diff options
Diffstat (limited to 'man')
152 files changed, 31256 insertions, 35575 deletions
diff --git a/man/binfmt.d.xml b/man/binfmt.d.xml index 55a3df0b73..5b63cfb4c3 100644 --- a/man/binfmt.d.xml +++ b/man/binfmt.d.xml @@ -20,83 +20,82 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> <refentry id="binfmt.d" conditional='ENABLE_BINFMT' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>binfmt.d</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>binfmt.d</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>binfmt.d</refname> - <refpurpose>Configure additional binary formats for - executables at boot</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/binfmt.d/*.conf</filename></para> - <para><filename>/run/binfmt.d/*.conf</filename></para> - <para><filename>/usr/lib/binfmt.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>At boot, - <citerefentry><refentrytitle>systemd-binfmt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - reads configuration files from the above directories - to register in the kernel additional binary - formats for executables.</para> - </refsect1> - - <refsect1> - <title>Configuration Format</title> - - <para>Each file contains a list of binfmt_misc kernel - binary format rules. Consult <ulink - url="https://www.kernel.org/doc/Documentation/binfmt_misc.txt">binfmt_misc.txt</ulink> - for more information on registration of additional - binary formats and how to write rules.</para> - - <para>Empty lines and lines beginning with ; and # are - ignored. Note that this means you may not use ; and # - as delimiter in binary format rules.</para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - - <refsect1> - <title>Example</title> - <example> - <title>/etc/binfmt.d/wine.conf example:</title> - - <programlisting># Start WINE on Windows executables + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>binfmt.d</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>binfmt.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>binfmt.d</refname> + <refpurpose>Configure additional binary formats for + executables at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/binfmt.d/*.conf</filename></para> + <para><filename>/run/binfmt.d/*.conf</filename></para> + <para><filename>/usr/lib/binfmt.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>At boot, + <citerefentry><refentrytitle>systemd-binfmt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + reads configuration files from the above directories to register + in the kernel additional binary formats for executables.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>Each file contains a list of binfmt_misc kernel binary + format rules. Consult <ulink + url="https://www.kernel.org/doc/Documentation/binfmt_misc.txt">binfmt_misc.txt</ulink> + for more information on registration of additional binary formats + and how to write rules.</para> + + <para>Empty lines and lines beginning with ; and # are ignored. + Note that this means you may not use ; and # as delimiter in + binary format rules.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/binfmt.d/wine.conf example:</title> + + <programlisting># Start WINE on Windows executables :DOSWin:M::MZ::/usr/bin/wine:</programlisting> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-binfmt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>wine</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-binfmt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>wine</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/bootchart.conf.xml b/man/bootchart.conf.xml index e11ccb52f6..8bafcbedcc 100644 --- a/man/bootchart.conf.xml +++ b/man/bootchart.conf.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -26,148 +26,149 @@ --> <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="confd" /> - <xi:include href="standard-conf.xml" xpointer="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> + 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="confd" /> + <xi:include href="standard-conf.xml" xpointer="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/bootctl.xml b/man/bootctl.xml index 52540221e9..00f54c73fc 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -20,95 +20,93 @@ --> <refentry id="bootctl" conditional='ENABLE_EFI' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>bootctl</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Kay</firstname> - <surname>Sievers</surname> - <email>kay@vrfy.org</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>bootctl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>bootctl</refname> - <refpurpose>Control the firmware and boot manager settings</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>bootctl</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="req">COMMAND</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>bootctl</command> may be used to - query or (in the future) change the firmware and boot - manager settings.</para> - - <para>Firmware information is available only on EFI - systems.</para> - - <para>Currently, only the <citerefentry project='gummiboot'><refentrytitle>gummiboot</refentrytitle><manvolnum>8</manvolnum></citerefentry> boot - manager implements the required boot loader interface - to provide complete boot manager information.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - <para>The following commands are understood:</para> - - <variablelist> - <varlistentry> - <term><command>status</command></term> - - <listitem><para>Show firmware and boot - manager information about the system, - including secure boot mode status and - selected firmware entry (where - available).</para></listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <ulink url="http://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot loader interface</ulink>, - <ulink url="http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot loader specification</ulink>, - <ulink url="http://www.freedesktop.org/wiki/Software/gummiboot/">gummiboot</ulink> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>bootctl</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Kay</firstname> + <surname>Sievers</surname> + <email>kay@vrfy.org</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>bootctl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>bootctl</refname> + <refpurpose>Control the firmware and boot manager settings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>bootctl</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="req">COMMAND</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>bootctl</command> may be used to query or (in the + future) change the firmware and boot manager settings.</para> + + <para>Firmware information is available only on EFI systems. + </para> + + <para>Currently, only the + <citerefentry project='gummiboot'><refentrytitle>gummiboot</refentrytitle><manvolnum>8</manvolnum></citerefentry> + boot manager implements the required boot loader interface to + provide complete boot manager information.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>status</command></term> + + <listitem><para>Show firmware and boot manager information + about the system, including secure boot mode status and + selected firmware entry (where available).</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot loader interface</ulink>, + <ulink url="http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot loader specification</ulink>, + <ulink url="http://www.freedesktop.org/wiki/Software/gummiboot/">gummiboot</ulink> + </para> + </refsect1> </refentry> diff --git a/man/bootup.xml b/man/bootup.xml index 0854b6c316..b5c3e1523a 100644 --- a/man/bootup.xml +++ b/man/bootup.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,301 +23,279 @@ <refentry id="bootup"> - <refentryinfo> - <title>bootup</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>bootup</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>bootup</refname> - <refpurpose>System bootup process</refpurpose> - </refnamediv> - - <refsect1> - <title>Description</title> - - <para>A number of different components are involved in - the system boot. Immediately after power-up, the - system BIOS will do minimal hardware initialization, - and hand control over to a boot loader stored on a - persistent storage device. This boot loader will then - invoke an OS kernel from disk (or the network). In the - Linux case, this kernel (optionally) extracts and - executes an initial RAM disk image (initrd), such as - generated by - <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - which looks for the root file system (possibly using - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for this). After the root file system is found and - mounted, the initrd hands over control to the host's - system manager (such as - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>) - stored on the OS image, which is then responsible for - probing all remaining hardware, mounting all necessary - file systems and spawning all configured - services.</para> - - <para>On shutdown, the system manager stops all - services, unmounts all file systems (detaching the - storage technologies backing them), and then - (optionally) jumps back into the initrd code which - unmounts/detaches the root file system and the storage - it resides on. As a last step, the system is powered down.</para> - - <para>Additional information about the system boot - process may be found in - <citerefentry project='man-pages'><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>System Manager Bootup</title> - - <para>At boot, the system manager on the OS image is - responsible for initializing the required file - systems, services and drivers that are necessary for - operation of the system. On - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - systems, this process is split up in various discrete - steps which are exposed as target units. (See - <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for detailed information about target units.) The - boot-up process is highly parallelized so that the - order in which specific target units are reached is not - deterministic, but still adheres to a limited amount - of ordering structure.</para> - - <para>When systemd starts up the system, it will - activate all units that are dependencies of - <filename>default.target</filename> (as well as - recursively all dependencies of these - dependencies). Usually, - <filename>default.target</filename> is simply an alias - of <filename>graphical.target</filename> or - <filename>multi-user.target</filename>, depending on - whether the system is configured for a graphical UI or - only for a text console. To enforce minimal ordering - between the units pulled in, a number of well-known - target units are available, as listed on - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - - <para>The following chart is a structural overview of - these well-known units and their position in the - boot-up logic. The arrows describe which units are - pulled in and ordered before which other units. Units - near the top are started before units nearer to the - bottom of the chart.</para> + <refentryinfo> + <title>bootup</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>bootup</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>bootup</refname> + <refpurpose>System bootup process</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>A number of different components are involved in the system + boot. Immediately after power-up, the system BIOS will do minimal + hardware initialization, and hand control over to a boot loader + stored on a persistent storage device. This boot loader will then + invoke an OS kernel from disk (or the network). In the Linux case, + this kernel (optionally) extracts and executes an initial RAM disk + image (initrd), such as generated by + <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + which looks for the root file system (possibly using + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for this). After the root file system is found and mounted, the + initrd hands over control to the host's system manager (such as + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>) + stored on the OS image, which is then responsible for probing all + remaining hardware, mounting all necessary file systems and + spawning all configured services.</para> + + <para>On shutdown, the system manager stops all services, unmounts + all file systems (detaching the storage technologies backing + them), and then (optionally) jumps back into the initrd code which + unmounts/detaches the root file system and the storage it resides + on. As a last step, the system is powered down.</para> + + <para>Additional information about the system boot process may be + found in + <citerefentry project='man-pages'><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>System Manager Bootup</title> + + <para>At boot, the system manager on the OS image is responsible + for initializing the required file systems, services and drivers + that are necessary for operation of the system. On + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + systems, this process is split up in various discrete steps which + are exposed as target units. (See + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for detailed information about target units.) The boot-up process + is highly parallelized so that the order in which specific target + units are reached is not deterministic, but still adheres to a + limited amount of ordering structure.</para> + + <para>When systemd starts up the system, it will activate all + units that are dependencies of <filename>default.target</filename> + (as well as recursively all dependencies of these dependencies). + Usually, <filename>default.target</filename> is simply an alias of + <filename>graphical.target</filename> or + <filename>multi-user.target</filename>, depending on whether the + system is configured for a graphical UI or only for a text + console. To enforce minimal ordering between the units pulled in, + a number of well-known target units are available, as listed on + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>The following chart is a structural overview of these + well-known units and their position in the boot-up logic. The + arrows describe which units are pulled in and ordered before which + other units. Units near the top are started before units nearer to + the bottom of the chart.</para> <programlisting>local-fs-pre.target - | - v + | + v (various mounts and (various swap (various cryptsetup - fsck services...) devices...) devices...) (various low-level (various low-level - | | | services: udevd, API VFS mounts: - v v v tmpfiles, random mqueue, configfs, + fsck services...) devices...) devices...) (various low-level (various low-level + | | | services: udevd, API VFS mounts: + v v v tmpfiles, random mqueue, configfs, local-fs.target swap.target cryptsetup.target seed, sysctl, ...) debugfs, ...) - | | | | | - \__________________|_________________ | ___________________|____________________/ - \|/ - v - sysinit.target - | - ____________________________________/|\________________________________________ - / | | | \ - | | | | | - v v | v v - (various (various | (various rescue.service - timers...) paths...) | sockets...) | - | | | | v - v v | v <emphasis>rescue.target</emphasis> - timers.target paths.target | sockets.target - | | | | - v |_________________ | ___________________/ - \|/ - v - basic.target - | - ____________________________________/| emergency.service - / | | | - | | | v - v v v <emphasis>emergency.target</emphasis> - display- (various system (various system - manager.service services services) - | required for | - | graphical UIs) v - | | <emphasis>multi-user.target</emphasis> - | | | - \_________________ | _________________/ - \|/ - v - <emphasis>graphical.target</emphasis></programlisting> - - <para>Target units that are commonly used as boot - targets are <emphasis>emphasized</emphasis>. These - units are good choices as goal targets, for - example by passing them to the - <varname>systemd.unit=</varname> kernel command line - option (see - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>) - or by symlinking <filename>default.target</filename> - to them.</para> - - <para><filename>timers.target</filename> is pulled-in - by <filename>basic.target</filename> asynchronously. - This allows timers units to depend on services which - become only available later in boot.</para> - </refsect1> - - <refsect1> - <title>Bootup in the Initial RAM Disk (initrd)</title> - <para>The initial RAM disk implementation (initrd) can - be set up using systemd as well. In this case, boot up - inside the initrd follows the following - structure.</para> - - <para>The default target in the initrd is - <filename>initrd.target</filename>. The bootup process - begins 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>. If the root device - can be mounted at <filename>/sysroot</filename>, the - <filename>sysroot.mount</filename> unit becomes active - and <filename>initrd-root-fs.target</filename> is - reached. The service - <filename>initrd-parse-etc.service</filename> scans - <filename>/sysroot/etc/fstab</filename> for a possible - <filename>/usr</filename> mount point and additional - entries marked with the - <emphasis>x-initrd.mount</emphasis> option. All - entries found are mounted below - <filename>/sysroot</filename>, and - <filename>initrd-fs.target</filename> is reached. The - service <filename>initrd-cleanup.service</filename> - isolates to the - <filename>initrd-switch-root.target</filename>, where - cleanup services can run. As the very last step, the - <filename>initrd-switch-root.service</filename> is - activated, which will cause the system to switch its - root to <filename>/sysroot</filename>. - </para> - -<programlisting> : (beginning identical to above) - : - v - basic.target - | emergency.service - ______________________/| | - / | v - | sysroot.mount <emphasis>emergency.target</emphasis> - | | - | v - | initrd-root-fs.target - | | - | v - v initrd-parse-etc.service - (custom initrd | - services...) v - | (sysroot-usr.mount and - | various mounts marked - | with fstab option - | x-initrd.mount...) - | | - | v - | initrd-fs.target - \______________________ | - \| - v - initrd.target - | - v - initrd-cleanup.service - isolates to - initrd-switch-root.target - | - v - ______________________/| - / v - | initrd-udevadm-cleanup-db.service - v | - (custom initrd | - services...) | - \______________________ | - \| - v - initrd-switch-root.target - | - v - initrd-switch-root.service - | - v - Transition to Host OS</programlisting> - </refsect1> - - - <refsect1> - <title>System Manager Shutdown</title> - - <para>System shutdown with systemd also consists of - various target units with some minimal ordering - structure applied:</para> - - - - -<programlisting> (conflicts with (conflicts with - all system all file system - services) mounts, swaps, - | cryptsetup - | devices, ...) - | | - v v - shutdown.target umount.target - | | - \_______ ______/ - \ / - v - (various low-level - services) - | - v - final.target - | - _____________________________________/ \_________________________________ - / | | \ - | | | | - v v v v + | | | | | + \__________________|_________________ | ___________________|____________________/ + \|/ + v + sysinit.target + | + ____________________________________/|\________________________________________ + / | | | \ + | | | | | + v v | v v + (various (various | (various rescue.service + timers...) paths...) | sockets...) | + | | | | v + v v | v <emphasis>rescue.target</emphasis> + timers.target paths.target | sockets.target + | | | | + v |_________________ | ___________________/ + \|/ + v + basic.target + | + ____________________________________/| emergency.service + / | | | + | | | v + v v v <emphasis>emergency.target</emphasis> + display- (various system (various system + manager.service services services) + | required for | + | graphical UIs) v + | | <emphasis>multi-user.target</emphasis> + | | | + \_________________ | _________________/ + \|/ + v + <emphasis>graphical.target</emphasis></programlisting> + + <para>Target units that are commonly used as boot targets are + <emphasis>emphasized</emphasis>. These units are good choices as + goal targets, for example by passing them to the + <varname>systemd.unit=</varname> kernel command line option (see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>) + or by symlinking <filename>default.target</filename> to + them.</para> + + <para><filename>timers.target</filename> is pulled-in by + <filename>basic.target</filename> asynchronously. This allows + timers units to depend on services which become only available + later in boot.</para> + </refsect1> + + <refsect1> + <title>Bootup in the Initial RAM Disk (initrd)</title> + <para>The initial RAM disk implementation (initrd) can be set up + using systemd as well. In this case, boot up inside the initrd + follows the following structure.</para> + + <para>The default target in the initrd is + <filename>initrd.target</filename>. The bootup process begins + 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>. + If the root device can be mounted at + <filename>/sysroot</filename>, the + <filename>sysroot.mount</filename> unit becomes active and + <filename>initrd-root-fs.target</filename> is reached. The service + <filename>initrd-parse-etc.service</filename> scans + <filename>/sysroot/etc/fstab</filename> for a possible + <filename>/usr</filename> mount point and additional entries + marked with the <emphasis>x-initrd.mount</emphasis> option. All + entries found are mounted below <filename>/sysroot</filename>, and + <filename>initrd-fs.target</filename> is reached. The service + <filename>initrd-cleanup.service</filename> isolates to the + <filename>initrd-switch-root.target</filename>, where cleanup + services can run. As the very last step, the + <filename>initrd-switch-root.service</filename> is activated, + which will cause the system to switch its root to + <filename>/sysroot</filename>. + </para> + +<programlisting> : (beginning identical to above) + : + v + basic.target + | emergency.service + ______________________/| | + / | v + | sysroot.mount <emphasis>emergency.target</emphasis> + | | + | v + | initrd-root-fs.target + | | + | v + v initrd-parse-etc.service + (custom initrd | + services...) v + | (sysroot-usr.mount and + | various mounts marked + | with fstab option + | x-initrd.mount...) + | | + | v + | initrd-fs.target + \______________________ | + \| + v + initrd.target + | + v + initrd-cleanup.service + isolates to + initrd-switch-root.target + | + v + ______________________/| + / v + | initrd-udevadm-cleanup-db.service + v | + (custom initrd | + services...) | + \______________________ | + \| + v + initrd-switch-root.target + | + v + initrd-switch-root.service + | + v + Transition to Host OS</programlisting> + </refsect1> + + + <refsect1> + <title>System Manager Shutdown</title> + + <para>System shutdown with systemd also consists of various target + units with some minimal ordering structure applied:</para> + +<programlisting> (conflicts with (conflicts with + all system all file system + services) mounts, swaps, + | cryptsetup + | devices, ...) + | | + v v + shutdown.target umount.target + | | + \_______ ______/ + \ / + v + (various low-level + services) + | + v + final.target + | + _____________________________________/ \_________________________________ + / | | \ + | | | | + v v v v systemd-reboot.service systemd-poweroff.service systemd-halt.service systemd-kexec.service - | | | | - v v v v - <emphasis>reboot.target</emphasis> <emphasis>poweroff.target</emphasis> <emphasis>halt.target</emphasis> <emphasis>kexec.target</emphasis></programlisting> - - <para>Commonly used system shutdown targets are <emphasis>emphasized</emphasis>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + | | | | + v v v v + <emphasis>reboot.target</emphasis> <emphasis>poweroff.target</emphasis> <emphasis>halt.target</emphasis> <emphasis>kexec.target</emphasis></programlisting> + + <para>Commonly used system shutdown targets are + <emphasis>emphasized</emphasis>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml index 929af196d1..efbc655a76 100644 --- a/man/coredumpctl.xml +++ b/man/coredumpctl.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,227 +22,216 @@ --> <refentry id="coredumpctl" conditional='ENABLE_COREDUMP' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>coredumpctl</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>coredumpctl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>coredumpctl</refname> - <refpurpose>Retrieve coredumps from the journal</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>coredumpctl</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="req">COMMAND</arg> - <arg choice="opt" rep="repeat">PID|COMM|EXE|MATCH</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <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> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--no-legend</option></term> - - <listitem><para>Do not print column headers. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-1</option></term> - - <listitem><para>Show information of a - single coredump only, instead of - listing all known coredumps. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-F</option></term> - <term><option>--field=</option></term> - - <listitem><para>Print all possible - data values the specified field - takes in matching coredump entries of the - journal.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-o</option></term> - <term><option>--output=FILE</option></term> - - <listitem><para>Write the core to - <option>FILE</option>.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - - </variablelist> - - <para>The following commands are understood:</para> - - <variablelist> - <varlistentry> - <term><command>list</command></term> - - <listitem><para>List coredumps - captured in the journal matching - specified characteristics. If no - command is specified, this is the - implied default.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>info</command></term> - - <listitem><para>Show detailed - information about coredumps 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 output, - unless an output file is specified with - <option>-o/--output</option>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>gdb</command></term> - - <listitem><para>Invoke the GNU - debugger on the last coredump matching - specified characteristics. - </para></listitem> - </varlistentry> - - </variablelist> - - </refsect1> - - <refsect1> - <title>Matching</title> - - <para>A match can be:</para> - - <variablelist> - <varlistentry> - <term><replaceable>PID</replaceable></term> - - <listitem><para>Process ID of the - process that dumped - core. An integer.</para></listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>COMM</replaceable></term> - - <listitem><para>Name of the executable - (matches <option>COREDUMP_COMM=</option>). - Must not contain slashes. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>EXE</replaceable></term> - - <listitem><para>Path to the executable - (matches <option>COREDUMP_EXE=</option>). - Must contain at least one slash. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><replaceable>MATCH</replaceable></term> - - <listitem><para>General journalctl predicates - (see <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>). - Must contain an equal sign. - </para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <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 failure. - </para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>List all the coredumps of a program named foo</title> - - <programlisting># coredumpctl list foo</programlisting> - </example> - - <example> - <title>Invoke gdb on the last coredump</title> - - <programlisting># coredumpctl gdb</programlisting> - </example> - - <example> - <title>Show information about a process that dumped core, matching by its PID 6654</title> - - <programlisting># coredumpctl info 6654</programlisting> - </example> - - <example> - <title>Extract the last coredump of /usr/bin/bar to a file named bar.coredump</title> - - <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>coredumpctl</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>coredumpctl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>coredumpctl</refname> + <refpurpose>Retrieve coredumps from the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>coredumpctl</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="req">COMMAND</arg> + <arg choice="opt" rep="repeat">PID|COMM|EXE|MATCH</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <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> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--no-legend</option></term> + + <listitem><para>Do not print column headers. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-1</option></term> + + <listitem><para>Show information of a single coredump only, + instead of listing all known coredumps. </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-F</option></term> + <term><option>--field=</option></term> + + <listitem><para>Print all possible data values the specified + field takes in matching coredump entries of the + journal.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-o</option></term> + <term><option>--output=FILE</option></term> + + <listitem><para>Write the core to <option>FILE</option>. + </para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + <xi:include href="standard-options.xml" xpointer="no-pager" /> + + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>list</command></term> + + <listitem><para>List coredumps captured in the journal + matching specified characteristics. If no command is + specified, this is the implied default.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>info</command></term> + + <listitem><para>Show detailed information about coredumps + 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 + output, unless an output file is specified with + <option>-o/--output</option>. </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>gdb</command></term> + + <listitem><para>Invoke the GNU debugger on the last coredump + matching specified characteristics. </para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>Matching</title> + + <para>A match can be:</para> + + <variablelist> + <varlistentry> + <term><replaceable>PID</replaceable></term> + + <listitem><para>Process ID of the + process that dumped + core. An integer.</para></listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>COMM</replaceable></term> + + <listitem><para>Name of the executable (matches + <option>COREDUMP_COMM=</option>). Must not contain slashes. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>EXE</replaceable></term> + + <listitem><para>Path to the executable (matches + <option>COREDUMP_EXE=</option>). Must contain at least one + slash. </para></listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>MATCH</replaceable></term> + + <listitem><para>General journalctl predicates (see + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>). + Must contain an equal sign. </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <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 + failure. + </para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>List all the coredumps of a program named foo</title> + + <programlisting># coredumpctl list foo</programlisting> + </example> + + <example> + <title>Invoke gdb on the last coredump</title> + + <programlisting># coredumpctl gdb</programlisting> + </example> + + <example> + <title>Show information about a process that dumped core, + matching by its PID 6654</title> + + <programlisting># coredumpctl info 6654</programlisting> + </example> + + <example> + <title>Extract the last coredump 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> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/crypttab.xml b/man/crypttab.xml index 1a1002ecf4..aeacc57973 100644 --- a/man/crypttab.xml +++ b/man/crypttab.xml @@ -27,389 +27,366 @@ --> <refentry id="crypttab" conditional='HAVE_LIBCRYPTSETUP'> - <refentryinfo> - <title>crypttab</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Documentation</contrib> - <firstname>Miloslav</firstname> - <surname>Trmac</surname> - <email>mitr@redhat.com</email> - </author> - <author> - <contrib>Documentation</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>crypttab</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>crypttab</refname> - <refpurpose>Configuration for encrypted block devices</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/crypttab</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <filename>/etc/crypttab</filename> file - describes encrypted block devices that are set up - during system boot.</para> - - <para>Empty lines and lines starting with the <literal>#</literal> - character are ignored. Each of the remaining lines - describes one encrypted block device, fields on the - line are delimited by white space. The first two - fields are mandatory, the remaining two are - optional.</para> - - <para>Setting up encrypted block devices using this file - supports three encryption modes: LUKS, TrueCrypt and plain. - See <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for more information about each mode. When no mode is specified - in the options field and the block device contains a LUKS - signature, it is opened as a LUKS device; otherwise, it is - assumed to be in raw dm-crypt (plain mode) format.</para> - - <para>The first field contains the name of the - resulting encrypted block device; the device is set up - within <filename>/dev/mapper/</filename>.</para> - - <para>The second field contains a path to the - underlying block device or file, or a specification of a block - device via <literal>UUID=</literal> followed by the - UUID.</para> - - <para>The third field specifies the encryption - password. If the field is not present or the password - is set to <literal>none</literal> or <literal>-</literal>, - the password has to be manually entered during system boot. - Otherwise, the field is interpreted as a absolute path to - a file containing the encryption password. For swap encryption, - <filename>/dev/urandom</filename> or the hardware - device <filename>/dev/hw_random</filename> can be used - as the password file; using - <filename>/dev/random</filename> may prevent boot - completion if the system does not have enough entropy - to generate a truly random encryption key.</para> - - <para>The fourth field, if present, is a - comma-delimited list of options. The following - options are recognized:</para> - - <variablelist class='fstab-options'> - - <varlistentry> - <term><option>discard</option></term> - - <listitem><para>Allow discard requests to be - passed through the encrypted block device. This - improves performance on SSD storage but has - security implications.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>cipher=</option></term> - - <listitem><para>Specifies the cipher to use. See - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default value of - this option. A cipher with unpredictable IV - values, such as <literal>aes-cbc-essiv:sha256</literal>, - is recommended.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>hash=</option></term> - - <listitem><para>Specifies the hash to use for - password hashing. See - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default value of - this option.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>header=</option></term> - - <listitem><para>Use a detached (separated) - metadata device or file where the LUKS header - is stored. This option is only relevant for - LUKS devices. See - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default value of - this option.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>keyfile-offset=</option></term> - - <listitem><para>Specifies the number of bytes to - skip at the start of the key file. See - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default value of - this option.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>keyfile-size=</option></term> - - <listitem><para>Specifies the maximum number - of bytes to read from the key file. See - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default value of - this option. This option is ignored in plain - encryption mode, as the key file size is then - given by the key size.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>key-slot=</option></term> - - <listitem><para>Specifies the key slot to - compare the passphrase or key against. - If the key slot does not match the given - passphrase or key, but another would, the - setup of the device will fail regardless. - This option implies <option>luks</option>. See - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values. The default is to try - all key slots in sequential order.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>luks</option></term> - - <listitem><para>Force LUKS mode. When this mode - is used, the following options are ignored since - they are provided by the LUKS header on the - device: <option>cipher=</option>, - <option>hash=</option>, - <option>size=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>noauto</option></term> - - <listitem><para>This device will not be - automatically unlocked on boot.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>nofail</option></term> - - <listitem><para>The system will not wait for the - device to show up and be unlocked at boot, and - not fail the boot if it does not show up.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>plain</option></term> - - <listitem><para>Force plain encryption mode.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>read-only</option></term><term><option>readonly</option></term> - - <listitem><para>Set up the encrypted block - device in read-only mode.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>size=</option></term> - - <listitem><para>Specifies the key size - in bits. See - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for possible values and the default value of - this option.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>swap</option></term> - - <listitem><para>The encrypted block device will - be used as a swap device, and will be formatted - accordingly after setting up the encrypted - block device, with - <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - This option implies <option>plain</option>.</para> - - <para>WARNING: Using the <option>swap</option> - option will destroy the contents of the named - partition during every boot, so make sure the - underlying block device is specified correctly.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>tcrypt</option></term> - - <listitem><para>Use TrueCrypt encryption mode. - When this mode is used, the following options are - ignored since they are provided by the TrueCrypt - header on the device or do not apply: - <option>cipher=</option>, - <option>hash=</option>, - <option>keyfile-offset=</option>, - <option>keyfile-size=</option>, - <option>size=</option>.</para> - - <para>When this mode is used, the passphrase is - read from the key file given in the third field. - Only the first line of this file is read, - excluding the new line character.</para> - - <para>Note that the TrueCrypt format uses both - passphrase and key files to derive a password - for the volume. Therefore, the passphrase and - all key files need to be provided. Use - <option>tcrypt-keyfile=</option> to provide - the absolute path to all key files. When using - an empty passphrase in combination with one or - more key files, use <literal>/dev/null</literal> - as the password file in the third field.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>tcrypt-hidden</option></term> - - <listitem><para>Use the hidden TrueCrypt volume. - This option implies <option>tcrypt</option>.</para> - - <para>This will map the hidden volume that is - inside of the volume provided in the second - field. Please note that there is no protection - for the hidden volume if the outer volume is - mounted instead. See - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for more information on this limitation.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>tcrypt-keyfile=</option></term> - - <listitem><para>Specifies the absolute path to a - key file to use for a TrueCrypt volume. This - implies <option>tcrypt</option> and can be - used more than once to provide several key - files.</para> - - <para>See the entry for <option>tcrypt</option> - on the behavior of the passphrase and key files - when using TrueCrypt encryption mode.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>tcrypt-system</option></term> - - <listitem><para>Use TrueCrypt in system - encryption mode. This option implies - <option>tcrypt</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>timeout=</option></term> - - <listitem><para>Specifies the timeout for - querying for a password. If no unit is - specified, seconds is used. Supported units are - s, ms, us, min, h, d. A timeout of 0 waits - indefinitely (which is the default).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>x-systemd.device-timeout=</option></term> - - <listitem><para>Specifies how long - systemd should wait for a device to - show up before giving up on the - entry. The argument is a time in - seconds or explicitly specified - units of <literal>s</literal>, - <literal>min</literal>, - <literal>h</literal>, - <literal>ms</literal>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>tmp</option></term> - - <listitem><para>The encrypted block device will - be prepared for using it as <filename>/tmp</filename>; - it will be formatted using - <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - This option implies <option>plain</option>.</para> - - <para>WARNING: Using the <option>tmp</option> - option will destroy the contents of the named - partition during every boot, so make sure the - underlying block device is specified correctly.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>tries=</option></term> - - <listitem><para>Specifies the maximum number of - times the user is queried for a password. - The default is 3. If set to 0, the user is - queried for a password indefinitely.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>verify</option></term> - - <listitem><para> If the encryption password is - read from console, it has to be entered twice to - prevent typos.</para></listitem> - </varlistentry> - - </variablelist> - - <para>At early boot and when the system manager - configuration is reloaded, this file is translated into - native systemd units - by <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>Example</title> - <example> - <title>/etc/crypttab example</title> - <para>Set up four encrypted block devices. One using - LUKS for normal storage, another one for usage as a swap - device and two TrueCrypt volumes.</para> - - <programlisting>luks UUID=2505567a-9e27-4efe-a4d5-15ad146c258b -swap /dev/sda7 /dev/urandom swap + <refentryinfo> + <title>crypttab</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Documentation</contrib> + <firstname>Miloslav</firstname> + <surname>Trmac</surname> + <email>mitr@redhat.com</email> + </author> + <author> + <contrib>Documentation</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>crypttab</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>crypttab</refname> + <refpurpose>Configuration for encrypted block devices</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/crypttab</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/crypttab</filename> file describes + encrypted block devices that are set up during system boot.</para> + + <para>Empty lines and lines starting with the <literal>#</literal> + character are ignored. Each of the remaining lines describes one + encrypted block device, fields on the line are delimited by white + space. The first two fields are mandatory, the remaining two are + optional.</para> + + <para>Setting up encrypted block devices using this file supports + three encryption modes: LUKS, TrueCrypt and plain. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more information about each mode. When no mode is specified in + the options field and the block device contains a LUKS signature, + it is opened as a LUKS device; otherwise, it is assumed to be in + raw dm-crypt (plain mode) format.</para> + + <para>The first field contains the name of the resulting encrypted + block device; the device is set up within + <filename>/dev/mapper/</filename>.</para> + + <para>The second field contains a path to the underlying block + device or file, or a specification of a block device via + <literal>UUID=</literal> followed by the UUID.</para> + + <para>The third field specifies the encryption password. If the + field is not present or the password is set to + <literal>none</literal> or <literal>-</literal>, the password has + to be manually entered during system boot. Otherwise, the field is + interpreted as a absolute path to a file containing the encryption + password. For swap encryption, <filename>/dev/urandom</filename> + or the hardware device <filename>/dev/hw_random</filename> can be + used as the password file; using <filename>/dev/random</filename> + may prevent boot completion if the system does not have enough + entropy to generate a truly random encryption key.</para> + + <para>The fourth field, if present, is a comma-delimited list of + options. The following options are recognized:</para> + + <variablelist class='fstab-options'> + + <varlistentry> + <term><option>discard</option></term> + + <listitem><para>Allow discard requests to be passed through + the encrypted block device. This improves performance on SSD + storage but has security implications.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>cipher=</option></term> + + <listitem><para>Specifies the cipher to use. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this option. A + cipher with unpredictable IV values, such as + <literal>aes-cbc-essiv:sha256</literal>, is + recommended.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>hash=</option></term> + + <listitem><para>Specifies the hash to use for password + hashing. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this + option.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>header=</option></term> + + <listitem><para>Use a detached (separated) metadata device or + file where the LUKS header is stored. This option is only + relevant for LUKS devices. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this + option.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>keyfile-offset=</option></term> + + <listitem><para>Specifies the number of bytes to skip at the + start of the key file. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this + option.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>keyfile-size=</option></term> + + <listitem><para>Specifies the maximum number of bytes to read + from the key file. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this option. This + option is ignored in plain encryption mode, as the key file + size is then given by the key size.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>key-slot=</option></term> + + <listitem><para>Specifies the key slot to compare the + passphrase or key against. If the key slot does not match the + given passphrase or key, but another would, the setup of the + device will fail regardless. This option implies + <option>luks</option>. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values. The default is to try all key slots in + sequential order.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>luks</option></term> + + <listitem><para>Force LUKS mode. When this mode is used, the + following options are ignored since they are provided by the + LUKS header on the device: <option>cipher=</option>, + <option>hash=</option>, + <option>size=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>noauto</option></term> + + <listitem><para>This device will not be automatically unlocked + on boot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>nofail</option></term> + + <listitem><para>The system will not wait for the device to + show up and be unlocked at boot, and not fail the boot if it + does not show up.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>plain</option></term> + + <listitem><para>Force plain encryption mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>read-only</option></term><term><option>readonly</option></term> + + <listitem><para>Set up the encrypted block device in read-only + mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>size=</option></term> + + <listitem><para>Specifies the key size in bits. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for possible values and the default value of this + option.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>swap</option></term> + + <listitem><para>The encrypted block device will be used as a + swap device, and will be formatted accordingly after setting + up the encrypted block device, with + <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + This option implies <option>plain</option>.</para> + + <para>WARNING: Using the <option>swap</option> option will + destroy the contents of the named partition during every boot, + so make sure the underlying block device is specified + correctly.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>tcrypt</option></term> + + <listitem><para>Use TrueCrypt encryption mode. When this mode + is used, the following options are ignored since they are + provided by the TrueCrypt header on the device or do not + apply: + <option>cipher=</option>, + <option>hash=</option>, + <option>keyfile-offset=</option>, + <option>keyfile-size=</option>, + <option>size=</option>.</para> + + <para>When this mode is used, the passphrase is read from the + key file given in the third field. Only the first line of this + file is read, excluding the new line character.</para> + + <para>Note that the TrueCrypt format uses both passphrase and + key files to derive a password for the volume. Therefore, the + passphrase and all key files need to be provided. Use + <option>tcrypt-keyfile=</option> to provide the absolute path + to all key files. When using an empty passphrase in + combination with one or more key files, use + <literal>/dev/null</literal> as the password file in the third + field.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>tcrypt-hidden</option></term> + + <listitem><para>Use the hidden TrueCrypt volume. This option + implies <option>tcrypt</option>.</para> + + <para>This will map the hidden volume that is inside of the + volume provided in the second field. Please note that there is + no protection for the hidden volume if the outer volume is + mounted instead. See + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more information on this limitation.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>tcrypt-keyfile=</option></term> + + <listitem><para>Specifies the absolute path to a key file to + use for a TrueCrypt volume. This implies + <option>tcrypt</option> and can be used more than once to + provide several key files.</para> + + <para>See the entry for <option>tcrypt</option> on the + behavior of the passphrase and key files when using TrueCrypt + encryption mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>tcrypt-system</option></term> + + <listitem><para>Use TrueCrypt in system encryption mode. This + option implies <option>tcrypt</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>timeout=</option></term> + + <listitem><para>Specifies the timeout for querying for a + password. If no unit is specified, seconds is used. Supported + units are s, ms, us, min, h, d. A timeout of 0 waits + indefinitely (which is the default).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.device-timeout=</option></term> + + <listitem><para>Specifies how long systemd should wait for a + device to show up before giving up on the entry. The argument + is a time in seconds or explicitly specified units of + <literal>s</literal>, + <literal>min</literal>, + <literal>h</literal>, + <literal>ms</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>tmp</option></term> + + <listitem><para>The encrypted block device will be prepared + for using it as <filename>/tmp</filename>; it will be + formatted using + <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + This option implies <option>plain</option>.</para> + + <para>WARNING: Using the <option>tmp</option> option will + destroy the contents of the named partition during every boot, + so make sure the underlying block device is specified + correctly.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>tries=</option></term> + + <listitem><para>Specifies the maximum number of times the user + is queried for a password. The default is 3. If set to 0, the + user is queried for a password indefinitely.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>verify</option></term> + + <listitem><para> If the encryption password is read from + console, it has to be entered twice to prevent + typos.</para></listitem> + </varlistentry> + + </variablelist> + + <para>At early boot and when the system manager configuration is + reloaded, this file is translated into native systemd units by + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/crypttab example</title> + <para>Set up four encrypted block devices. One using LUKS for + normal storage, another one for usage as a swap device and two + TrueCrypt volumes.</para> + + <programlisting>luks UUID=2505567a-9e27-4efe-a4d5-15ad146c258b +swap /dev/sda7 /dev/urandom swap truecrypt /dev/sda2 /etc/container_password tcrypt -hidden /mnt/tc_hidden /dev/null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile</programlisting> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> +hidden /mnt/tc_hidden /dev/null tcrypt-hidden,tcrypt-keyfile=/etc/keyfile</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mke2fs</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/daemon.xml b/man/daemon.xml index 5d3a9903da..a8bbfc055b 100644 --- a/man/daemon.xml +++ b/man/daemon.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,739 +23,571 @@ <refentry id="daemon"> - <refentryinfo> - <title>daemon</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>daemon</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>daemon</refname> - <refpurpose>Writing and packaging system daemons</refpurpose> - </refnamediv> - - <refsect1> - <title>Description</title> - - <para>A daemon is a service process that runs in the - background and supervises the system or provides - functionality to other processes. Traditionally, - daemons are implemented following a scheme originating - in SysV Unix. Modern daemons should follow a simpler - yet more powerful scheme (here called "new-style" - daemons), as implemented by - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This - manual page covers both schemes, and in - particular includes recommendations for daemons that - shall be included in the systemd init system.</para> - - <refsect2> - <title>SysV Daemons</title> - - <para>When a traditional SysV daemon - starts, it should execute the following steps - as part of the initialization. Note that these - steps are unnecessary for new-style daemons (see below), - and should only be implemented if compatibility - with SysV is essential.</para> - - <orderedlist> - <listitem><para>Close all open file - descriptors except standard input, output, - and error (i.e. the first three file - descriptors 0, 1, 2). This ensures - that no accidentally passed file - descriptor stays around in the daemon - process. On Linux, this is best - implemented by iterating through - <filename>/proc/self/fd</filename>, - with a fallback of iterating from file - descriptor 3 to the value returned by - <function>getrlimit()</function> for - <constant>RLIMIT_NOFILE</constant>. - </para></listitem> - - <listitem><para>Reset all signal - handlers to their default. This is - best done by iterating through the - available signals up to the limit of - <constant>_NSIG</constant> and resetting them to - <constant>SIG_DFL</constant>.</para></listitem> - - <listitem><para>Reset the signal mask - using - <function>sigprocmask()</function>.</para></listitem> - - <listitem><para>Sanitize the - environment block, removing or - resetting environment variables that - might negatively impact daemon - runtime.</para></listitem> - - <listitem><para>Call <function>fork()</function>, - to create a background - process.</para></listitem> - - <listitem><para>In the child, call - <function>setsid()</function> to - detach from any terminal and create an - independent session.</para></listitem> - - <listitem><para>In the child, call - <function>fork()</function> again, to - ensure that the daemon can never re-acquire - a terminal again.</para></listitem> - - <listitem><para>Call <function>exit()</function> in the - first child, so that only the second - child (the actual daemon process) - stays around. This ensures that the - daemon process is re-parented to - init/PID 1, as all daemons should - be.</para></listitem> - - <listitem><para>In the daemon process, - connect <filename>/dev/null</filename> - to standard input, output, and error. - </para></listitem> - - <listitem><para>In the daemon process, - reset the umask to 0, so that the file - modes passed to <function>open()</function>, <function>mkdir()</function> and - suchlike directly control the access - mode of the created files and - directories.</para></listitem> - - <listitem><para>In the daemon process, - change the current directory to the - root directory (/), in order to avoid - that the daemon involuntarily - blocks mount points from being - unmounted.</para></listitem> - - <listitem><para>In the daemon process, - write the daemon PID (as returned by - <function>getpid()</function>) to a - PID file, for example - <filename>/run/foobar.pid</filename> - (for a hypothetical daemon "foobar") - to ensure that the daemon cannot be - started more than once. This must be - implemented in race-free fashion so - that the PID file is only updated when - it is verified at the same time that - the PID previously stored in the PID - file no longer exists or belongs to a - foreign process.</para></listitem> - - <listitem><para>In the daemon process, - drop privileges, if possible and - applicable.</para></listitem> - - <listitem><para>From the daemon - process, notify the original process - started that initialization is - complete. This can be implemented via - an unnamed pipe or similar - communication channel that is created - before the first - <function>fork()</function> and hence - available in both the original and the - daemon process.</para></listitem> - - <listitem><para>Call - <function>exit()</function> in the - original process. The process that - invoked the daemon must be able to - rely on that this - <function>exit()</function> happens - after initialization is complete and - all external communication channels - are established and - accessible.</para></listitem> - </orderedlist> - - <para>The BSD <function>daemon()</function> function should not be - used, as it implements only a subset of these steps.</para> - - <para>A daemon that needs to provide - compatibility with SysV systems should - implement the scheme pointed out - above. However, it is recommended to make this - behavior optional and configurable via a - command line argument to ease debugging as - well as to simplify integration into systems - using systemd.</para> - </refsect2> - - <refsect2> - <title>New-Style Daemons</title> - - <para>Modern services for Linux should be - implemented as new-style daemons. This makes it - easier to supervise and control them at - runtime and simplifies their - implementation.</para> - - <para>For developing a new-style daemon, none - of the initialization steps recommended for - SysV daemons need to be implemented. New-style - init systems such as systemd make all of them - redundant. Moreover, since some of these steps - interfere with process monitoring, file - descriptor passing and other 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> - - <para>It is recommended for new-style daemons - to implement the following:</para> - - <orderedlist> - <listitem><para>If <constant>SIGTERM</constant> is - received, shut down the daemon and - exit cleanly.</para></listitem> - - <listitem><para>If <constant>SIGHUP</constant> is received, - reload the configuration files, if - this applies.</para></listitem> - - <listitem><para>Provide a correct exit - code from the main daemon process, as - this is used by the init system to - detect service errors and problems. It - is recommended to follow the exit code - scheme as defined in the <ulink - url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB - recommendations for SysV init - scripts</ulink>.</para></listitem> - - <listitem><para>If possible and - applicable, expose the daemon's control - interface via the D-Bus IPC system and - grab a bus name as last step of - initialization.</para></listitem> - - <listitem><para>For integration in - systemd, provide a - <filename>.service</filename> unit - file that carries information about - starting, stopping and otherwise - maintaining the daemon. See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para></listitem> - - <listitem><para>As much as possible, - rely on the init system's - functionality to limit the access of - the daemon to files, services and - other resources, i.e. in the case of - systemd, rely on systemd's resource - limit control instead of implementing - your own, rely on systemd's privilege - dropping code instead of implementing - it in the daemon, and similar. See - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the available - controls.</para></listitem> - - <listitem><para>If D-Bus is used, make - your daemon 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 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 details.</para></listitem> - - <listitem><para>If your daemon - provides services to other local - processes or remote clients via a - socket, it should be made - socket-activatable following the - scheme pointed out below. Like D-Bus - activation, this enables on-demand - starting of services as well as it - allows improved parallelization of - service start-up. Also, for state-less - protocols (such as syslog, DNS), a - daemon implementing socket-based - activation can be restarted without - losing a single request. See below for - details.</para></listitem> - - <listitem><para>If applicable, a daemon - should notify the init system about - startup completion or status updates - via the - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - interface.</para></listitem> - - <listitem><para>Instead of using the - <function>syslog()</function> call to - log directly to the system syslog - service, a new-style daemon may choose - to simply log to standard error via - <function>fprintf()</function>, which - is then forwarded to syslog by the - init system. If log levels are - necessary, these can be encoded by - prefixing individual log lines with - strings like <literal><4></literal> (for log - level 4 "WARNING" in the syslog - priority scheme), following a similar - style as the Linux kernel's - <function>printk()</function> level - system. For details, see - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - </orderedlist> - - <para>These recommendations are similar but - not identical to the <ulink - url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">Apple - MacOS X Daemon Requirements</ulink>.</para> - </refsect2> - - </refsect1> - <refsect1> - <title>Activation</title> - - <para>New-style init systems provide multiple - additional mechanisms to activate services, as - detailed below. It is common that services are - configured to be activated via more than one mechanism - at the same time. An example for systemd: - <filename>bluetoothd.service</filename> might get - activated either when Bluetooth hardware is plugged - in, or when an application accesses its programming - interfaces via D-Bus. Or, a print server daemon might - get activated when traffic arrives at an IPP port, or - when a printer is plugged in, or when a file is queued - in the printer spool directory. Even for services that - are intended to be started on system bootup - unconditionally, it is a good idea to implement some of - the various activation schemes outlined below, in - order to maximize parallelization. If a daemon - implements a D-Bus service or listening socket, - implementing the full bus and socket activation scheme - allows starting of the daemon with its clients in - parallel (which speeds up boot-up), since all its - communication channels are established already, and no - request is lost because client requests will be queued - by the bus system (in case of D-Bus) or the kernel (in - case of sockets) until the activation is - completed.</para> - - <refsect2> - <title>Activation on Boot</title> - - <para>Old-style daemons are usually activated - exclusively on boot (and manually by the - administrator) via SysV init scripts, as - detailed in the <ulink - url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB - Linux Standard Base Core - Specification</ulink>. This method of - activation is supported ubiquitously on Linux - init systems, both old-style and new-style - systems. Among other issues, SysV init scripts - have the disadvantage of involving shell - scripts in the boot process. New-style init - systems generally employ updated versions of - activation, both during boot-up and during - runtime and using more minimal service - description files.</para> - - <para>In systemd, if the developer or - administrator wants to make sure that a service or - other unit is activated automatically on boot, - it is recommended to place a symlink to the - unit file in the <filename>.wants/</filename> - directory of either - <filename>multi-user.target</filename> or - <filename>graphical.target</filename>, which - are normally used as boot targets at system - startup. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details about the - <filename>.wants/</filename> directories, and - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details about the two boot targets.</para> - - </refsect2> - - <refsect2> - <title>Socket-Based Activation</title> - - <para>In order to maximize the possible - parallelization and robustness and simplify - configuration and development, it is - recommended for all new-style daemons that - communicate via listening sockets to employ - socket-based activation. In a socket-based - activation scheme, the creation and binding of - the listening socket as primary communication - channel of daemons to local (and sometimes - remote) clients is moved out of the daemon - code and into the init system. Based on - per-daemon configuration, the init system - installs the sockets and then hands them off - to the spawned process as soon as the - respective daemon is to be started. - Optionally, activation of the service can be - delayed until the first inbound traffic - arrives at the socket to implement on-demand - activation of daemons. However, the primary - advantage of this scheme is that all providers - and all consumers of the sockets can be - started in parallel as soon as all sockets - are established. In addition to that, daemons - can be restarted with losing only a minimal - number of client transactions, or even any - client request at all (the latter is - particularly true for state-less protocols, - such as DNS or syslog), because the socket - stays bound and accessible during the restart, - and all requests are queued while the daemon - cannot process them.</para> - - <para>New-style daemons which support socket - activation must be able to receive their - sockets from the init system instead of - creating and binding them themselves. For - details about the programming interfaces for - this scheme provided by systemd, see - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. For - details about porting existing daemons to - socket-based activation, see below. With - minimal effort, it is possible to implement - socket-based activation in addition to - traditional internal socket creation in the - same codebase in order to support both - new-style and old-style init systems from the - same daemon binary.</para> - - <para>systemd implements socket-based - activation via <filename>.socket</filename> - units, which are described in - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. When - configuring socket units for socket-based - activation, it is essential that all listening - sockets are pulled in by the special target - unit <filename>sockets.target</filename>. It - is recommended to place a - <varname>WantedBy=sockets.target</varname> - directive in the <literal>[Install]</literal> - section to automatically add such a - dependency on installation of a socket - unit. Unless - <varname>DefaultDependencies=no</varname> is - set, the necessary ordering dependencies are - implicitly created for all socket units. For - more information about - <filename>sockets.target</filename>, see - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. It - is not necessary or recommended to place any - additional dependencies on socket units (for - example from - <filename>multi-user.target</filename> or - suchlike) when one is installed in - <filename>sockets.target</filename>.</para> - </refsect2> - - <refsect2> - <title>Bus-Based Activation</title> - - <para>When the D-Bus IPC system is used for - communication with clients, new-style daemons - should employ bus activation so that they are - automatically activated when a client - application accesses their IPC - interfaces. This is configured in D-Bus - service files (not to be confused with systemd - service unit files!). To ensure that D-Bus - uses systemd to start-up and maintain the - daemon, use the - <varname>SystemdService=</varname> directive - in these service files to configure the - matching systemd service for a D-Bus - service. e.g.: For a D-Bus service whose D-Bus - activation file is named - <filename>org.freedesktop.RealtimeKit.service</filename>, - make sure to set - <varname>SystemdService=rtkit-daemon.service</varname> - in that file to bind it to the systemd - service - <filename>rtkit-daemon.service</filename>. This - is needed to make sure that the daemon is - started in a race-free fashion when activated - via multiple mechanisms simultaneously.</para> - </refsect2> - - <refsect2> - <title>Device-Based Activation</title> - - <para>Often, daemons that manage a particular - type of hardware should be activated only when - the hardware of the respective kind is plugged - in or otherwise becomes available. In a - new-style init system, it is possible to bind - activation to hardware plug/unplug events. In - systemd, kernel devices appearing in the - sysfs/udev device tree can be exposed as units - if they are tagged with the string - <literal>systemd</literal>. Like any other - kind of unit, they may then pull in other units - when activated (i.e. plugged in) and thus - implement device-based activation. systemd - dependencies may be encoded in the udev - database via the - <varname>SYSTEMD_WANTS=</varname> - property. See - <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Often, it is nicer to pull in - services from devices only indirectly via - dedicated targets. Example: Instead of pulling - in <filename>bluetoothd.service</filename> - from all the various bluetooth dongles and - other hardware available, pull in - bluetooth.target from them and - <filename>bluetoothd.service</filename> from - that target. This provides for nicer - abstraction and gives administrators the - option to enable - <filename>bluetoothd.service</filename> via - controlling a - <filename>bluetooth.target.wants/</filename> - symlink uniformly with a command like - <command>enable</command> of - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - instead of manipulating the udev - ruleset.</para> - </refsect2> - - <refsect2> - <title>Path-Based Activation</title> - - <para>Often, runtime of daemons processing - spool files or directories (such as a printing - system) can be delayed until these file system - objects change state, or become - non-empty. New-style init systems provide a - way to bind service activation to file system - changes. systemd implements this scheme via - path-based activation configured in - <filename>.path</filename> units, as outlined - in - <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </refsect2> - - <refsect2> - <title>Timer-Based Activation</title> - - <para>Some daemons that implement clean-up - jobs that are intended to be executed in - regular intervals benefit from timer-based - activation. In systemd, this is implemented - via <filename>.timer</filename> units, as - described in - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </refsect2> - - <refsect2> - <title>Other Forms of Activation</title> - - <para>Other forms of activation have been - suggested and implemented in some - systems. However, there are often simpler or - better alternatives, or they can be put - together of combinations of the schemes - above. Example: Sometimes, it appears useful to - start daemons or <filename>.socket</filename> - units when a specific IP address is configured - on a network interface, because network - sockets shall be bound to the - address. However, an alternative to implement - this is by utilizing the Linux <constant>IP_FREEBIND</constant> - socket option, as accessible via - <varname>FreeBind=yes</varname> in systemd - socket files (see - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). This option, when enabled, - allows sockets to be bound to a non-local, not - configured IP address, and hence allows - bindings to a particular IP address before it - actually becomes available, making such an - explicit dependency to the configured address - redundant. Another often suggested trigger for - service activation is low system - load. However, here too, a more convincing - approach might be to make proper use of - features of the operating system, in - particular, the CPU or IO scheduler of - Linux. Instead of scheduling jobs from - userspace based on monitoring the OS - scheduler, it is advisable to leave the - scheduling of processes to the OS scheduler - itself. systemd provides fine-grained access - to the CPU and IO schedulers. If a process - executed by the init system shall not - negatively impact the amount of CPU or IO - bandwidth available to other processes, it - should be configured with - <varname>CPUSchedulingPolicy=idle</varname> - and/or - <varname>IOSchedulingClass=idle</varname>. Optionally, - this may be combined with timer-based - activation to schedule background jobs during - runtime and with minimal impact on the system, - and remove it from the boot phase - itself.</para> - </refsect2> - - </refsect1> - <refsect1> - <title>Integration with Systemd</title> - - <refsect2> - <title>Writing Systemd Unit Files</title> - - <para>When writing systemd unit files, it is - recommended to consider the following - suggestions:</para> - - <orderedlist> - <listitem><para>If possible, do not use - the <varname>Type=forking</varname> - setting in service files. But if you - do, make sure to set the PID file path - using <varname>PIDFile=</varname>. See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para></listitem> - - <listitem><para>If your daemon - registers a D-Bus name on the bus, - make sure to use - <varname>Type=dbus</varname> in the - service file if - possible.</para></listitem> - - <listitem><para>Make sure to set a - good human-readable description string - with - <varname>Description=</varname>.</para></listitem> - - <listitem><para>Do not disable - <varname>DefaultDependencies=</varname>, - unless you really know what you do and - your unit is involved in early boot or - late system shutdown.</para></listitem> - - <listitem><para>Normally, little if - any dependencies should need to - be defined explicitly. However, if you - do configure explicit dependencies, only refer to - unit names listed on - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> - or names introduced by your own - package to keep the unit file - operating - system-independent.</para></listitem> - - <listitem><para>Make sure to include - an <literal>[Install]</literal> - section including installation - information for the unit file. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. To activate your service - on boot, make sure to add a - <varname>WantedBy=multi-user.target</varname> - or - <varname>WantedBy=graphical.target</varname> - directive. To activate your socket on - boot, make sure to add - <varname>WantedBy=sockets.target</varname>. Usually, - you also want to make sure that when - your service is installed, your socket - is installed too, hence add - <varname>Also=foo.socket</varname> in - your service file - <filename>foo.service</filename>, for - a hypothetical program - <filename>foo</filename>.</para></listitem> - - </orderedlist> - </refsect2> - - <refsect2> - <title>Installing Systemd Service Files</title> - - <para>At the build installation time - (e.g. <command>make install</command> during - package build), packages are recommended to - install their systemd unit files in the - directory returned by <command>pkg-config - systemd - --variable=systemdsystemunitdir</command> (for - system services) or <command>pkg-config - systemd - --variable=systemduserunitdir</command> - (for user services). This will make the - services available in the system on explicit - request but not activate them automatically - during boot. Optionally, during package - installation (e.g. <command>rpm -i</command> - by the administrator), symlinks should be - created in the systemd configuration - directories via the <command>enable</command> - command of the - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool to activate them automatically on - boot.</para> - - <para>Packages using - <citerefentry project='die-net'><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry> - are recommended to use a configure script - excerpt like the following to determine the - unit installation path during source - configuration:</para> - - <programlisting>PKG_PROG_PKG_CONFIG + <refentryinfo> + <title>daemon</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>daemon</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>daemon</refname> + <refpurpose>Writing and packaging system daemons</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>A daemon is a service process that runs in the background + and supervises the system or provides functionality to other + processes. Traditionally, daemons are implemented following a + scheme originating in SysV Unix. Modern daemons should follow a + simpler yet more powerful scheme (here called "new-style" + daemons), as implemented by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + This manual page covers both schemes, and in particular includes + recommendations for daemons that shall be included in the systemd + init system.</para> + + <refsect2> + <title>SysV Daemons</title> + + <para>When a traditional SysV daemon starts, it should execute + the following steps as part of the initialization. Note that + these steps are unnecessary for new-style daemons (see below), + and should only be implemented if compatibility with SysV is + essential.</para> + + <orderedlist> + <listitem><para>Close all open file descriptors except + standard input, output, and error (i.e. the first three file + descriptors 0, 1, 2). This ensures that no accidentally passed + file descriptor stays around in the daemon process. On Linux, + this is best implemented by iterating through + <filename>/proc/self/fd</filename>, with a fallback of + iterating from file descriptor 3 to the value returned by + <function>getrlimit()</function> for + <constant>RLIMIT_NOFILE</constant>. </para></listitem> + + <listitem><para>Reset all signal handlers to their default. + This is best done by iterating through the available signals + up to the limit of <constant>_NSIG</constant> and resetting + them to <constant>SIG_DFL</constant>.</para></listitem> + + <listitem><para>Reset the signal mask + using + <function>sigprocmask()</function>.</para></listitem> + + <listitem><para>Sanitize the environment block, removing or + resetting environment variables that might negatively impact + daemon runtime.</para></listitem> + + <listitem><para>Call <function>fork()</function>, to create a + background process.</para></listitem> + + <listitem><para>In the child, call + <function>setsid()</function> to detach from any terminal and + create an independent session.</para></listitem> + + <listitem><para>In the child, call <function>fork()</function> + again, to ensure that the daemon can never re-acquire a + terminal again.</para></listitem> + + <listitem><para>Call <function>exit()</function> in the first + child, so that only the second child (the actual daemon + process) stays around. This ensures that the daemon process is + re-parented to init/PID 1, as all daemons should + be.</para></listitem> + + <listitem><para>In the daemon process, connect + <filename>/dev/null</filename> to standard input, output, and + error.</para></listitem> + + <listitem><para>In the daemon process, reset the umask to 0, + so that the file modes passed to <function>open()</function>, + <function>mkdir()</function> and suchlike directly control the + access mode of the created files and + directories.</para></listitem> + + <listitem><para>In the daemon process, change the current + directory to the root directory (/), in order to avoid that + the daemon involuntarily blocks mount points from being + unmounted.</para></listitem> + + <listitem><para>In the daemon process, write the daemon PID + (as returned by <function>getpid()</function>) to a PID file, + for example <filename>/run/foobar.pid</filename> (for a + hypothetical daemon "foobar") to ensure that the daemon cannot + be started more than once. This must be implemented in + race-free fashion so that the PID file is only updated when it + is verified at the same time that the PID previously stored in + the PID file no longer exists or belongs to a foreign + process.</para></listitem> + + <listitem><para>In the daemon process, drop privileges, if + possible and applicable.</para></listitem> + + <listitem><para>From the daemon process, notify the original + process started that initialization is complete. This can be + implemented via an unnamed pipe or similar communication + channel that is created before the first + <function>fork()</function> and hence available in both the + original and the daemon process.</para></listitem> + + <listitem><para>Call <function>exit()</function> in the + original process. The process that invoked the daemon must be + able to rely on that this <function>exit()</function> happens + after initialization is complete and all external + communication channels are established and + accessible.</para></listitem> + </orderedlist> + + <para>The BSD <function>daemon()</function> function should not + be used, as it implements only a subset of these steps.</para> + + <para>A daemon that needs to provide compatibility with SysV + systems should implement the scheme pointed out above. However, + it is recommended to make this behavior optional and + configurable via a command line argument to ease debugging as + well as to simplify integration into systems using + systemd.</para> + </refsect2> + + <refsect2> + <title>New-Style Daemons</title> + + <para>Modern services for Linux should be implemented as + new-style daemons. This makes it easier to supervise and control + them at runtime and simplifies their implementation.</para> + + <para>For developing a new-style daemon, none of the + initialization steps recommended for SysV daemons need to be + implemented. New-style init systems such as systemd make all of + them redundant. Moreover, since some of these steps interfere + with process monitoring, file descriptor passing and other + 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> + + <para>It is recommended for new-style daemons to implement the + following:</para> + + <orderedlist> + <listitem><para>If <constant>SIGTERM</constant> is received, + shut down the daemon and exit cleanly.</para></listitem> + + <listitem><para>If <constant>SIGHUP</constant> is received, + reload the configuration files, if this + applies.</para></listitem> + + <listitem><para>Provide a correct exit code from the main + daemon process, as this is used by the init system to detect + service errors and problems. It is recommended to follow the + exit code scheme as defined in the <ulink + url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB + recommendations for SysV init + scripts</ulink>.</para></listitem> + + <listitem><para>If possible and applicable, expose the + daemon's control interface via the D-Bus IPC system and grab a + bus name as last step of initialization.</para></listitem> + + <listitem><para>For integration in systemd, provide a + <filename>.service</filename> unit file that carries + information about starting, stopping and otherwise maintaining + the daemon. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + + <listitem><para>As much as possible, rely on the init system's + functionality to limit the access of the daemon to files, + services and other resources, i.e. in the case of systemd, + rely on systemd's resource limit control instead of + implementing your own, rely on systemd's privilege dropping + code instead of implementing it in the daemon, and similar. + See + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the available controls.</para></listitem> + + <listitem><para>If D-Bus is used, make your daemon + 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 + 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 + details.</para></listitem> + + <listitem><para>If your daemon provides services to other + local processes or remote clients via a socket, it should be + made socket-activatable following the scheme pointed out + below. Like D-Bus activation, this enables on-demand starting + of services as well as it allows improved parallelization of + service start-up. Also, for state-less protocols (such as + syslog, DNS), a daemon implementing socket-based activation + can be restarted without losing a single request. See below + for details.</para></listitem> + + <listitem><para>If applicable, a daemon should notify the init + system about startup completion or status updates via the + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + interface.</para></listitem> + + <listitem><para>Instead of using the + <function>syslog()</function> call to log directly to the + system syslog service, a new-style daemon may choose to simply + log to standard error via <function>fprintf()</function>, + which is then forwarded to syslog by the init system. If log + levels are necessary, these can be encoded by prefixing + individual log lines with strings like + <literal><4></literal> (for log level 4 "WARNING" in the + syslog priority scheme), following a similar style as the + Linux kernel's <function>printk()</function> level system. For + details, see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + </orderedlist> + + <para>These recommendations are similar but not identical to the + <ulink + url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">Apple + MacOS X Daemon Requirements</ulink>.</para> + </refsect2> + + </refsect1> + <refsect1> + <title>Activation</title> + + <para>New-style init systems provide multiple additional + mechanisms to activate services, as detailed below. It is common + that services are configured to be activated via more than one + mechanism at the same time. An example for systemd: + <filename>bluetoothd.service</filename> might get activated either + when Bluetooth hardware is plugged in, or when an application + accesses its programming interfaces via D-Bus. Or, a print server + daemon might get activated when traffic arrives at an IPP port, or + when a printer is plugged in, or when a file is queued in the + printer spool directory. Even for services that are intended to be + started on system bootup unconditionally, it is a good idea to + implement some of the various activation schemes outlined below, + in order to maximize parallelization. If a daemon implements a + D-Bus service or listening socket, implementing the full bus and + socket activation scheme allows starting of the daemon with its + clients in parallel (which speeds up boot-up), since all its + communication channels are established already, and no request is + lost because client requests will be queued by the bus system (in + case of D-Bus) or the kernel (in case of sockets) until the + activation is completed.</para> + + <refsect2> + <title>Activation on Boot</title> + + <para>Old-style daemons are usually activated exclusively on + boot (and manually by the administrator) via SysV init scripts, + as detailed in the <ulink + url="http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB + Linux Standard Base Core Specification</ulink>. This method of + activation is supported ubiquitously on Linux init systems, both + old-style and new-style systems. Among other issues, SysV init + scripts have the disadvantage of involving shell scripts in the + boot process. New-style init systems generally employ updated + versions of activation, both during boot-up and during runtime + and using more minimal service description files.</para> + + <para>In systemd, if the developer or administrator wants to + make sure that a service or other unit is activated + automatically on boot, it is recommended to place a symlink to + the unit file in the <filename>.wants/</filename> directory of + either <filename>multi-user.target</filename> or + <filename>graphical.target</filename>, which are normally used + as boot targets at system startup. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details about the <filename>.wants/</filename> directories, + and + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about the two boot targets.</para> + + </refsect2> + + <refsect2> + <title>Socket-Based Activation</title> + + <para>In order to maximize the possible parallelization and + robustness and simplify configuration and development, it is + recommended for all new-style daemons that communicate via + listening sockets to employ socket-based activation. In a + socket-based activation scheme, the creation and binding of the + listening socket as primary communication channel of daemons to + local (and sometimes remote) clients is moved out of the daemon + code and into the init system. Based on per-daemon + configuration, the init system installs the sockets and then + hands them off to the spawned process as soon as the respective + daemon is to be started. Optionally, activation of the service + can be delayed until the first inbound traffic arrives at the + socket to implement on-demand activation of daemons. However, + the primary advantage of this scheme is that all providers and + all consumers of the sockets can be started in parallel as soon + as all sockets are established. In addition to that, daemons can + be restarted with losing only a minimal number of client + transactions, or even any client request at all (the latter is + particularly true for state-less protocols, such as DNS or + syslog), because the socket stays bound and accessible during + the restart, and all requests are queued while the daemon cannot + process them.</para> + + <para>New-style daemons which support socket activation must be + able to receive their sockets from the init system instead of + creating and binding them themselves. For details about the + programming interfaces for this scheme provided by systemd, see + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + For details about porting existing daemons to socket-based + activation, see below. With minimal effort, it is possible to + implement socket-based activation in addition to traditional + internal socket creation in the same codebase in order to + support both new-style and old-style init systems from the same + daemon binary.</para> + + <para>systemd implements socket-based activation via + <filename>.socket</filename> units, which are described in + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + When configuring socket units for socket-based activation, it is + essential that all listening sockets are pulled in by the + special target unit <filename>sockets.target</filename>. It is + recommended to place a + <varname>WantedBy=sockets.target</varname> directive in the + <literal>[Install]</literal> section to automatically add such a + dependency on installation of a socket unit. Unless + <varname>DefaultDependencies=no</varname> is set, the necessary + ordering dependencies are implicitly created for all socket + units. For more information about + <filename>sockets.target</filename>, see + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + It is not necessary or recommended to place any additional + dependencies on socket units (for example from + <filename>multi-user.target</filename> or suchlike) when one is + installed in <filename>sockets.target</filename>.</para> + </refsect2> + + <refsect2> + <title>Bus-Based Activation</title> + + <para>When the D-Bus IPC system is used for communication with + clients, new-style daemons should employ bus activation so that + they are automatically activated when a client application + accesses their IPC interfaces. This is configured in D-Bus + service files (not to be confused with systemd service unit + files!). To ensure that D-Bus uses systemd to start-up and + maintain the daemon, use the <varname>SystemdService=</varname> + directive in these service files to configure the matching + systemd service for a D-Bus service. e.g.: For a D-Bus service + whose D-Bus activation file is named + <filename>org.freedesktop.RealtimeKit.service</filename>, make + sure to set + <varname>SystemdService=rtkit-daemon.service</varname> in that + file to bind it to the systemd service + <filename>rtkit-daemon.service</filename>. This is needed to + make sure that the daemon is started in a race-free fashion when + activated via multiple mechanisms simultaneously.</para> + </refsect2> + + <refsect2> + <title>Device-Based Activation</title> + + <para>Often, daemons that manage a particular type of hardware + should be activated only when the hardware of the respective + kind is plugged in or otherwise becomes available. In a + new-style init system, it is possible to bind activation to + hardware plug/unplug events. In systemd, kernel devices + appearing in the sysfs/udev device tree can be exposed as units + if they are tagged with the string <literal>systemd</literal>. + Like any other kind of unit, they may then pull in other units + when activated (i.e. plugged in) and thus implement device-based + activation. systemd dependencies may be encoded in the udev + database via the <varname>SYSTEMD_WANTS=</varname> property. See + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Often, it is nicer to pull in services from devices + only indirectly via dedicated targets. Example: Instead of + pulling in <filename>bluetoothd.service</filename> from all the + various bluetooth dongles and other hardware available, pull in + bluetooth.target from them and + <filename>bluetoothd.service</filename> from that target. This + provides for nicer abstraction and gives administrators the + option to enable <filename>bluetoothd.service</filename> via + controlling a <filename>bluetooth.target.wants/</filename> + symlink uniformly with a command like <command>enable</command> + of + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + instead of manipulating the udev ruleset.</para> + </refsect2> + + <refsect2> + <title>Path-Based Activation</title> + + <para>Often, runtime of daemons processing spool files or + directories (such as a printing system) can be delayed until + these file system objects change state, or become non-empty. + New-style init systems provide a way to bind service activation + to file system changes. systemd implements this scheme via + path-based activation configured in <filename>.path</filename> + units, as outlined in + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect2> + + <refsect2> + <title>Timer-Based Activation</title> + + <para>Some daemons that implement clean-up jobs that are + intended to be executed in regular intervals benefit from + timer-based activation. In systemd, this is implemented via + <filename>.timer</filename> units, as described in + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect2> + + <refsect2> + <title>Other Forms of Activation</title> + + <para>Other forms of activation have been suggested and + implemented in some systems. However, there are often simpler or + better alternatives, or they can be put together of combinations + of the schemes above. Example: Sometimes, it appears useful to + start daemons or <filename>.socket</filename> units when a + specific IP address is configured on a network interface, + because network sockets shall be bound to the address. However, + an alternative to implement this is by utilizing the Linux + <constant>IP_FREEBIND</constant> socket option, as accessible + via <varname>FreeBind=yes</varname> in systemd socket files (see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). This option, when enabled, allows sockets to be + bound to a non-local, not configured IP address, and hence + allows bindings to a particular IP address before it actually + becomes available, making such an explicit dependency to the + configured address redundant. Another often suggested trigger + for service activation is low system load. However, here too, a + more convincing approach might be to make proper use of features + of the operating system, in particular, the CPU or IO scheduler + of Linux. Instead of scheduling jobs from userspace based on + monitoring the OS scheduler, it is advisable to leave the + scheduling of processes to the OS scheduler itself. systemd + provides fine-grained access to the CPU and IO schedulers. If a + process executed by the init system shall not negatively impact + the amount of CPU or IO bandwidth available to other processes, + it should be configured with + <varname>CPUSchedulingPolicy=idle</varname> and/or + <varname>IOSchedulingClass=idle</varname>. Optionally, this may + be combined with timer-based activation to schedule background + jobs during runtime and with minimal impact on the system, and + remove it from the boot phase itself.</para> + </refsect2> + + </refsect1> + <refsect1> + <title>Integration with Systemd</title> + + <refsect2> + <title>Writing Systemd Unit Files</title> + + <para>When writing systemd unit files, it is recommended to + consider the following suggestions:</para> + + <orderedlist> + <listitem><para>If possible, do not use the + <varname>Type=forking</varname> setting in service files. But + if you do, make sure to set the PID file path using + <varname>PIDFile=</varname>. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + + <listitem><para>If your daemon registers a D-Bus name on the + bus, make sure to use <varname>Type=dbus</varname> in the + service file if possible.</para></listitem> + + <listitem><para>Make sure to set a good human-readable + description string with + <varname>Description=</varname>.</para></listitem> + + <listitem><para>Do not disable + <varname>DefaultDependencies=</varname>, unless you really + know what you do and your unit is involved in early boot or + late system shutdown.</para></listitem> + + <listitem><para>Normally, little if any dependencies should + need to be defined explicitly. However, if you do configure + explicit dependencies, only refer to unit names listed on + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + or names introduced by your own package to keep the unit file + operating system-independent.</para></listitem> + + <listitem><para>Make sure to include an + <literal>[Install]</literal> section including installation + information for the unit file. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. To activate your service on boot, make sure to + add a <varname>WantedBy=multi-user.target</varname> or + <varname>WantedBy=graphical.target</varname> directive. To + activate your socket on boot, make sure to add + <varname>WantedBy=sockets.target</varname>. Usually, you also + want to make sure that when your service is installed, your + socket is installed too, hence add + <varname>Also=foo.socket</varname> in your service file + <filename>foo.service</filename>, for a hypothetical program + <filename>foo</filename>.</para></listitem> + + </orderedlist> + </refsect2> + + <refsect2> + <title>Installing Systemd Service Files</title> + + <para>At the build installation time (e.g. <command>make + install</command> during package build), packages are + recommended to install their systemd unit files in the directory + returned by <command>pkg-config systemd + --variable=systemdsystemunitdir</command> (for system services) + or <command>pkg-config systemd + --variable=systemduserunitdir</command> (for user services). + This will make the services available in the system on explicit + request but not activate them automatically during boot. + Optionally, during package installation (e.g. <command>rpm + -i</command> by the administrator), symlinks should be created + in the systemd configuration directories via the + <command>enable</command> command of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool to activate them automatically on boot.</para> + + <para>Packages using + <citerefentry project='die-net'><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry> + are recommended to use a configure script + excerpt like the following to determine the + unit installation path during source + configuration:</para> + + <programlisting>PKG_PROG_PKG_CONFIG AC_ARG_WITH([systemdsystemunitdir], [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],, [with_systemdsystemunitdir=auto]) @@ -763,60 +595,58 @@ AS_IF([test "x$with_systemdsystemunitdir" = "xyes" -o "x$with_systemdsystemunitd def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd) AS_IF([test "x$def_systemdsystemunitdir" = "x"], - [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"], - [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])]) - with_systemdsystemunitdir=no], - [with_systemdsystemunitdir="$def_systemdsystemunitdir"])]) + [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"], + [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])]) + with_systemdsystemunitdir=no], + [with_systemdsystemunitdir="$def_systemdsystemunitdir"])]) AS_IF([test "x$with_systemdsystemunitdir" != "xno"], [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])]) AM_CONDITIONAL([HAVE_SYSTEMD], [test "x$with_systemdsystemunitdir" != "xno"])</programlisting> - <para>This snippet allows automatic - installation of the unit files on systemd - machines, and optionally allows their - installation even on machines lacking - systemd. (Modification of this snippet for the - user unit directory is left as an exercise for the - reader.)</para> + <para>This snippet allows automatic + installation of the unit files on systemd + machines, and optionally allows their + installation even on machines lacking + systemd. (Modification of this snippet for the + user unit directory is left as an exercise for the + reader.)</para> - <para>Additionally, to ensure that - <command>make distcheck</command> continues to - work, it is recommended to add the following - to the top-level <filename>Makefile.am</filename> - file in - <citerefentry project='die-net'><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based - projects:</para> + <para>Additionally, to ensure that + <command>make distcheck</command> continues to + work, it is recommended to add the following + to the top-level <filename>Makefile.am</filename> + file in + <citerefentry project='die-net'><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based + projects:</para> - <programlisting>DISTCHECK_CONFIGURE_FLAGS = \ - --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting> + <programlisting>DISTCHECK_CONFIGURE_FLAGS = \ + --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting> - <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para> + <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para> - <programlisting>if HAVE_SYSTEMD + <programlisting>if HAVE_SYSTEMD systemdsystemunit_DATA = \ - foobar.socket \ - foobar.service + foobar.socket \ + foobar.service endif</programlisting> - <para>In the - <citerefentry project='die-net'><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry> - <filename>.spec</filename> file, use snippets - like the following to enable/disable the - service during - installation/deinstallation. This makes use of - the RPM macros shipped along systemd. Consult - the packaging guidelines of your distribution - for details and the equivalent for other - package managers.</para> + <para>In the + <citerefentry project='die-net'><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry> + <filename>.spec</filename> file, use snippets like the following + to enable/disable the service during + installation/deinstallation. This makes use of the RPM macros + shipped along systemd. Consult the packaging guidelines of your + distribution for details and the equivalent for other package + managers.</para> - <para>At the top of the file:</para> + <para>At the top of the file:</para> - <programlisting>BuildRequires: systemd + <programlisting>BuildRequires: systemd %{?systemd_requires}</programlisting> - <para>And as scriptlets, further down:</para> + <para>And as scriptlets, further down:</para> - <programlisting>%post + <programlisting>%post %systemd_post foobar.service foobar.socket %preun @@ -825,133 +655,111 @@ endif</programlisting> %postun %systemd_postun</programlisting> - <para>If the service shall be restarted during - upgrades, replace the - <literal>%postun</literal> scriptlet above - with the following:</para> + <para>If the service shall be restarted during upgrades, replace + the <literal>%postun</literal> scriptlet above with the + following:</para> - <programlisting>%postun + <programlisting>%postun %systemd_postun_with_restart foobar.service</programlisting> - <para>Note that - <literal>%systemd_post</literal> and - <literal>%systemd_preun</literal> expect the - names of all units that are installed/removed - as arguments, separated by - spaces. <literal>%systemd_postun</literal> - expects no - arguments. <literal>%systemd_postun_with_restart</literal> - expects the units to restart as - arguments.</para> - - <para>To facilitate upgrades from a package - version that shipped only SysV init scripts to - a package version that ships both a SysV init - script and a native systemd service file, use - a fragment like the following:</para> - - <programlisting>%triggerun -- foobar < 0.47.11-1 + <para>Note that <literal>%systemd_post</literal> and + <literal>%systemd_preun</literal> expect the names of all units + that are installed/removed as arguments, separated by spaces. + <literal>%systemd_postun</literal> expects no arguments. + <literal>%systemd_postun_with_restart</literal> expects the + units to restart as arguments.</para> + + <para>To facilitate upgrades from a package version that shipped + only SysV init scripts to a package version that ships both a + SysV init script and a native systemd service file, use a + fragment like the following:</para> + + <programlisting>%triggerun -- foobar < 0.47.11-1 if /sbin/chkconfig --level 5 foobar ; then - /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&1 || : + /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&1 || : fi</programlisting> - <para>Where 0.47.11-1 is the first package - version that includes the native unit - file. This fragment will ensure that the first - time the unit file is installed, it will be - enabled if and only if the SysV init script is - enabled, thus making sure that the enable - status is not changed. Note that - <command>chkconfig</command> is a command - specific to Fedora which can be used to check - whether a SysV init script is enabled. Other - operating systems will have to use different - commands here.</para> - </refsect2> - </refsect1> - - <refsect1> - <title>Porting Existing Daemons</title> - - <para>Since new-style init systems such as systemd are - compatible with traditional SysV init systems, it is - not strictly necessary to port existing daemons to the - new style. However, doing so offers additional - functionality to the daemons as well as simplifying - integration into new-style init systems.</para> - - <para>To port an existing SysV compatible daemon, the - following steps are recommended:</para> - - <orderedlist> - <listitem><para>If not already implemented, - add an optional command line switch to the - daemon to disable daemonization. This is - useful not only for using the daemon in - new-style init systems, but also to ease - debugging.</para></listitem> - - <listitem><para>If the daemon offers - interfaces to other software running on the - local system via local <constant>AF_UNIX</constant> sockets, - consider implementing socket-based activation - (see above). Usually, a minimal patch is - sufficient to implement this: Extend the - socket creation in the daemon code so that - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> - is checked for already passed sockets - first. If sockets are passed (i.e. when - <function>sd_listen_fds()</function> returns a - positive value), skip the socket creation step - and use the passed sockets. Secondly, ensure - that the file system socket nodes for local - <constant>AF_UNIX</constant> sockets used in the socket-based - activation are not removed when the daemon - shuts down, if sockets have been - passed. Third, if the daemon normally closes - all remaining open file descriptors as part of - its initialization, the sockets passed from - the init system must be spared. Since - new-style init systems guarantee that no - left-over file descriptors are passed to - executed processes, it might be a good choice - to simply skip the closing of all remaining - open file descriptors if sockets are - passed.</para></listitem> - - <listitem><para>Write and install a systemd - unit file for the service (and the sockets if - socket-based activation is used, as well as a - path unit file, if the daemon processes a - spool directory), see above for - details.</para></listitem> - - <listitem><para>If the daemon exposes - interfaces via D-Bus, write and install a - D-Bus activation file for the service, see - above for details.</para></listitem> - </orderedlist> - </refsect1> - - <refsect1> - <title>Placing Daemon Data</title> - - <para>It is recommended to follow the general - guidelines for placing package files, as discussed in - <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <para>Where 0.47.11-1 is the first package version that includes + the native unit file. This fragment will ensure that the first + time the unit file is installed, it will be enabled if and only + if the SysV init script is enabled, thus making sure that the + enable status is not changed. Note that + <command>chkconfig</command> is a command specific to Fedora + which can be used to check whether a SysV init script is + enabled. Other operating systems will have to use different + commands here.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>Porting Existing Daemons</title> + + <para>Since new-style init systems such as systemd are compatible + with traditional SysV init systems, it is not strictly necessary + to port existing daemons to the new style. However, doing so + offers additional functionality to the daemons as well as + simplifying integration into new-style init systems.</para> + + <para>To port an existing SysV compatible daemon, the following + steps are recommended:</para> + + <orderedlist> + <listitem><para>If not already implemented, add an optional + command line switch to the daemon to disable daemonization. This + is useful not only for using the daemon in new-style init + systems, but also to ease debugging.</para></listitem> + + <listitem><para>If the daemon offers interfaces to other + software running on the local system via local + <constant>AF_UNIX</constant> sockets, consider implementing + socket-based activation (see above). Usually, a minimal patch is + sufficient to implement this: Extend the socket creation in the + daemon code so that + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + is checked for already passed sockets first. If sockets are + passed (i.e. when <function>sd_listen_fds()</function> returns a + positive value), skip the socket creation step and use the + passed sockets. Secondly, ensure that the file system socket + nodes for local <constant>AF_UNIX</constant> sockets used in the + socket-based activation are not removed when the daemon shuts + down, if sockets have been passed. Third, if the daemon normally + closes all remaining open file descriptors as part of its + initialization, the sockets passed from the init system must be + spared. Since new-style init systems guarantee that no left-over + file descriptors are passed to executed processes, it might be a + good choice to simply skip the closing of all remaining open + file descriptors if sockets are passed.</para></listitem> + + <listitem><para>Write and install a systemd unit file for the + service (and the sockets if socket-based activation is used, as + well as a path unit file, if the daemon processes a spool + directory), see above for details.</para></listitem> + + <listitem><para>If the daemon exposes interfaces via D-Bus, + write and install a D-Bus activation file for the service, see + above for details.</para></listitem> + </orderedlist> + </refsect1> + + <refsect1> + <title>Placing Daemon Data</title> + + <para>It is recommended to follow the general guidelines for + placing package files, as discussed in + <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/file-hierarchy.xml b/man/file-hierarchy.xml index 9d96cff007..e9c894f5c8 100644 --- a/man/file-hierarchy.xml +++ b/man/file-hierarchy.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,956 +23,794 @@ <refentry id="file-hierarchy"> - <refentryinfo> - <title>file-hierarchy</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>file-hierarchy</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>file-hierarchy</refname> - <refpurpose>File system hierarchy overview</refpurpose> - </refnamediv> - - <refsect1> - <title>Description</title> - - <para>Operating systems using the - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - system and service manager are organized based on a - file system hierarchy inspired by UNIX, more - specifically the hierarchy described in the <ulink - url="http://refspecs.linuxfoundation.org/FHS_2.3/fhs-2.3.html">File - System Hierarchy</ulink> specification and - <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>. This - manual page describes a more minimal, modernized - subset of these specifications that defines more - strictly the suggestions and restrictions systemd - makes on the file system hierarchy.</para> - - <para>Many of the paths described here are queriable - with the - <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool.</para> - </refsect1> - - <refsect1> - <title>General Structure</title> - - <variablelist> - <varlistentry> - <term><filename>/</filename></term> - <listitem><para>The file system - root. Usually writable, but this is - not required. Possibly a temporary - file system (<literal>tmpfs</literal>). Not shared with - other hosts (unless read-only). - </para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/boot</filename></term> - <listitem><para>The boot partition - used for bringing up the system. On - EFI systems this is possibly the EFI - System Partition, also see - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This - directory is usually strictly local - to the host, and should be considered - read-only, except when a new kernel or - boot loader is installed. This - directory only exists on systems that - run on physical or emulated hardware - that requires boot - loaders.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/etc</filename></term> - <listitem><para>System-specific - configuration. This directory may or - may not be read-only. Frequently, this - directory is pre-populated with - vendor-supplied configuration files, - but applications should not make - assumptions about this directory - being fully populated or populated at - all, and should fall back to defaults - if configuration is missing.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/home</filename></term> - <listitem><para>The location for - normal user's home - directories. Possibly shared with - other systems, and never - read-only. This directory should only - be used for normal users, never for - system users. This directory and - possibly the directories contained - within it might only become available - or writable in late boot or even only - after user authentication. This directory - might be placed on limited-functionality - network file systems, hence - applications should not assume the - full set of file API is available on - this directory. Applications should - generally not reference this directory - directly, but via the per-user - <varname>$HOME</varname> environment - variable, or via the home directory - field of the user - database.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/root</filename></term> - <listitem><para>The home directory of - the root user. The root user's home - directory is located outside of - <filename>/home</filename> in order to - make sure the root user may log in - even without <filename>/home</filename> - being available and - mounted.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/srv</filename></term> - <listitem><para>The place to store - general server payload, managed by the - administrator. No restrictions are - made how this directory is organized - internally. Generally writable, and - possibly shared among systems. This - directory might become available or - writable only very late during - boot.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/tmp</filename></term> - <listitem><para>The place for small - temporary files. This directory is - usually mounted as - a <literal>tmpfs</literal> instance, and - should hence not be used for larger - files. (Use - <filename>/var/tmp</filename> for - larger files.) Since the directory is - accessible to other users of the - system it is essential that this - directory is only written to with the - <citerefentry project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and related calls. This directory is - usually flushed at boot-up. Also, - files that are not accessed within a - certain time are usually automatically - deleted. If applications find the - environment variable - <varname>$TMPDIR</varname> set they - should prefer using the directory - specified in it over directly - referencing - <filename>/tmp</filename> (see <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> - and - <ulink url="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">IEEE Std 1003.1</ulink> for details).</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Runtime Data</title> - - <variablelist> - <varlistentry> - <term><filename>/run</filename></term> - <listitem><para>A - <literal>tmpfs</literal> file system - for system packages to place runtime - data in. This directory is flushed on - boot, and generally writable for - privileged programs - only. Always writable.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/run/log</filename></term> - <listitem><para>Runtime system - logs. System components may place - private logs in this directory. Always - writable, even when - <filename>/var/log</filename> might - not be accessible - yet.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/run/user</filename></term> - <listitem><para>Contains per-user - runtime directories, each usually - individually mounted - <literal>tmpfs</literal> - instances. Always writable, flushed at - each reboot and when the user logs - out. User code should not reference - this directory directly, but via the - <varname>$XDG_RUNTIME_DIR</varname> - environment variable, as documented in - the <ulink - url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG - Base Directory - Specification</ulink>.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Vendor-supplied Operating System Resources</title> - - <variablelist> - - <varlistentry> - <term><filename>/usr</filename></term> - <listitem><para>Vendor-supplied - operating system resources. Usually - read-only, but this is not - required. Possibly shared between - multiple hosts. This directory should - not be modified by the administrator, - except when installing or removing - vendor-supplied - packages.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/usr/bin</filename></term> - <listitem><para>Binaries and - executables for user commands, that - shall appear in the - <varname>$PATH</varname> search - path. It is recommended not to place - binaries in this directory that are - not useful for invocation from a shell - (such as daemon binaries); these - should be placed in a subdirectory of - <filename>/usr/lib</filename> - instead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/usr/include</filename></term> - <listitem><para>C and C++ API header - files of system - libraries.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/usr/lib</filename></term> - <listitem><para>Static, private vendor - data that is compatible with all - architectures (though not necessarily - architecture-independent). Note that - this includes internal executables or - other binaries that are not regularly - invoked from a shell. Such binaries - may be for any architecture supported - by the system. Do not place public - libraries in this directory, use - <varname>$libdir</varname> (see - below), instead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></term> - <listitem><para>Location for placing - dynamic libraries, also called <varname>$libdir</varname>. - The architecture identifier to use is defined on <ulink - url="https://wiki.debian.org/Multiarch/Tuples">Multiarch Architecture Specifiers (Tuples)</ulink> - list. Legacy locations of <varname>$libdir</varname> are - <filename>/usr/lib</filename>, - <filename>/usr/lib64</filename>. - This directory should not - be used for package-specific data, - unless this data is - architecture-dependent, too. To query - <varname>$libdir</varname> for the - primary architecture of the system, - invoke: - <programlisting># pkg-config --variable=libdir systemd</programlisting> or - <programlisting># systemd-path system-library-arch</programlisting> - </para></listitem> - - </varlistentry> - - <varlistentry> - <term><filename>/usr/share</filename></term> - <listitem><para>Resources shared - between multiple packages, such as - documentation, man pages, time zone - information, fonts and other - resources. Usually, the precise - location and format of files stored - below this directory is subject to - specifications that ensure - interoperability.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/usr/share/doc</filename></term> - <listitem><para>Documentation for the - operating system or system - packages.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/usr/share/factory/etc</filename></term> - <listitem><para>Repository for - vendor-supplied default configuration - files. This directory should be - populated with pristine vendor versions - of all configuration files that may be - placed in - <filename>/etc</filename>. This is - useful to compare the local - configuration of a system with vendor - defaults and to populate the local - configuration with - defaults.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/usr/share/factory/var</filename></term> - - <listitem><para>Similar to - <filename>/usr/share/factory/etc</filename> - but for vendor versions of files in - the variable, persistent data - directory - <filename>/var</filename>.</para></listitem> - - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Persistent Variable System Data</title> - - <variablelist> - <varlistentry> - <term><filename>/var</filename></term> - <listitem><para>Persistent, variable - system data. Must be writable. This - directory might be pre-populated with - vendor-supplied data, but applications - should be able to reconstruct - necessary files and directories in - this subhierarchy should they be - missing, as the system might start up - without this directory being - populated. Persistency is recommended, - but optional, to support ephemeral - systems. This directory might become - available or writable only very late - during boot. Components that are - required to operate during early boot - hence shall not unconditionally rely - on this directory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/var/cache</filename></term> - <listitem><para>Persistent system - cache data. System components may - place non-essential data in this - directory. Flushing this directory - should have no effect on operation of - programs, except for increased - runtimes necessary to rebuild these - caches.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/var/lib</filename></term> - <listitem><para>Persistent system - data. System components may - place private data in this - directory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/var/log</filename></term> - <listitem><para>Persistent system - logs. System components may place - private logs in this directory, though - it is recommended to do most logging - via the - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> - calls.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/var/spool</filename></term> - <listitem><para>Persistent system - spool data, such as printer or mail - queues.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/var/tmp</filename></term> - <listitem><para>The place for larger - and persistent temporary files. In - contrast to <filename>/tmp</filename> - this directory is usually mounted from - a persistent physical file system and - can thus accept larger files. (Use - <filename>/tmp</filename> for smaller - files.) This directory is generally - not flushed at boot-up, but time-based - cleanup of files that have not been - accessed for a certain time is - applied. The same security - restrictions as with - <filename>/tmp</filename> apply, and - hence only - <citerefentry project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or similar calls should be used to - make use of this directory. If - applications find the environment - variable <varname>$TMPDIR</varname> - set they should prefer using the - directory specified in it over - directly referencing - <filename>/var/tmp</filename> (see <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details). - </para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Virtual Kernel and API File Systems</title> - - <variablelist> - <varlistentry> - <term><filename>/dev</filename></term> - <listitem><para>The root directory for - device nodes. Usually this directory - is mounted as a - <literal>devtmpfs</literal> instance, - but might be of a different type in - sandboxed/containerized setups. This - directory is managed jointly by the - kernel and - <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - and should not be written to by other - components. A number of special - purpose virtual file systems might be - mounted below this - directory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/dev/shm</filename></term> - <listitem><para>Place for POSIX shared - memory segments, as created via - <citerefentry><refentrytitle>shm_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This - directory is flushed on boot, and is a - <literal>tmpfs</literal> file - system. Since all users have write - access to this directory, special care - should be taken to avoid name clashes - and vulnerabilities. For normal users, - shared memory segments in this - directory are usually deleted when the - user logs out. Usually it is a better - idea to use memory mapped files in - <filename>/run</filename> (for system - programs) or - <varname>$XDG_RUNTIME_DIR</varname> - (for user programs) instead of POSIX - shared memory segments, since those - directories are not world-writable and - hence not vulnerable to - security-sensitive name - clashes.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/proc</filename></term> - <listitem><para>A virtual kernel file - system exposing the process list and - other functionality. This file system - is mostly an API to interface with the - kernel and not a place where normal - files may be stored. For details, see - <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. A - number of special purpose virtual file - systems might be mounted below this - directory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/proc/sys</filename></term> - <listitem><para>A hierarchy below - <filename>/proc</filename> that - exposes a number of kernel - tunables. The primary way to configure - the settings in this API file tree is - via - <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - files. In sandboxed/containerized - setups this directory is generally - mounted read-only.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/sys</filename></term> - <listitem><para>A virtual kernel file - system exposing discovered devices and - other functionality. This file system - is mostly an API to interface with the - kernel and not a place where normal - files may be stored. In - sandboxed/containerized setups this - directory is generally mounted - read-only. A number of special purpose - virtual file systems might be mounted - below this - directory.</para></listitem> - </varlistentry> - - - </variablelist> - </refsect1> - - <refsect1> - <title>Compatibility Symlinks</title> - - <variablelist> - <varlistentry> - <term><filename>/bin</filename></term> - <term><filename>/sbin</filename></term> - <term><filename>/usr/sbin</filename></term> - - <listitem><para>These compatibility - symlinks point to - <filename>/usr/bin</filename>, - ensuring that scripts and binaries - referencing these legacy paths - correctly find their binaries.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/lib</filename></term> - - <listitem><para>This compatibility - symlink points to - <filename>/usr/lib</filename>, - ensuring that programs referencing - this legacy path correctly find - their resources.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/lib64</filename></term> - - <listitem><para>On some architecture - ABIs this compatibility symlink points - to <varname>$libdir</varname>, - ensuring that binaries referencing - this legacy path correctly find their - dynamic loader. This symlink only - exists on architectures whose ABI - places the dynamic loader in this - path.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/var/run</filename></term> - - <listitem><para>This compatibility - symlink points to - <filename>/run</filename>, ensuring - that programs referencing this legacy - path correctly find their runtime - data.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Home Directory</title> - - <para>User applications may want to place files and - directories in the user's home directory. They should - follow the following basic structure. Note that some - of these directories are also standardized (though - more weakly) by the <ulink - url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG - Base Directory Specification</ulink>. Additional - locations for high-level user resources are defined by - <ulink - url="http://www.freedesktop.org/wiki/Software/xdg-user-dirs/">xdg-user-dirs</ulink>.</para> - - <variablelist> - <varlistentry> - <term><filename>~/.cache</filename></term> - - <listitem><para>Persistent user cache - data. User programs may place - non-essential data in this - directory. Flushing this directory - should have no effect on operation of - programs, except for increased - runtimes necessary to rebuild these - caches. If an application finds - <varname>$XDG_CACHE_HOME</varname> set - is should use the directory specified - in it instead of this - directory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>~/.config</filename></term> - - <listitem><para>Application - configuration and state. When a new - user is created this directory will be - empty or not exist at - all. Applications should fall back to - defaults should their configuration or - state in this directory be missing. If - an application finds - <varname>$XDG_CONFIG_HOME</varname> set - is should use the directory specified - in it instead of this - directory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>~/.local/bin</filename></term> - - <listitem><para>Executables that shall - appear in the user's - <varname>$PATH</varname> search - path. It is recommended not to place - executables in this directory that are - not useful for invocation from a - shell; these should be placed in a - subdirectory of - <filename>~/.local/lib</filename> - instead. Care should be taken when - placing architecture-dependent - binaries in this place which might be - problematic if the home directory is - shared between multiple hosts with - different - architectures.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>~/.local/lib</filename></term> - - <listitem><para>Static, private vendor - data that is compatible with all - architectures.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></term> - - <listitem><para>Location for placing - public dynamic libraries. The architecture - identifier to use, is defined on <ulink - url="https://wiki.debian.org/Multiarch/Tuples">Multiarch Architecture Specifiers (Tuples)</ulink> - list.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>~/.local/share</filename></term> - - <listitem><para>Resources shared - between multiple packages, such as - fonts or artwork. Usually, the precise - location and format of files stored - below this directory is subject to - specifications that ensure - interoperability. If - an application finds - <varname>$XDG_DATA_HOME</varname> set - is should use the directory specified - in it instead of this - directory.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - - <refsect1> - <title>Unprivileged Write Access</title> - - <para>Unprivileged processes generally lack - write access to most of the hierarchy.</para> - - <para>The exceptions for normal users are - <filename>/tmp</filename>, - <filename>/var/tmp</filename>, - <filename>/dev/shm</filename>, as well as the home - directory <varname>$HOME</varname> (usually found - below <filename>/home</filename>) and the runtime - directory <varname>$XDG_RUNTIME_DIR</varname> (found - below <filename>/run/user</filename>) of the - user, which are all writable.</para> - - <para>For unprivileged system processes only - <filename>/tmp</filename>, - <filename>/var/tmp</filename> and - <filename>/dev/shm</filename> are writable. If an - unprivileged system process needs a private, writable - directory in <filename>/var</filename> or - <filename>/run</filename>, it is recommended to either - create it before dropping privileges in the daemon - code, to create it via - <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - fragments during boot, or via the - <varname>RuntimeDirectory=</varname> directive of - service units (see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details).</para> - </refsect1> - - <refsect1> - <title>Node Types</title> - - <para>Unix file systems support different types of file - nodes, including regular files, directories, symlinks, - character and block device nodes, sockets and FIFOs.</para> - - <para>It is strongly recommended that - <filename>/dev</filename> is the only location below - which device nodes shall be placed. Similar, - <filename>/run</filename> shall be the only location - to place sockets and FIFOs. Regular files, - directories and symlinks may be used in all - directories.</para> - </refsect1> - - <refsect1> - <title>System Packages</title> - - <para>Developers of system packages should follow - strict rules when placing their own files in the file - system. The following table lists recommended - locations for specific types of files supplied by the - vendor.</para> - - <table> - <title>System Package Vendor Files Locations</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname="directory" /> - <colspec colname="purpose" /> - <thead> - <row> - <entry>Directory</entry> - <entry>Purpose</entry> - </row> - </thead> - <tbody> - <row> - <entry><filename>/usr/bin</filename></entry> - <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path, compiled for any of the supported architectures compatible with the operating system. It is not recommended to place internal binaries or binaries that are not commonly invoked from the shell in this directory, such as daemon binaries. As this directory is shared with most other packages of the system special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry> - </row> - <row> - <entry><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></entry> - <entry>Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry> - </row> - <row> - <entry><filename>/usr/lib/<replaceable>package</replaceable></filename></entry> - <entry>Private, static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry> - </row> - <row> - <entry><filename>/usr/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry> - <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. Note that this generally does not include private executables since binaries of a specific architecture may be freely invoked from any other supported system architecture.</entry> - </row> - <row> - <entry><filename>/usr/include/<replaceable>package</replaceable></filename></entry> - <entry>Public C/C++ APIs of public shared libraries of the package.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Additional static vendor files may be installed - in the <filename>/usr/share</filename> hierarchy, to - the locations defined by the various relevant - specifications.</para> - - <para>During runtime and for local configuration and - state additional directories are defined:</para> - - <table> - <title>System Package Variable Files Locations</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname="directory" /> - <colspec colname="purpose" /> - <thead> - <row> - <entry>Directory</entry> - <entry>Purpose</entry> - </row> - </thead> - <tbody> - <row> - <entry><filename>/etc/<replaceable>package</replaceable></filename></entry> - <entry>System-specific configuration for the package. It is recommended to default to safe fallbacks if this configuration is missing, if this is possible. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to copy or symlink the necessary files and directories from <filename>/usr/share/factory</filename> during boot, via the <literal>L</literal> or <literal>C</literal> directives.</entry> - </row> - <row> - <entry><filename>/run/<replaceable>package</replaceable></filename></entry> - <entry>Runtime data for the package. Packages must be able to create the necessary subdirectories in this tree on their own, since the directory is flushed automatically on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot. Alternatively, the <varname>RuntimeDirectory=</varname> directive of service units may be used (see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.)</entry> - </row> - <row> - <entry><filename>/run/log/<replaceable>package</replaceable></filename></entry> - <entry>Runtime log data for the package. As above, the package needs to make sure to create this directory if necessary, as it will be flushed on every boot.</entry> - </row> - <row> - <entry><filename>/var/cache/<replaceable>package</replaceable></filename></entry> - <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry> - </row> - <row> - <entry><filename>/var/lib/<replaceable>package</replaceable></filename></entry> - <entry>Persistent private data of the package. This is the primary place to put persistent data that does not fall into the other categories listed. Packages should be able to create the necessary subdirectories in this tree on their own, since the directory might be missing on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot.</entry> - </row> - <row> - <entry><filename>/var/log/<replaceable>package</replaceable></filename></entry> - <entry>Persistent log data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry> - </row> - <row> - <entry><filename>/var/spool/<replaceable>package</replaceable></filename></entry> - <entry>Persistent spool/queue data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - <title>User Packages</title> - - <para>Programs running in user context should follow - strict rules when placing their own files in the - user's home directory. The following table lists - recommended locations in the home directory for - specific types of files supplied by the vendor if the - application is installed in the home directory. (Note - however, that user applications installed system-wide - should follow the rules outlined above regarding - placing vendor files.)</para> - - <table> - <title>User Package Vendor File Locations</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname="directory" /> - <colspec colname="purpose" /> - <thead> - <row> - <entry>Directory</entry> - <entry>Purpose</entry> - </row> - </thead> - <tbody> - <row> - <entry><filename>~/.local/bin</filename></entry> - <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path. It is not recommended to place internal executables or executables that are not commonly invoked from the shell in this directory, such as daemon executables. As this directory is shared with most other packages of the user special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry> - </row> - <row> - <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></entry> - <entry>Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry> - </row> - <row> - <entry><filename>~/.local/lib/<replaceable>package</replaceable></filename></entry> - <entry>Private, static vendor resources of the package, compatible with any architecture, or any other kind of read-only vendor data.</entry> - </row> - <row> - <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry> - <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Additional static vendor files may be installed - in the <filename>~/.local/share</filename> hierarchy, - to the locations defined by the various relevant - specifications.</para> - - <para>During runtime and for local configuration and - state additional directories are defined:</para> - - <table> - <title>User Package Variable File Locations</title> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname="directory" /> - <colspec colname="purpose" /> - <thead> - <row> - <entry>Directory</entry> - <entry>Purpose</entry> - </row> - </thead> - <tbody> - <row> - <entry><filename>~/.config/<replaceable>package</replaceable></filename></entry> - <entry>User-specific configuration and state for the package. It is required to default to safe fallbacks if this configuration is missing.</entry> - </row> - <row> - <entry><filename><varname>$XDG_RUNTIME_DIR</varname>/<replaceable>package</replaceable></filename></entry> - <entry>User runtime data for the package.</entry> - </row> - <row> - <entry><filename>~/.cache/<replaceable>package</replaceable></filename></entry> - <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>file-hierarchy</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>file-hierarchy</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>file-hierarchy</refname> + <refpurpose>File system hierarchy overview</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>Operating systems using the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + system and service manager are organized based on a file system + hierarchy inspired by UNIX, more specifically the hierarchy + described in the <ulink + url="http://refspecs.linuxfoundation.org/FHS_2.3/fhs-2.3.html">File + System Hierarchy</ulink> specification and + <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + This manual page describes a more minimal, modernized subset of + these specifications that defines more strictly the suggestions + and restrictions systemd makes on the file system + hierarchy.</para> + + <para>Many of the paths described here are queriable + with the + <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool.</para> + </refsect1> + + <refsect1> + <title>General Structure</title> + + <variablelist> + <varlistentry> + <term><filename>/</filename></term> + <listitem><para>The file system root. Usually writable, but + this is not required. Possibly a temporary file system + (<literal>tmpfs</literal>). Not shared with other hosts + (unless read-only). </para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/boot</filename></term> + <listitem><para>The boot partition used for bringing up the + system. On EFI systems this is possibly the EFI System + Partition, also see + <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + This directory is usually strictly local to the host, and + should be considered read-only, except when a new kernel or + boot loader is installed. This directory only exists on + systems that run on physical or emulated hardware that + requires boot loaders.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/etc</filename></term> + <listitem><para>System-specific configuration. This directory + may or may not be read-only. Frequently, this directory is + pre-populated with vendor-supplied configuration files, but + applications should not make assumptions about this directory + being fully populated or populated at all, and should fall + back to defaults if configuration is + missing.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/home</filename></term> + <listitem><para>The location for normal user's home + directories. Possibly shared with other systems, and never + read-only. This directory should only be used for normal + users, never for system users. This directory and possibly the + directories contained within it might only become available or + writable in late boot or even only after user authentication. + This directory might be placed on limited-functionality + network file systems, hence applications should not assume the + full set of file API is available on this directory. + Applications should generally not reference this directory + directly, but via the per-user <varname>$HOME</varname> + environment variable, or via the home directory field of the + user database.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/root</filename></term> + <listitem><para>The home directory of the root user. The root + user's home directory is located outside of + <filename>/home</filename> in order to make sure the root user + may log in even without <filename>/home</filename> being + available and mounted.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/srv</filename></term> + <listitem><para>The place to store general server payload, + managed by the administrator. No restrictions are made how + this directory is organized internally. Generally writable, + and possibly shared among systems. This directory might become + available or writable only very late during + boot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/tmp</filename></term> + <listitem><para>The place for small temporary files. This + directory is usually mounted as a <literal>tmpfs</literal> + instance, and should hence not be used for larger files. (Use + <filename>/var/tmp</filename> for larger files.) Since the + directory is accessible to other users of the system it is + essential that this directory is only written to with the + <citerefentry project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and related calls. This directory is usually flushed at + boot-up. Also, files that are not accessed within a certain + time are usually automatically deleted. If applications find + the environment variable <varname>$TMPDIR</varname> set they + should prefer using the directory specified in it over + directly referencing <filename>/tmp</filename> (see + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and + <ulink url="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">IEEE + Std 1003.1</ulink> for details).</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Runtime Data</title> + + <variablelist> + <varlistentry> + <term><filename>/run</filename></term> + <listitem><para>A <literal>tmpfs</literal> file system for + system packages to place runtime data in. This directory is + flushed on boot, and generally writable for privileged + programs only. Always writable.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/run/log</filename></term> + <listitem><para>Runtime system logs. System components may + place private logs in this directory. Always writable, even + when <filename>/var/log</filename> might not be accessible + yet.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/run/user</filename></term> + <listitem><para>Contains per-user runtime directories, each + usually individually mounted <literal>tmpfs</literal> + instances. Always writable, flushed at each reboot and when + the user logs out. User code should not reference this + directory directly, but via the + <varname>$XDG_RUNTIME_DIR</varname> environment variable, as + documented in the <ulink + url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory Specification</ulink>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Vendor-supplied Operating System Resources</title> + + <variablelist> + + <varlistentry> + <term><filename>/usr</filename></term> + <listitem><para>Vendor-supplied operating system resources. + Usually read-only, but this is not required. Possibly shared + between multiple hosts. This directory should not be modified + by the administrator, except when installing or removing + vendor-supplied packages.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/bin</filename></term> + <listitem><para>Binaries and executables for user commands, + that shall appear in the <varname>$PATH</varname> search path. + It is recommended not to place binaries in this directory that + are not useful for invocation from a shell (such as daemon + binaries); these should be placed in a subdirectory of + <filename>/usr/lib</filename> instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/include</filename></term> + <listitem><para>C and C++ API header files of system + libraries.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/lib</filename></term> + <listitem><para>Static, private vendor data that is compatible + with all architectures (though not necessarily + architecture-independent). Note that this includes internal + executables or other binaries that are not regularly invoked + from a shell. Such binaries may be for any architecture + supported by the system. Do not place public libraries in this + directory, use <varname>$libdir</varname> (see below), + instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></term> + <listitem><para>Location for placing dynamic libraries, also + called <varname>$libdir</varname>. The architecture identifier + to use is defined on <ulink + url="https://wiki.debian.org/Multiarch/Tuples">Multiarch + Architecture Specifiers (Tuples)</ulink> list. Legacy + locations of <varname>$libdir</varname> are + <filename>/usr/lib</filename>, + <filename>/usr/lib64</filename>. This directory should not be + used for package-specific data, unless this data is + architecture-dependent, too. To query + <varname>$libdir</varname> for the primary architecture of the + system, invoke: <programlisting># pkg-config --variable=libdir + systemd</programlisting> or <programlisting># systemd-path + system-library-arch</programlisting> </para></listitem> + + </varlistentry> + + <varlistentry> + <term><filename>/usr/share</filename></term> + <listitem><para>Resources shared between multiple packages, + such as documentation, man pages, time zone information, fonts + and other resources. Usually, the precise location and format + of files stored below this directory is subject to + specifications that ensure interoperability.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/share/doc</filename></term> + <listitem><para>Documentation for the operating system or + system packages.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/share/factory/etc</filename></term> + <listitem><para>Repository for vendor-supplied default + configuration files. This directory should be populated with + pristine vendor versions of all configuration files that may + be placed in <filename>/etc</filename>. This is useful to + compare the local configuration of a system with vendor + defaults and to populate the local configuration with + defaults.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/share/factory/var</filename></term> + + <listitem><para>Similar to + <filename>/usr/share/factory/etc</filename> but for vendor + versions of files in the variable, persistent data directory + <filename>/var</filename>.</para></listitem> + + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Persistent Variable System Data</title> + + <variablelist> + <varlistentry> + <term><filename>/var</filename></term> + <listitem><para>Persistent, variable system data. Must be + writable. This directory might be pre-populated with + vendor-supplied data, but applications should be able to + reconstruct necessary files and directories in this + subhierarchy should they be missing, as the system might start + up without this directory being populated. Persistency is + recommended, but optional, to support ephemeral systems. This + directory might become available or writable only very late + during boot. Components that are required to operate during + early boot hence shall not unconditionally rely on this + directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/cache</filename></term> + <listitem><para>Persistent system cache data. System + components may place non-essential data in this directory. + Flushing this directory should have no effect on operation of + programs, except for increased runtimes necessary to rebuild + these caches.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/lib</filename></term> + <listitem><para>Persistent system data. System components may + place private data in this directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/log</filename></term> + <listitem><para>Persistent system logs. System components may + place private logs in this directory, though it is recommended + to do most logging via the + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> + calls.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/spool</filename></term> + <listitem><para>Persistent system spool data, such as printer + or mail queues.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/tmp</filename></term> + <listitem><para>The place for larger and persistent temporary + files. In contrast to <filename>/tmp</filename> this directory + is usually mounted from a persistent physical file system and + can thus accept larger files. (Use <filename>/tmp</filename> + for smaller files.) This directory is generally not flushed at + boot-up, but time-based cleanup of files that have not been + accessed for a certain time is applied. The same security + restrictions as with <filename>/tmp</filename> apply, and + hence only + <citerefentry project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or similar calls should be used to make use of this directory. + If applications find the environment variable + <varname>$TMPDIR</varname> set they should prefer using the + directory specified in it over directly referencing + <filename>/var/tmp</filename> (see + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). </para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Virtual Kernel and API File Systems</title> + + <variablelist> + <varlistentry> + <term><filename>/dev</filename></term> + <listitem><para>The root directory for device nodes. Usually + this directory is mounted as a <literal>devtmpfs</literal> + instance, but might be of a different type in + sandboxed/containerized setups. This directory is managed + jointly by the kernel and + <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + and should not be written to by other components. A number of + special purpose virtual file systems might be mounted below + this directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/dev/shm</filename></term> + <listitem><para>Place for POSIX shared memory segments, as + created via + <citerefentry><refentrytitle>shm_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This directory is flushed on boot, and is a + <literal>tmpfs</literal> file system. Since all users have + write access to this directory, special care should be taken + to avoid name clashes and vulnerabilities. For normal users, + shared memory segments in this directory are usually deleted + when the user logs out. Usually it is a better idea to use + memory mapped files in <filename>/run</filename> (for system + programs) or <varname>$XDG_RUNTIME_DIR</varname> (for user + programs) instead of POSIX shared memory segments, since those + directories are not world-writable and hence not vulnerable to + security-sensitive name clashes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/proc</filename></term> + <listitem><para>A virtual kernel file system exposing the + process list and other functionality. This file system is + mostly an API to interface with the kernel and not a place + where normal files may be stored. For details, see + <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + A number of special purpose virtual file systems might be + mounted below this directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/proc/sys</filename></term> + <listitem><para>A hierarchy below <filename>/proc</filename> + that exposes a number of kernel tunables. The primary way to + configure the settings in this API file tree is via + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + files. In sandboxed/containerized setups this directory is + generally mounted read-only.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/sys</filename></term> + <listitem><para>A virtual kernel file system exposing + discovered devices and other functionality. This file system + is mostly an API to interface with the kernel and not a place + where normal files may be stored. In sandboxed/containerized + setups this directory is generally mounted read-only. A number + of special purpose virtual file systems might be mounted below + this directory.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Compatibility Symlinks</title> + + <variablelist> + <varlistentry> + <term><filename>/bin</filename></term> + <term><filename>/sbin</filename></term> + <term><filename>/usr/sbin</filename></term> + + <listitem><para>These compatibility symlinks point to + <filename>/usr/bin</filename>, ensuring that scripts and + binaries referencing these legacy paths correctly find their + binaries.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/lib</filename></term> + + <listitem><para>This compatibility symlink points to + <filename>/usr/lib</filename>, ensuring that programs + referencing this legacy path correctly find their + resources.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/lib64</filename></term> + + <listitem><para>On some architecture ABIs this compatibility + symlink points to <varname>$libdir</varname>, ensuring that + binaries referencing this legacy path correctly find their + dynamic loader. This symlink only exists on architectures + whose ABI places the dynamic loader in this + path.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/var/run</filename></term> + + <listitem><para>This compatibility symlink points to + <filename>/run</filename>, ensuring that programs referencing + this legacy path correctly find their runtime + data.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Home Directory</title> + + <para>User applications may want to place files and directories in + the user's home directory. They should follow the following basic + structure. Note that some of these directories are also + standardized (though more weakly) by the <ulink + url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory Specification</ulink>. Additional locations for + high-level user resources are defined by <ulink + url="http://www.freedesktop.org/wiki/Software/xdg-user-dirs/">xdg-user-dirs</ulink>.</para> + + <variablelist> + <varlistentry> + <term><filename>~/.cache</filename></term> + + <listitem><para>Persistent user cache data. User programs may + place non-essential data in this directory. Flushing this + directory should have no effect on operation of programs, + except for increased runtimes necessary to rebuild these + caches. If an application finds + <varname>$XDG_CACHE_HOME</varname> set is should use the + directory specified in it instead of this + directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.config</filename></term> + + <listitem><para>Application configuration and state. When a + new user is created this directory will be empty or not exist + at all. Applications should fall back to defaults should their + configuration or state in this directory be missing. If an + application finds <varname>$XDG_CONFIG_HOME</varname> set is + should use the directory specified in it instead of this + directory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.local/bin</filename></term> + + <listitem><para>Executables that shall appear in the user's + <varname>$PATH</varname> search path. It is recommended not to + place executables in this directory that are not useful for + invocation from a shell; these should be placed in a + subdirectory of <filename>~/.local/lib</filename> instead. + Care should be taken when placing architecture-dependent + binaries in this place which might be problematic if the home + directory is shared between multiple hosts with different + architectures.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.local/lib</filename></term> + + <listitem><para>Static, private vendor data that is compatible + with all architectures.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></term> + + <listitem><para>Location for placing public dynamic libraries. + The architecture identifier to use, is defined on <ulink + url="https://wiki.debian.org/Multiarch/Tuples">Multiarch + Architecture Specifiers (Tuples)</ulink> + list.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>~/.local/share</filename></term> + + <listitem><para>Resources shared between multiple packages, + such as fonts or artwork. Usually, the precise location and + format of files stored below this directory is subject to + specifications that ensure interoperability. If an application + finds <varname>$XDG_DATA_HOME</varname> set is should use the + directory specified in it instead of this + directory.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + + <refsect1> + <title>Unprivileged Write Access</title> + + <para>Unprivileged processes generally lack write access to most + of the hierarchy.</para> + + <para>The exceptions for normal users are + <filename>/tmp</filename>, + <filename>/var/tmp</filename>, + <filename>/dev/shm</filename>, as well as the home directory + <varname>$HOME</varname> (usually found below + <filename>/home</filename>) and the runtime directory + <varname>$XDG_RUNTIME_DIR</varname> (found below + <filename>/run/user</filename>) of the user, which are all + writable.</para> + + <para>For unprivileged system processes only + <filename>/tmp</filename>, + <filename>/var/tmp</filename> and + <filename>/dev/shm</filename> are writable. If an + unprivileged system process needs a private, writable directory in + <filename>/var</filename> or <filename>/run</filename>, it is + recommended to either create it before dropping privileges in the + daemon code, to create it via + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + fragments during boot, or via the + <varname>RuntimeDirectory=</varname> directive of service units + (see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details).</para> + </refsect1> + + <refsect1> + <title>Node Types</title> + + <para>Unix file systems support different types of file nodes, + including regular files, directories, symlinks, character and + block device nodes, sockets and FIFOs.</para> + + <para>It is strongly recommended that <filename>/dev</filename> is + the only location below which device nodes shall be placed. + Similar, <filename>/run</filename> shall be the only location to + place sockets and FIFOs. Regular files, directories and symlinks + may be used in all directories.</para> + </refsect1> + + <refsect1> + <title>System Packages</title> + + <para>Developers of system packages should follow strict rules + when placing their own files in the file system. The following + table lists recommended locations for specific types of files + supplied by the vendor.</para> + + <table> + <title>System Package Vendor Files Locations</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="directory" /> + <colspec colname="purpose" /> + <thead> + <row> + <entry>Directory</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>/usr/bin</filename></entry> + <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path, compiled for any of the supported architectures compatible with the operating system. It is not recommended to place internal binaries or binaries that are not commonly invoked from the shell in this directory, such as daemon binaries. As this directory is shared with most other packages of the system special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry> + </row> + <row> + <entry><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></entry> + <entry>Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry> + </row> + <row> + <entry><filename>/usr/lib/<replaceable>package</replaceable></filename></entry> + <entry>Private, static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry> + </row> + <row> + <entry><filename>/usr/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry> + <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. Note that this generally does not include private executables since binaries of a specific architecture may be freely invoked from any other supported system architecture.</entry> + </row> + <row> + <entry><filename>/usr/include/<replaceable>package</replaceable></filename></entry> + <entry>Public C/C++ APIs of public shared libraries of the package.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Additional static vendor files may be installed in the + <filename>/usr/share</filename> hierarchy, to the locations + defined by the various relevant specifications.</para> + + <para>During runtime and for local configuration and state + additional directories are defined:</para> + + <table> + <title>System Package Variable Files Locations</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="directory" /> + <colspec colname="purpose" /> + <thead> + <row> + <entry>Directory</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>/etc/<replaceable>package</replaceable></filename></entry> + <entry>System-specific configuration for the package. It is recommended to default to safe fallbacks if this configuration is missing, if this is possible. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to copy or symlink the necessary files and directories from <filename>/usr/share/factory</filename> during boot, via the <literal>L</literal> or <literal>C</literal> directives.</entry> + </row> + <row> + <entry><filename>/run/<replaceable>package</replaceable></filename></entry> + <entry>Runtime data for the package. Packages must be able to create the necessary subdirectories in this tree on their own, since the directory is flushed automatically on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot. Alternatively, the <varname>RuntimeDirectory=</varname> directive of service units may be used (see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.)</entry> + </row> + <row> + <entry><filename>/run/log/<replaceable>package</replaceable></filename></entry> + <entry>Runtime log data for the package. As above, the package needs to make sure to create this directory if necessary, as it will be flushed on every boot.</entry> + </row> + <row> + <entry><filename>/var/cache/<replaceable>package</replaceable></filename></entry> + <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry> + </row> + <row> + <entry><filename>/var/lib/<replaceable>package</replaceable></filename></entry> + <entry>Persistent private data of the package. This is the primary place to put persistent data that does not fall into the other categories listed. Packages should be able to create the necessary subdirectories in this tree on their own, since the directory might be missing on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot.</entry> + </row> + <row> + <entry><filename>/var/log/<replaceable>package</replaceable></filename></entry> + <entry>Persistent log data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry> + </row> + <row> + <entry><filename>/var/spool/<replaceable>package</replaceable></filename></entry> + <entry>Persistent spool/queue data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + <title>User Packages</title> + + <para>Programs running in user context should follow strict rules + when placing their own files in the user's home directory. The + following table lists recommended locations in the home directory + for specific types of files supplied by the vendor if the + application is installed in the home directory. (Note however, + that user applications installed system-wide should follow the + rules outlined above regarding placing vendor files.)</para> + + <table> + <title>User Package Vendor File Locations</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="directory" /> + <colspec colname="purpose" /> + <thead> + <row> + <entry>Directory</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>~/.local/bin</filename></entry> + <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path. It is not recommended to place internal executables or executables that are not commonly invoked from the shell in this directory, such as daemon executables. As this directory is shared with most other packages of the user special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry> + </row> + <row> + <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></entry> + <entry>Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry> + </row> + <row> + <entry><filename>~/.local/lib/<replaceable>package</replaceable></filename></entry> + <entry>Private, static vendor resources of the package, compatible with any architecture, or any other kind of read-only vendor data.</entry> + </row> + <row> + <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry> + <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Additional static vendor files may be installed in the + <filename>~/.local/share</filename> hierarchy, to the locations + defined by the various relevant specifications.</para> + + <para>During runtime and for local configuration and state + additional directories are defined:</para> + + <table> + <title>User Package Variable File Locations</title> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="directory" /> + <colspec colname="purpose" /> + <thead> + <row> + <entry>Directory</entry> + <entry>Purpose</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>~/.config/<replaceable>package</replaceable></filename></entry> + <entry>User-specific configuration and state for the package. It is required to default to safe fallbacks if this configuration is missing.</entry> + </row> + <row> + <entry><filename><varname>$XDG_RUNTIME_DIR</varname>/<replaceable>package</replaceable></filename></entry> + <entry>User runtime data for the package.</entry> + </row> + <row> + <entry><filename>~/.cache/<replaceable>package</replaceable></filename></entry> + <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/halt.xml b/man/halt.xml index e9ed6554a9..a06dbd0097 100644 --- a/man/halt.xml +++ b/man/halt.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,151 +22,147 @@ --> <refentry id="halt" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>halt</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>halt</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>halt</refname> - <refname>poweroff</refname> - <refname>reboot</refname> - <refpurpose>Halt, power-off or reboot the machine</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>halt <arg choice="opt" rep="repeat">OPTIONS</arg></command> - </cmdsynopsis> - <cmdsynopsis> - <command>poweroff <arg choice="opt" rep="repeat">OPTIONS</arg></command> - </cmdsynopsis> - <cmdsynopsis> - <command>reboot <arg choice="opt" rep="repeat">OPTIONS</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>halt</command>, - <command>poweroff</command>, <command>reboot</command> - may be used to halt, power-off or reboot the - machine.</para> - - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--help</option></term> - - <xi:include href="standard-options.xml" xpointer="help-text" /> - </varlistentry> - - <varlistentry> - <term><option>--halt</option></term> - - <listitem><para>Halt the machine, - regardless of which one of the three - commands is invoked.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-p</option></term> - <term><option>--poweroff</option></term> - - <listitem><para>Power-off the machine, - regardless of which one of the three - commands is invoked.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--reboot</option></term> - - <listitem><para>Reboot the machine, - regardless of which one of the three - commands is invoked.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-f</option></term> - <term><option>--force</option></term> - - <listitem><para>Force immediate halt, - power-off, reboot. Do not contact the - init system.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-w</option></term> - <term><option>--wtmp-only</option></term> - - <listitem><para>Only write wtmp - shutdown entry, do not actually halt, - power-off, reboot.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-d</option></term> - <term><option>--no-wtmp</option></term> - - <listitem><para>Do not write wtmp - shutdown entry.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-wall</option></term> - - <listitem><para>Do not send wall - message before - halt, power-off, reboot.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>These are legacy commands available for - compatibility only.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>halt</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>halt</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>halt</refname> + <refname>poweroff</refname> + <refname>reboot</refname> + <refpurpose>Halt, power-off or reboot the machine</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>halt</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + </cmdsynopsis> + <cmdsynopsis> + <command>poweroff</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + </cmdsynopsis> + <cmdsynopsis> + <command>reboot</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>halt</command>, <command>poweroff</command>, + <command>reboot</command> may be used to halt, power-off or reboot + the machine.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + + <xi:include href="standard-options.xml" xpointer="help-text" /> + </varlistentry> + + <varlistentry> + <term><option>--halt</option></term> + + <listitem><para>Halt the machine, regardless of which one of + the three commands is invoked.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-p</option></term> + <term><option>--poweroff</option></term> + + <listitem><para>Power-off the machine, regardless of which one + of the three commands is invoked.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--reboot</option></term> + + <listitem><para>Reboot the machine, regardless of which one of + the three commands is invoked.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-f</option></term> + <term><option>--force</option></term> + + <listitem><para>Force immediate halt, power-off, reboot. Do + not contact the init system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-w</option></term> + <term><option>--wtmp-only</option></term> + + <listitem><para>Only write wtmp shutdown entry, do not + actually halt, power-off, reboot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-d</option></term> + <term><option>--no-wtmp</option></term> + + <listitem><para>Do not write wtmp shutdown + entry.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-wall</option></term> + + <listitem><para>Do not send wall message before halt, + power-off, reboot.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>These are legacy commands available for compatibility + only.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/hostname.xml b/man/hostname.xml index 2f949dedd3..588f643253 100644 --- a/man/hostname.xml +++ b/man/hostname.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,84 +23,80 @@ --> <refentry id="hostname"> - <refentryinfo> - <title>hostname</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>hostname</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>hostname</refname> - <refpurpose>Local hostname configuration file</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/hostname</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <filename>/etc/hostname</filename> file - configures the name of the local system that is set - during boot using the - <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call. It should contain a single - newline-terminated hostname string. The - hostname may be a free-form string up to 64 characters - in length; however, it is recommended that it consists - only of 7-bit ASCII lower-case characters and no spaces or dots, - and limits itself to the format allowed for DNS domain - name labels, even though this is not a - strict requirement.</para> - - <para>Depending on the operating system, other - configuration files might be checked for configuration - of the hostname as well, however only as fallback.</para> - - <para>You may use - <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to change the value of this file during runtime from - the command line. Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize it on mounted (but not booted) system - images.</para> - </refsect1> - - <refsect1> - <title>History</title> - - <para>The simple configuration file format of - <filename>/etc/hostname</filename> originates from - Debian GNU/Linux.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>hostname</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>hostname</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>hostname</refname> + <refpurpose>Local hostname configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/hostname</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/hostname</filename> file configures the + name of the local system that is set during boot using the + <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system call. It should contain a single newline-terminated + hostname string. The hostname may be a free-form string up to 64 + characters in length; however, it is recommended that it consists + only of 7-bit ASCII lower-case characters and no spaces or dots, + and limits itself to the format allowed for DNS domain name + labels, even though this is not a strict requirement.</para> + + <para>Depending on the operating system, other configuration files + might be checked for configuration of the hostname as well, + however only as fallback.</para> + + <para>You may use + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to change the value of this file during runtime from the command + line. Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize it on mounted (but not booted) system images.</para> + </refsect1> + + <refsect1> + <title>History</title> + + <para>The simple configuration file format of + <filename>/etc/hostname</filename> originates from Debian + GNU/Linux.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/hostnamectl.xml b/man/hostnamectl.xml index de154020d6..b1f038156d 100644 --- a/man/hostnamectl.xml +++ b/man/hostnamectl.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,276 +22,239 @@ --> <refentry id="hostnamectl" conditional='ENABLE_HOSTNAMED' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>hostnamectl</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>hostnamectl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>hostnamectl</refname> - <refpurpose>Control the system hostname</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>hostnamectl</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="req">COMMAND</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>hostnamectl</command> may be used to - query and change the system hostname and related - settings.</para> - - <para>This tool distinguishes three different - hostnames: the high-level "pretty" hostname which - might include all kinds of special characters - (e.g. "Lennart's Laptop"), the static hostname which - is used to initialize the kernel hostname at boot - (e.g. "lennarts-laptop"), and the transient hostname - which is a default received from network configuration. - If a static hostname is set, and is valid (something other - than localhost), then the transient hostname is not used.</para> - - <para>Note that the pretty hostname has little - restrictions on the characters used, while the static - and transient hostnames are limited to the usually - accepted characters of Internet domain names.</para> - - <para>The static hostname is stored in - <filename>/etc/hostname</filename>, see - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information. The pretty hostname, chassis - type, and icon name are stored in - <filename>/etc/machine-info</filename>, see - <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the system host name for mounted (but - not booted) system images.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--no-ask-password</option></term> - - <listitem><para>Do not query the user - for authentication for privileged - operations.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--static</option></term> - <term><option>--transient</option></term> - <term><option>--pretty</option></term> - - <listitem><para>If - <command>status</command> is used (or - no explicit command is given) and one - of those fields is given, - <command>hostnamectl</command> will - print out just this selected - hostname.</para> - - <para>If used with - <command>set-hostname</command>, only - the selected hostname(s) will be - updated. When more than one of those - options is used, all the specified - hostnames will be updated. - </para></listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - <para>The following commands are understood:</para> - - <variablelist> - <varlistentry> - <term><command>status</command></term> - - <listitem><para>Show current system - hostname and related - information.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-hostname <replaceable>NAME</replaceable></command></term> - - <listitem><para>Set the system - hostname to - <replaceable>NAME</replaceable>. By - default, this will alter the pretty, - the static, and the transient hostname - alike; however, if one or more of - <option>--static</option>, - <option>--transient</option>, - <option>--pretty</option> are used, - only the selected hostnames are - changed. If the pretty hostname is - being set, and static or transient are - being set as well, the specified - hostname will be simplified in regards - to the character set used before the - latter are updated. This is done by - replacing spaces with - <literal>-</literal> and removing - special characters. This ensures that - the pretty and the static hostname are - always closely related while still - following the validity rules of the - specific name. This simplification of - the hostname string is not done if - only the transient and/or static host - names are set, and the pretty host - name is left untouched.</para> - - <para>Pass the empty string - <literal></literal> as the hostname to - reset the selected hostnames to their - default (usually - <literal>localhost</literal>).</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-icon-name <replaceable>NAME</replaceable></command></term> - - <listitem><para>Set the system icon - name to - <replaceable>NAME</replaceable>. The - icon name is used by some graphical - applications to visualize this host. - The icon name should follow the <ulink - url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon - Naming Specification</ulink>.</para> - - <para>Pass an empty string to reset - the icon name to the default value, - which is determined from chassis type - (see below) and possibly other - parameters.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-chassis <replaceable>TYPE</replaceable></command></term> - - <listitem><para>Set the chassis type - to <replaceable>TYPE</replaceable>. - The chassis type is used by some - graphical applications to visualize - the host or alter user interaction. - Currently, the following chassis types - are defined: - <literal>desktop</literal>, - <literal>laptop</literal>, - <literal>server</literal>, - <literal>tablet</literal>, - <literal>handset</literal>, - <literal>watch</literal>, - <literal>embedded</literal> as well as - the special chassis types - <literal>vm</literal> and - <literal>container</literal> for - virtualized systems that lack an - immediate physical chassis.</para> - - <para>Pass an empty string to reset - the chassis type to the default value - which is determined from the firmware - and possibly other parameters.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>set-deployment <replaceable>ENVIRONMENT</replaceable></command></term> - - <listitem><para>Set the deployment - environment - description. <replaceable>ENVIRONMENT</replaceable> - must be a single word without any - control characters. One of the - following is suggested: - <literal>development</literal>, - <literal>integration</literal>, - <literal>staging</literal>, - <literal>production</literal>. - </para> - - <para>Pass an empty string to reset to - the default empty value.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><command>set-location <replaceable>LOCATION</replaceable></command></term> - - <listitem><para>Set the location - string for the system, if it is - known. <replaceable>LOCATION</replaceable> - should be a human-friendly, free-form - string describing the physical - location of the system, if it is known - and applicable. This may be as generic - as <literal>Berlin, Germany</literal> - or as specific as <literal>Left Rack, - 2nd Shelf</literal>.</para> - - <para>Pass an empty string to reset to - the default empty value.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>hostnamectl</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>hostnamectl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>hostnamectl</refname> + <refpurpose>Control the system hostname</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>hostnamectl</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="req">COMMAND</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>hostnamectl</command> may be used to query and + change the system hostname and related settings.</para> + + <para>This tool distinguishes three different hostnames: the + high-level "pretty" hostname which might include all kinds of + special characters (e.g. "Lennart's Laptop"), the static hostname + which is used to initialize the kernel hostname at boot (e.g. + "lennarts-laptop"), and the transient hostname which is a default + received from network configuration. If a static hostname is set, + and is valid (something other than localhost), then the transient + hostname is not used.</para> + + <para>Note that the pretty hostname has little restrictions on the + characters used, while the static and transient hostnames are + limited to the usually accepted characters of Internet domain + names.</para> + + <para>The static hostname is stored in + <filename>/etc/hostname</filename>, see + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information. The pretty hostname, chassis type, and icon + name are stored in <filename>/etc/machine-info</filename>, see + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize the system host name for mounted (but not booted) + system images.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--no-ask-password</option></term> + + <listitem><para>Do not query the user for authentication for + privileged operations.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--static</option></term> + <term><option>--transient</option></term> + <term><option>--pretty</option></term> + + <listitem><para>If <command>status</command> is used (or no + explicit command is given) and one of those fields is given, + <command>hostnamectl</command> will print out just this + selected hostname.</para> + + <para>If used with <command>set-hostname</command>, only the + selected hostname(s) will be updated. When more than one of + those options is used, all the specified hostnames will be + updated. </para></listitem> + </varlistentry> + + <xi:include href="user-system-options.xml" xpointer="host" /> + <xi:include href="user-system-options.xml" xpointer="machine" /> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>status</command></term> + + <listitem><para>Show current system + hostname and related + information.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-hostname <replaceable>NAME</replaceable></command></term> + + <listitem><para>Set the system hostname to + <replaceable>NAME</replaceable>. By default, this will alter + the pretty, the static, and the transient hostname alike; + however, if one or more of <option>--static</option>, + <option>--transient</option>, <option>--pretty</option> are + used, only the selected hostnames are changed. If the pretty + hostname is being set, and static or transient are being set + as well, the specified hostname will be simplified in regards + to the character set used before the latter are updated. This + is done by replacing spaces with <literal>-</literal> and + removing special characters. This ensures that the pretty and + the static hostname are always closely related while still + following the validity rules of the specific name. This + simplification of the hostname string is not done if only the + transient and/or static host names are set, and the pretty + host name is left untouched.</para> + + <para>Pass the empty string <literal></literal> as the + hostname to reset the selected hostnames to their default + (usually <literal>localhost</literal>).</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-icon-name <replaceable>NAME</replaceable></command></term> + + <listitem><para>Set the system icon name to + <replaceable>NAME</replaceable>. The icon name is used by some + graphical applications to visualize this host. The icon name + should follow the <ulink + url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">Icon + Naming Specification</ulink>.</para> + + <para>Pass an empty string to reset the icon name to the + default value, which is determined from chassis type (see + below) and possibly other parameters.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-chassis <replaceable>TYPE</replaceable></command></term> + + <listitem><para>Set the chassis type to + <replaceable>TYPE</replaceable>. The chassis type is used by + some graphical applications to visualize the host or alter + user interaction. Currently, the following chassis types are + defined: + <literal>desktop</literal>, + <literal>laptop</literal>, + <literal>server</literal>, + <literal>tablet</literal>, + <literal>handset</literal>, + <literal>watch</literal>, + <literal>embedded</literal>, + as well as the special chassis types + <literal>vm</literal> and + <literal>container</literal> for virtualized systems that lack + an immediate physical chassis.</para> + + <para>Pass an empty string to reset the chassis type to the + default value which is determined from the firmware and + possibly other parameters.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>set-deployment <replaceable>ENVIRONMENT</replaceable></command></term> + + <listitem><para>Set the deployment environment description. + <replaceable>ENVIRONMENT</replaceable> must be a single word + without any control characters. One of the following is + suggested: + <literal>development</literal>, + <literal>integration</literal>, + <literal>staging</literal>, + <literal>production</literal>. + </para> + + <para>Pass an empty string to reset to the default empty + value.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>set-location <replaceable>LOCATION</replaceable></command></term> + + <listitem><para>Set the location string for the system, if it + is known. <replaceable>LOCATION</replaceable> should be a + human-friendly, free-form string describing the physical + location of the system, if it is known and applicable. This + may be as generic as <literal>Berlin, Germany</literal> or as + specific as <literal>Left Rack, 2nd Shelf</literal>.</para> + + <para>Pass an empty string to reset to the default empty + value.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/journald.conf.xml b/man/journald.conf.xml index 4edcc003c0..8504d66d49 100644 --- a/man/journald.conf.xml +++ b/man/journald.conf.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,463 +23,359 @@ --> <refentry id="journald.conf" - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>journald.conf</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>journald.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>journald.conf</refname> - <refname>journald.conf.d</refname> - <refpurpose>Journal service configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/journald.conf</filename></para> - <para><filename>/etc/systemd/journald.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/journald.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/journald.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These files configure various parameters of the - systemd journal service, - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - <xi:include href="standard-conf.xml" xpointer="conf" /> - - <refsect1> - <title>Options</title> - - <para>All options are configured in the - <literal>[Journal]</literal> section:</para> - - <variablelist> - - <varlistentry> - <term><varname>Storage=</varname></term> - - <listitem><para>Controls where to - store journal data. One of - <literal>volatile</literal>, - <literal>persistent</literal>, - <literal>auto</literal> and - <literal>none</literal>. If - <literal>volatile</literal>, journal - log data will be stored only in - memory, i.e. below the - <filename>/run/log/journal</filename> - hierarchy (which is created if - needed). If - <literal>persistent</literal>, data will - be stored preferably on disk, - i.e. below the - <filename>/var/log/journal</filename> - hierarchy (which is created if - needed), with a fallback to - <filename>/run/log/journal</filename> - (which is created if needed), during - early boot and if the disk is not - writable. <literal>auto</literal> is - similar to - <literal>persistent</literal> but the - directory - <filename>/var/log/journal</filename> - is not created if needed, so that its - existence controls where log data - goes. <literal>none</literal> turns - off all storage, all log data received - will be dropped. Forwarding to other - targets, such as the console, the - kernel log buffer or a syslog daemon - will still work however. Defaults to - <literal>auto</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Compress=</varname></term> - - <listitem><para>Takes a boolean - value. If enabled (the default), data - objects that shall be stored in the - journal and are larger than a certain - threshold are compressed before they - are written to the file - system.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Seal=</varname></term> - - <listitem><para>Takes a boolean - value. If enabled (the default), and a - sealing key is available (as created - by - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <option>--setup-keys</option> - command), Forward Secure Sealing (FSS) - for all persistent journal files is - enabled. FSS is based on <ulink - url="https://eprint.iacr.org/2013/397">Seekable - Sequential Key Generators</ulink> by - G. A. Marson and B. Poettering - (doi:10.1007/978-3-642-40203-6_7) - and may be used to protect journal files - from unnoticed alteration.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SplitMode=</varname></term> - - <listitem><para>Controls whether to - split up journal files per user. One - of <literal>uid</literal>, - <literal>login</literal> and - <literal>none</literal>. If - <literal>uid</literal>, all users will - get each their own journal files - regardless of whether they possess a - login session or not, however system - users will log into the system - journal. If <literal>login</literal>, - actually logged-in users will get each - their own journal files, but users - without login session and system users - will log into the system journal. If - <literal>none</literal>, journal files - are not split up by user and all - messages are instead stored in the - single system journal. Note that - splitting up journal files by user is - only available for journals stored - persistently. If journals are stored - on volatile storage (see above), only - a single journal file for all user IDs - is kept. Defaults to - <literal>uid</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RateLimitInterval=</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>, - more messages than specified in - <varname>RateLimitBurst=</varname> are - logged by a service, all further - messages within the interval are - dropped until the interval is over. A - message about the number of dropped - messages is generated. This rate - limiting is applied 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 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, set either - value to 0.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SystemMaxUse=</varname></term> - <term><varname>SystemKeepFree=</varname></term> - <term><varname>SystemMaxFileSize=</varname></term> - <term><varname>RuntimeMaxUse=</varname></term> - <term><varname>RuntimeKeepFree=</varname></term> - <term><varname>RuntimeMaxFileSize=</varname></term> - - <listitem><para>Enforce size limits on - the journal files stored. The options - prefixed with - <literal>System</literal> apply to the - journal files when stored on a - persistent file system, more - specifically - <filename>/var/log/journal</filename>. The - options prefixed with - <literal>Runtime</literal> apply to - the journal files when stored on a - volatile in-memory file system, more - specifically - <filename>/run/log/journal</filename>. The - former is used only when - <filename>/var</filename> is mounted, - writable, and the directory - <filename>/var/log/journal</filename> - exists. Otherwise, only the latter - applies. Note that this means that - during early boot and if the - administrator disabled persistent - logging, only the latter options apply, - while the former apply if persistent - logging is enabled and the system is - fully booted - up. <command>journalctl</command> and - <command>systemd-journald</command> - ignore all files with names not ending - with <literal>.journal</literal> or - <literal>.journal~</literal>, so only - such files, located in the appropriate - directories, are taken into account - when calculating current disk usage. - </para> - - <para><varname>SystemMaxUse=</varname> - and <varname>RuntimeMaxUse=</varname> - control how much disk space the - journal may use up at maximum. - <varname>SystemKeepFree=</varname> and - <varname>RuntimeKeepFree=</varname> - control how much disk space - systemd-journald shall leave free for - other uses. - <command>systemd-journald</command> - will respect both limits and use the - smaller of the two values.</para> - - <para>The first pair defaults to 10% - and the second to 15% of the size of - the respective file system. If the - file system is nearly full and either - <varname>SystemKeepFree=</varname> or - <varname>RuntimeKeepFree=</varname> is - violated when systemd-journald is - started, the value will be raised to - percentage that is actually free. This - means that if there was enough - free space before and journal files were - created, and subsequently something - else causes the file system to fill - up, journald will stop using more - space, but it will not be removing - existing files to go reduce footprint - either.</para> - - <para><varname>SystemMaxFileSize=</varname> - and - <varname>RuntimeMaxFileSize=</varname> - control how large individual journal - files may grow at maximum. This - influences the granularity in which - disk space is made available through - rotation, i.e. deletion of historic - data. Defaults to one eighth of the - values configured with - <varname>SystemMaxUse=</varname> and - <varname>RuntimeMaxUse=</varname>, so - that usually seven rotated journal - files are kept as history. Specify - values in bytes or use K, M, G, T, P, - E as units for the specified sizes - (equal to 1024, 1024²,... bytes). - Note that size limits are enforced - synchronously when journal files are - extended, and no explicit rotation - step triggered by time is - needed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>MaxFileSec=</varname></term> - - <listitem><para>The maximum time to - store entries in a single journal - file before rotating to the next - one. Normally, time-based rotation - should not be required as size-based - rotation with options such as - <varname>SystemMaxFileSize=</varname> - should be sufficient to ensure that - journal files do not grow without - bounds. However, to ensure that not - too much data is lost at once when old - journal files are deleted, it might - make sense to change this value from - the default of one month. Set to 0 to - turn off this feature. This setting - takes time values which may be - suffixed with the units - <literal>year</literal>, - <literal>month</literal>, - <literal>week</literal>, <literal>day</literal>, - <literal>h</literal> or <literal>m</literal> - to override the default time unit of - seconds.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>MaxRetentionSec=</varname></term> - - <listitem><para>The maximum time to - store journal entries. This - controls whether journal files - containing entries older then the - specified time span are - deleted. Normally, time-based deletion - of old journal files should not be - required as size-based deletion with - options such as - <varname>SystemMaxUse=</varname> - should be sufficient to ensure that - journal files do not grow without - bounds. However, to enforce data - retention policies, it might make sense - to change this value from the - default of 0 (which turns off this - feature). This setting also takes - time values which may be suffixed with - the units <literal>year</literal>, - <literal>month</literal>, - <literal>week</literal>, <literal>day</literal>, - <literal>h</literal> or <literal> m</literal> - to override the default time unit of - seconds.</para></listitem> - </varlistentry> - - - <varlistentry> - <term><varname>SyncIntervalSec=</varname></term> - - <listitem><para>The timeout before - synchronizing journal files to - disk. After syncing, journal files are - placed in the OFFLINE state. Note that - syncing is unconditionally done - immediately after a log message of - priority CRIT, ALERT or EMERG has been - logged. This setting hence applies - only to messages of the levels ERR, - WARNING, NOTICE, INFO, DEBUG. The - default timeout is 5 minutes. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ForwardToSyslog=</varname></term> - <term><varname>ForwardToKMsg=</varname></term> - <term><varname>ForwardToConsole=</varname></term> - <term><varname>ForwardToWall=</varname></term> - - <listitem><para>Control whether log - messages received by the journal - daemon shall be forwarded to a - traditional syslog daemon, to the - kernel log buffer (kmsg), to the - system console, or sent as wall - messages to all logged-in users. These - options take boolean arguments. If - forwarding to syslog is enabled but no - syslog daemon is running, the - respective option has no effect. By - default, only forwarding wall is - enabled. These settings may be - overridden at boot time with the - kernel command line options - <literal>systemd.journald.forward_to_syslog=</literal>, - <literal>systemd.journald.forward_to_kmsg=</literal>, - <literal>systemd.journald.forward_to_console=</literal> - and - <literal>systemd.journald.forward_to_wall=</literal>. - When forwarding to the console, the - TTY to log to can be changed with - <varname>TTYPath=</varname>, described - below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>MaxLevelStore=</varname></term> - <term><varname>MaxLevelSyslog=</varname></term> - <term><varname>MaxLevelKMsg=</varname></term> - <term><varname>MaxLevelConsole=</varname></term> - <term><varname>MaxLevelWall=</varname></term> - - <listitem><para>Controls the maximum - log level of messages that are stored - on disk, forwarded to syslog, kmsg, - the console or wall (if that is - enabled, see above). As argument, - takes one of - <literal>emerg</literal>, - <literal>alert</literal>, - <literal>crit</literal>, - <literal>err</literal>, - <literal>warning</literal>, - <literal>notice</literal>, - <literal>info</literal>, - <literal>debug</literal> or integer - values in the range of 0..7 (corresponding - to the same levels). Messages equal or below - the log level specified are - stored/forwarded, messages above are - dropped. Defaults to - <literal>debug</literal> for - <varname>MaxLevelStore=</varname> and - <varname>MaxLevelSyslog=</varname>, to - ensure that the all messages are - written to disk and forwarded to - syslog. Defaults to - <literal>notice</literal> for - <varname>MaxLevelKMsg=</varname>, - <literal>info</literal> for - <varname>MaxLevelConsole=</varname> and - <literal>emerg</literal> for - <varname>MaxLevelWall=</varname>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TTYPath=</varname></term> - - <listitem><para>Change the console TTY - to use if - <varname>ForwardToConsole=yes</varname> - is used. Defaults to - <filename>/dev/console</filename>.</para></listitem> - </varlistentry> - - </variablelist> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>journald.conf</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>journald.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>journald.conf</refname> + <refname>journald.conf.d</refname> + <refpurpose>Journal service configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/journald.conf</filename></para> + <para><filename>/etc/systemd/journald.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/journald.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/journald.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These files configure various parameters of the systemd + journal service, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + <xi:include href="standard-conf.xml" xpointer="conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Journal]</literal> section:</para> + + <variablelist> + + <varlistentry> + <term><varname>Storage=</varname></term> + + <listitem><para>Controls where to store journal data. One of + <literal>volatile</literal>, + <literal>persistent</literal>, + <literal>auto</literal> and + <literal>none</literal>. If + <literal>volatile</literal>, journal + log data will be stored only in memory, i.e. below the + <filename>/run/log/journal</filename> hierarchy (which is + created if needed). If <literal>persistent</literal>, data + will be stored preferably on disk, i.e. below the + <filename>/var/log/journal</filename> hierarchy (which is + created if needed), with a fallback to + <filename>/run/log/journal</filename> (which is created if + needed), during early boot and if the disk is not writable. + <literal>auto</literal> is similar to + <literal>persistent</literal> but the directory + <filename>/var/log/journal</filename> is not created if + needed, so that its existence controls where log data goes. + <literal>none</literal> turns off all storage, all log data + received will be dropped. Forwarding to other targets, such as + the console, the kernel log buffer or a syslog daemon will + still work however. Defaults to + <literal>auto</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Compress=</varname></term> + + <listitem><para>Takes a boolean value. If enabled (the + default), data objects that shall be stored in the journal and + are larger than a certain threshold are compressed before they + are written to the file system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Seal=</varname></term> + + <listitem><para>Takes a boolean value. If enabled (the + default), and a sealing key is available (as created by + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <option>--setup-keys</option> command), Forward Secure Sealing + (FSS) for all persistent journal files is enabled. FSS is + based on <ulink + url="https://eprint.iacr.org/2013/397">Seekable Sequential Key + Generators</ulink> by G. A. Marson and B. Poettering + (doi:10.1007/978-3-642-40203-6_7) and may be used to protect + journal files from unnoticed alteration.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SplitMode=</varname></term> + + <listitem><para>Controls whether to split up journal files per + user. One of <literal>uid</literal>, <literal>login</literal> + and <literal>none</literal>. If <literal>uid</literal>, all + users will get each their own journal files regardless of + whether they possess a login session or not, however system + users will log into the system journal. If + <literal>login</literal>, actually logged-in users will get + each their own journal files, but users without login session + and system users will log into the system journal. If + <literal>none</literal>, journal files are not split up by + user and all messages are instead stored in the single system + journal. Note that splitting up journal files by user is only + available for journals stored persistently. If journals are + stored on volatile storage (see above), only a single journal + file for all user IDs is kept. Defaults to + <literal>uid</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RateLimitInterval=</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>, + more messages than specified in + <varname>RateLimitBurst=</varname> are logged by a service, + all further messages within the interval are dropped until the + interval is over. A message about the number of dropped + messages is generated. This rate limiting is applied + 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 + 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, + set either value to 0.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemMaxUse=</varname></term> + <term><varname>SystemKeepFree=</varname></term> + <term><varname>SystemMaxFileSize=</varname></term> + <term><varname>RuntimeMaxUse=</varname></term> + <term><varname>RuntimeKeepFree=</varname></term> + <term><varname>RuntimeMaxFileSize=</varname></term> + + <listitem><para>Enforce size limits on the journal files + stored. The options prefixed with <literal>System</literal> + apply to the journal files when stored on a persistent file + system, more specifically + <filename>/var/log/journal</filename>. The options prefixed + with <literal>Runtime</literal> apply to the journal files + when stored on a volatile in-memory file system, more + specifically <filename>/run/log/journal</filename>. The former + is used only when <filename>/var</filename> is mounted, + writable, and the directory + <filename>/var/log/journal</filename> exists. Otherwise, only + the latter applies. Note that this means that during early + boot and if the administrator disabled persistent logging, + only the latter options apply, while the former apply if + persistent logging is enabled and the system is fully booted + up. <command>journalctl</command> and + <command>systemd-journald</command> ignore all files with + names not ending with <literal>.journal</literal> or + <literal>.journal~</literal>, so only such files, located in + the appropriate directories, are taken into account when + calculating current disk usage. + </para> + + <para><varname>SystemMaxUse=</varname> and + <varname>RuntimeMaxUse=</varname> control how much disk space + the journal may use up at maximum. + <varname>SystemKeepFree=</varname> and + <varname>RuntimeKeepFree=</varname> control how much disk + space systemd-journald shall leave free for other uses. + <command>systemd-journald</command> will respect both limits + and use the smaller of the two values.</para> + + <para>The first pair defaults to 10% and the second to 15% of + the size of the respective file system. If the file system is + nearly full and either <varname>SystemKeepFree=</varname> or + <varname>RuntimeKeepFree=</varname> is violated when + systemd-journald is started, the value will be raised to + percentage that is actually free. This means that if there was + enough free space before and journal files were created, and + subsequently something else causes the file system to fill up, + journald will stop using more space, but it will not be + removing existing files to go reduce footprint either.</para> + + <para><varname>SystemMaxFileSize=</varname> + and + <varname>RuntimeMaxFileSize=</varname> + control how large individual journal + files may grow at maximum. This + influences the granularity in which + disk space is made available through + rotation, i.e. deletion of historic + data. Defaults to one eighth of the + values configured with + <varname>SystemMaxUse=</varname> and + <varname>RuntimeMaxUse=</varname>, so + that usually seven rotated journal + files are kept as history. Specify + values in bytes or use K, M, G, T, P, + E as units for the specified sizes + (equal to 1024, 1024²,... bytes). + Note that size limits are enforced + synchronously when journal files are + extended, and no explicit rotation + step triggered by time is + needed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxFileSec=</varname></term> + + <listitem><para>The maximum time to store entries in a single + journal file before rotating to the next one. Normally, + time-based rotation should not be required as size-based + rotation with options such as + <varname>SystemMaxFileSize=</varname> should be sufficient to + ensure that journal files do not grow without bounds. However, + to ensure that not too much data is lost at once when old + journal files are deleted, it might make sense to change this + value from the default of one month. Set to 0 to turn off this + feature. This setting takes time values which may be suffixed + with the units <literal>year</literal>, + <literal>month</literal>, <literal>week</literal>, + <literal>day</literal>, <literal>h</literal> or + <literal>m</literal> to override the default time unit of + seconds.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxRetentionSec=</varname></term> + + <listitem><para>The maximum time to store journal entries. + This controls whether journal files containing entries older + then the specified time span are deleted. Normally, time-based + deletion of old journal files should not be required as + size-based deletion with options such as + <varname>SystemMaxUse=</varname> should be sufficient to + ensure that journal files do not grow without bounds. However, + to enforce data retention policies, it might make sense to + change this value from the default of 0 (which turns off this + feature). This setting also takes time values which may be + suffixed with the units <literal>year</literal>, + <literal>month</literal>, <literal>week</literal>, + <literal>day</literal>, <literal>h</literal> or <literal> + m</literal> to override the default time unit of + seconds.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><varname>SyncIntervalSec=</varname></term> + + <listitem><para>The timeout before synchronizing journal files + to disk. After syncing, journal files are placed in the + OFFLINE state. Note that syncing is unconditionally done + immediately after a log message of priority CRIT, ALERT or + EMERG has been logged. This setting hence applies only to + messages of the levels ERR, WARNING, NOTICE, INFO, DEBUG. The + default timeout is 5 minutes. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ForwardToSyslog=</varname></term> + <term><varname>ForwardToKMsg=</varname></term> + <term><varname>ForwardToConsole=</varname></term> + <term><varname>ForwardToWall=</varname></term> + + <listitem><para>Control whether log messages received by the + journal daemon shall be forwarded to a traditional syslog + daemon, to the kernel log buffer (kmsg), to the system + console, or sent as wall messages to all logged-in users. + These options take boolean arguments. If forwarding to syslog + is enabled but no syslog daemon is running, the respective + option has no effect. By default, only forwarding wall is + enabled. These settings may be overridden at boot time with + the kernel command line options + <literal>systemd.journald.forward_to_syslog=</literal>, + <literal>systemd.journald.forward_to_kmsg=</literal>, + <literal>systemd.journald.forward_to_console=</literal> and + <literal>systemd.journald.forward_to_wall=</literal>. When + forwarding to the console, the TTY to log to can be changed + with <varname>TTYPath=</varname>, described + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxLevelStore=</varname></term> + <term><varname>MaxLevelSyslog=</varname></term> + <term><varname>MaxLevelKMsg=</varname></term> + <term><varname>MaxLevelConsole=</varname></term> + <term><varname>MaxLevelWall=</varname></term> + + <listitem><para>Controls the maximum log level of messages + that are stored on disk, forwarded to syslog, kmsg, the + console or wall (if that is enabled, see above). As argument, + takes one of + <literal>emerg</literal>, + <literal>alert</literal>, + <literal>crit</literal>, + <literal>err</literal>, + <literal>warning</literal>, + <literal>notice</literal>, + <literal>info</literal>, + <literal>debug</literal>, + or integer values in the range of 0..7 (corresponding to the + same levels). Messages equal or below the log level specified + are stored/forwarded, messages above are dropped. Defaults to + <literal>debug</literal> for <varname>MaxLevelStore=</varname> + and <varname>MaxLevelSyslog=</varname>, to ensure that the all + messages are written to disk and forwarded to syslog. Defaults + to + <literal>notice</literal> for <varname>MaxLevelKMsg=</varname>, + <literal>info</literal> for <varname>MaxLevelConsole=</varname>, + and <literal>emerg</literal> for + <varname>MaxLevelWall=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TTYPath=</varname></term> + + <listitem><para>Change the console TTY to use if + <varname>ForwardToConsole=yes</varname> is used. Defaults to + <filename>/dev/console</filename>.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index e32ed1972e..3741cf9cc2 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,375 +23,349 @@ <refentry id="kernel-command-line"> - <refentryinfo> - <title>kernel-command-line</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>kernel-command-line</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>kernel-command-line</refname> - <refpurpose>Kernel command line parameters</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/proc/cmdline</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The kernel, the initial RAM disk (initrd) and - basic userspace functionality may be configured at boot via - kernel command line arguments.</para> - - <para>For command line parameters understood by the - kernel, please see <ulink - url="https://www.kernel.org/doc/Documentation/kernel-parameters.txt"><filename>kernel-parameters.txt</filename></ulink> - and - <citerefentry project='man-pages'><refentrytitle>bootparam</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - - <para>For command line parameters understood by the - initial RAM disk, please see - <citerefentry project='die-net'><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - or the documentation of the specific initrd - implementation of your installation.</para> - </refsect1> - - <refsect1> - <title>Core OS Command Line Arguments</title> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>systemd.unit=</varname></term> - <term><varname>rd.systemd.unit=</varname></term> - <term><varname>systemd.dump_core=</varname></term> - <term><varname>systemd.crash_shell=</varname></term> - <term><varname>systemd.crash_chvt=</varname></term> - <term><varname>systemd.confirm_spawn=</varname></term> - <term><varname>systemd.show_status=</varname></term> - <term><varname>systemd.log_target=</varname></term> - <term><varname>systemd.log_level=</varname></term> - <term><varname>systemd.log_color=</varname></term> - <term><varname>systemd.log_location=</varname></term> - <term><varname>systemd.default_standard_output=</varname></term> - <term><varname>systemd.default_standard_error=</varname></term> - <term><varname>systemd.setenv=</varname></term> - <listitem> - <para>Parameters understood by - the system and service manager - to control system behavior. For details, see - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.mask=</varname></term> - <term><varname>systemd.wants=</varname></term> - <term><varname>systemd.debug-shell</varname></term> - <listitem> - <para>Additional parameters - understood by - <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - to mask or start specific - units at boot, or invoke a - debug shell on tty9.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.restore_state=</varname></term> - <listitem> - <para>This parameter is understood by - several system tools to control - whether or not they should restore - system state from the previous boot. - For details, see - <citerefentry><refentrytitle>systemd-backlight@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd-rfkill@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>quiet</varname></term> - <listitem> - <para>Parameter understood by - both the kernel and the system - and service manager to control - console log verbosity. For - details, see - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>debug</varname></term> - <listitem> - <para>Parameter understood by - both the kernel and the system - and service manager to control - console log verbosity. For - details, see - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>-b</varname></term> - <term><varname>emergency</varname></term> - <term><varname>rescue</varname></term> - <term><varname>single</varname></term> - <term><varname>s</varname></term> - <term><varname>S</varname></term> - <term><varname>1</varname></term> - <term><varname>2</varname></term> - <term><varname>3</varname></term> - <term><varname>4</varname></term> - <term><varname>5</varname></term> - <listitem> - <para>Parameters understood by - the system and service - manager, as compatibility - options. For details, see - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>locale.LANG=</varname></term> - <term><varname>locale.LANGUAGE=</varname></term> - <term><varname>locale.LC_CTYPE=</varname></term> - <term><varname>locale.LC_NUMERIC=</varname></term> - <term><varname>locale.LC_TIME=</varname></term> - <term><varname>locale.LC_COLLATE=</varname></term> - <term><varname>locale.LC_MONETARY=</varname></term> - <term><varname>locale.LC_MESSAGES=</varname></term> - <term><varname>locale.LC_PAPER=</varname></term> - <term><varname>locale.LC_NAME=</varname></term> - <term><varname>locale.LC_ADDRESS=</varname></term> - <term><varname>locale.LC_TELEPHONE=</varname></term> - <term><varname>locale.LC_MEASUREMENT=</varname></term> - <term><varname>locale.LC_IDENTIFICATION=</varname></term> - <listitem> - <para>Parameters understood by - the system and service manager - to control locale and language - settings. For details, see - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>fsck.mode=</varname></term> - <term><varname>fsck.repair=</varname></term> - - <listitem> - <para>Parameters understood by - the file system checker - services. For details, see - <citerefentry><refentrytitle>systemd-fsck@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>quotacheck.mode=</varname></term> - - <listitem> - <para>Parameter understood by - the file quota checker - service. For details, see - <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.journald.forward_to_syslog=</varname></term> - <term><varname>systemd.journald.forward_to_kmsg=</varname></term> - <term><varname>systemd.journald.forward_to_console=</varname></term> - <term><varname>systemd.journald.forward_to_wall=</varname></term> - - <listitem> - <para>Parameters understood by - the journal service. For - details, see - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>vconsole.keymap=</varname></term> - <term><varname>vconsole.keymap.toggle=</varname></term> - <term><varname>vconsole.font=</varname></term> - <term><varname>vconsole.font.map=</varname></term> - <term><varname>vconsole.font.unimap=</varname></term> - - <listitem> - <para>Parameters understood by - the virtual console setup logic. For - details, see - <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>udev.log-priority=</varname></term> - <term><varname>rd.udev.log-priority=</varname></term> - <term><varname>udev.children-max=</varname></term> - <term><varname>rd.udev.children-max=</varname></term> - <term><varname>udev.exec-delay=</varname></term> - <term><varname>rd.udev.exec-delay=</varname></term> - <term><varname>udev.event-timeout=</varname></term> - <term><varname>rd.udev.event-timeout=</varname></term> - <term><varname>net.ifnames=</varname></term> - - <listitem> - <para>Parameters understood by - the device event managing daemon. For - details, see - <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>plymouth.enable=</varname></term> - - <listitem> - <para>May be used to disable - the Plymouth boot splash. For - details, see - <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>luks=</varname></term> - <term><varname>rd.luks=</varname></term> - <term><varname>luks.crypttab=</varname></term> - <term><varname>rd.luks.crypttab=</varname></term> - <term><varname>luks.name=</varname></term> - <term><varname>rd.luks.name=</varname></term> - <term><varname>luks.uuid=</varname></term> - <term><varname>rd.luks.uuid=</varname></term> - <term><varname>luks.options=</varname></term> - <term><varname>rd.luks.options=</varname></term> - <term><varname>luks.key=</varname></term> - <term><varname>rd.luks.key=</varname></term> - - <listitem> - <para>Configures the LUKS - full-disk encryption logic at - boot. For details, see - <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>fstab=</varname></term> - <term><varname>rd.fstab=</varname></term> - - <listitem> - <para>Configures the - <filename>/etc/fstab</filename> - logic at boot. For details, see - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>root=</varname></term> - <term><varname>rootfstype=</varname></term> - <term><varname>rootfsflags=</varname></term> - <term><varname>ro</varname></term> - <term><varname>rw</varname></term> - - <listitem> - <para>Configures the root file - system and its file system - type and mount options, as - well as whether it shall be - mounted read-only or - read-writable initially. For - details, see - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.gpt_auto=</varname></term> - <term><varname>rd.systemd.gpt_auto=</varname></term> - - <listitem> - <para>Configures whether GPT - based partition auto-discovery - shall be attempted. For - details, see - <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>modules-load=</varname></term> - <term><varname>rd.modules-load=</varname></term> - - <listitem> - <para>Load a specific kernel - module early at boot. For - details, see - <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>resume=</varname></term> - - <listitem> - <para>Enables resume from hibernation - using the specified device. - All <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>-like - paths are supported. For details, see - <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>bootparam</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fsck@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-backlight@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-rfkill@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>kernel-command-line</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>kernel-command-line</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>kernel-command-line</refname> + <refpurpose>Kernel command line parameters</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/proc/cmdline</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The kernel, the initial RAM disk (initrd) and + basic userspace functionality may be configured at boot via + kernel command line arguments.</para> + + <para>For command line parameters understood by the kernel, please + see <ulink + url="https://www.kernel.org/doc/Documentation/kernel-parameters.txt"><filename>kernel-parameters.txt</filename></ulink> + and + <citerefentry project='man-pages'><refentrytitle>bootparam</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>For command line parameters understood by the initial RAM + disk, please see + <citerefentry project='die-net'><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + or the documentation of the specific initrd implementation of your + installation.</para> + </refsect1> + + <refsect1> + <title>Core OS Command Line Arguments</title> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>systemd.unit=</varname></term> + <term><varname>rd.systemd.unit=</varname></term> + <term><varname>systemd.dump_core=</varname></term> + <term><varname>systemd.crash_shell=</varname></term> + <term><varname>systemd.crash_chvt=</varname></term> + <term><varname>systemd.confirm_spawn=</varname></term> + <term><varname>systemd.show_status=</varname></term> + <term><varname>systemd.log_target=</varname></term> + <term><varname>systemd.log_level=</varname></term> + <term><varname>systemd.log_color=</varname></term> + <term><varname>systemd.log_location=</varname></term> + <term><varname>systemd.default_standard_output=</varname></term> + <term><varname>systemd.default_standard_error=</varname></term> + <term><varname>systemd.setenv=</varname></term> + <listitem> + <para>Parameters understood by the system and service + manager to control system behavior. For details, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.mask=</varname></term> + <term><varname>systemd.wants=</varname></term> + <term><varname>systemd.debug-shell</varname></term> + <listitem> + <para>Additional parameters understood by + <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + to mask or start specific units at boot, or invoke a debug + shell on tty9.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.restore_state=</varname></term> + <listitem> + <para>This parameter is understood by several system tools + to control whether or not they should restore system state + from the previous boot. For details, see + <citerefentry><refentrytitle>systemd-backlight@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd-rfkill@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>quiet</varname></term> + <listitem> + <para>Parameter understood by both the kernel and the system + and service manager to control console log verbosity. For + details, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>debug</varname></term> + <listitem> + <para>Parameter understood by both the kernel and the system + and service manager to control console log verbosity. For + details, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>-b</varname></term> + <term><varname>emergency</varname></term> + <term><varname>rescue</varname></term> + <term><varname>single</varname></term> + <term><varname>s</varname></term> + <term><varname>S</varname></term> + <term><varname>1</varname></term> + <term><varname>2</varname></term> + <term><varname>3</varname></term> + <term><varname>4</varname></term> + <term><varname>5</varname></term> + <listitem> + <para>Parameters understood by the system and service + manager, as compatibility options. For details, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>locale.LANG=</varname></term> + <term><varname>locale.LANGUAGE=</varname></term> + <term><varname>locale.LC_CTYPE=</varname></term> + <term><varname>locale.LC_NUMERIC=</varname></term> + <term><varname>locale.LC_TIME=</varname></term> + <term><varname>locale.LC_COLLATE=</varname></term> + <term><varname>locale.LC_MONETARY=</varname></term> + <term><varname>locale.LC_MESSAGES=</varname></term> + <term><varname>locale.LC_PAPER=</varname></term> + <term><varname>locale.LC_NAME=</varname></term> + <term><varname>locale.LC_ADDRESS=</varname></term> + <term><varname>locale.LC_TELEPHONE=</varname></term> + <term><varname>locale.LC_MEASUREMENT=</varname></term> + <term><varname>locale.LC_IDENTIFICATION=</varname></term> + <listitem> + <para>Parameters understood by the system and service + manager to control locale and language settings. For + details, see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>fsck.mode=</varname></term> + <term><varname>fsck.repair=</varname></term> + + <listitem> + <para>Parameters understood by the file system checker + services. For details, see + <citerefentry><refentrytitle>systemd-fsck@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>quotacheck.mode=</varname></term> + + <listitem> + <para>Parameter understood by the file quota checker + service. For details, see + <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.journald.forward_to_syslog=</varname></term> + <term><varname>systemd.journald.forward_to_kmsg=</varname></term> + <term><varname>systemd.journald.forward_to_console=</varname></term> + <term><varname>systemd.journald.forward_to_wall=</varname></term> + + <listitem> + <para>Parameters understood by the journal service. For + details, see + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>vconsole.keymap=</varname></term> + <term><varname>vconsole.keymap.toggle=</varname></term> + <term><varname>vconsole.font=</varname></term> + <term><varname>vconsole.font.map=</varname></term> + <term><varname>vconsole.font.unimap=</varname></term> + + <listitem> + <para>Parameters understood by the virtual console setup + logic. For details, see + <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>udev.log-priority=</varname></term> + <term><varname>rd.udev.log-priority=</varname></term> + <term><varname>udev.children-max=</varname></term> + <term><varname>rd.udev.children-max=</varname></term> + <term><varname>udev.exec-delay=</varname></term> + <term><varname>rd.udev.exec-delay=</varname></term> + <term><varname>udev.event-timeout=</varname></term> + <term><varname>rd.udev.event-timeout=</varname></term> + <term><varname>net.ifnames=</varname></term> + + <listitem> + <para>Parameters understood by the device event managing + daemon. For details, see + <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>plymouth.enable=</varname></term> + + <listitem> + <para>May be used to disable the Plymouth boot splash. For + details, see + <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks=</varname></term> + <term><varname>rd.luks=</varname></term> + <term><varname>luks.crypttab=</varname></term> + <term><varname>rd.luks.crypttab=</varname></term> + <term><varname>luks.name=</varname></term> + <term><varname>rd.luks.name=</varname></term> + <term><varname>luks.uuid=</varname></term> + <term><varname>rd.luks.uuid=</varname></term> + <term><varname>luks.options=</varname></term> + <term><varname>rd.luks.options=</varname></term> + <term><varname>luks.key=</varname></term> + <term><varname>rd.luks.key=</varname></term> + + <listitem> + <para>Configures the LUKS full-disk encryption logic at + boot. For details, see + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>fstab=</varname></term> + <term><varname>rd.fstab=</varname></term> + + <listitem> + <para>Configures the <filename>/etc/fstab</filename> logic + at boot. For details, see + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>root=</varname></term> + <term><varname>rootfstype=</varname></term> + <term><varname>rootfsflags=</varname></term> + <term><varname>ro</varname></term> + <term><varname>rw</varname></term> + + <listitem> + <para>Configures the root file system and its file system + type and mount options, as well as whether it shall be + mounted read-only or read-writable initially. For details, + see + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.gpt_auto=</varname></term> + <term><varname>rd.systemd.gpt_auto=</varname></term> + + <listitem> + <para>Configures whether GPT based partition auto-discovery + shall be attempted. For details, see + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>modules-load=</varname></term> + <term><varname>rd.modules-load=</varname></term> + + <listitem> + <para>Load a specific kernel module early at boot. For + details, see + <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>resume=</varname></term> + + <listitem> + <para>Enables resume from hibernation using the specified + device. All + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>-like + paths are supported. For details, see + <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>bootparam</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>dracut.cmdline</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-debug-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fsck@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-backlight@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-rfkill@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/locale.conf.xml b/man/locale.conf.xml index 67bcc18e2a..1566dae2c3 100644 --- a/man/locale.conf.xml +++ b/man/locale.conf.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,136 +23,131 @@ --> <refentry id="locale.conf"> - <refentryinfo> - <title>locale.conf</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>locale.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>locale.conf</refname> - <refpurpose>Configuration file for locale settings</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/locale.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <filename>/etc/locale.conf</filename> file - configures system-wide locale settings. It is read at - early-boot by - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> - - <para>The basic file format of - <filename>locale.conf</filename> is a - newline-separated list of environment-like - shell-compatible variable assignments. It is possible - to source the configuration from shell scripts, - however, beyond mere variable assignments, no shell - features are supported, allowing applications to read - the file without implementing a shell compatible - execution engine.</para> - - <para>Note that the kernel command line options - <varname>locale.LANG=</varname>, - <varname>locale.LANGUAGE=</varname>, - <varname>locale.LC_CTYPE=</varname>, - <varname>locale.LC_NUMERIC=</varname>, - <varname>locale.LC_TIME=</varname>, - <varname>locale.LC_COLLATE=</varname>, - <varname>locale.LC_MONETARY=</varname>, - <varname>locale.LC_MESSAGES=</varname>, - <varname>locale.LC_PAPER=</varname>, - <varname>locale.LC_NAME=</varname>, - <varname>locale.LC_ADDRESS=</varname>, - <varname>locale.LC_TELEPHONE=</varname>, - <varname>locale.LC_MEASUREMENT=</varname>, - <varname>locale.LC_IDENTIFICATION=</varname> may be - used to override the locale settings at boot.</para> - - <para>The locale settings configured in - <filename>/etc/locale.conf</filename> are system-wide - and are inherited by every service or user, unless - overridden or unset by individual programs or - individual users.</para> - - <para>Depending on the operating system, other - configuration files might be checked for locale - configuration as well, however only as - fallback.</para> - - <para><citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - may be used to alter the settings in this file during - runtime from the command line. Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize them on mounted (but not booted) system - images.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following locale settings may be set using - <filename>/etc/locale.conf</filename>: - <varname>LANG=</varname>, - <varname>LANGUAGE=</varname>, - <varname>LC_CTYPE=</varname>, - <varname>LC_NUMERIC=</varname>, - <varname>LC_TIME=</varname>, - <varname>LC_COLLATE=</varname>, - <varname>LC_MONETARY=</varname>, - <varname>LC_MESSAGES=</varname>, - <varname>LC_PAPER=</varname>, - <varname>LC_NAME=</varname>, - <varname>LC_ADDRESS=</varname>, - <varname>LC_TELEPHONE=</varname>, - <varname>LC_MEASUREMENT=</varname>, - <varname>LC_IDENTIFICATION=</varname>. Note that - <varname>LC_ALL</varname> may not be configured in - this file. For details about the meaning and semantics - of these settings, refer to - <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>Example</title> - - <example> - <title>German locale with English messages</title> - - <para><filename>/etc/locale.conf</filename>:</para> - - <programlisting>LANG=de_DE.UTF-8 + <refentryinfo> + <title>locale.conf</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>locale.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>locale.conf</refname> + <refpurpose>Configuration file for locale settings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/locale.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/locale.conf</filename> file configures + system-wide locale settings. It is read at early-boot by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + + <para>The basic file format of <filename>locale.conf</filename> is + a newline-separated list of environment-like shell-compatible + variable assignments. It is possible to source the configuration + from shell scripts, however, beyond mere variable assignments, no + shell features are supported, allowing applications to read the + file without implementing a shell compatible execution + engine.</para> + + <para>Note that the kernel command line options + <varname>locale.LANG=</varname>, + <varname>locale.LANGUAGE=</varname>, + <varname>locale.LC_CTYPE=</varname>, + <varname>locale.LC_NUMERIC=</varname>, + <varname>locale.LC_TIME=</varname>, + <varname>locale.LC_COLLATE=</varname>, + <varname>locale.LC_MONETARY=</varname>, + <varname>locale.LC_MESSAGES=</varname>, + <varname>locale.LC_PAPER=</varname>, + <varname>locale.LC_NAME=</varname>, + <varname>locale.LC_ADDRESS=</varname>, + <varname>locale.LC_TELEPHONE=</varname>, + <varname>locale.LC_MEASUREMENT=</varname>, + <varname>locale.LC_IDENTIFICATION=</varname> may be + used to override the locale settings at boot.</para> + + <para>The locale settings configured in + <filename>/etc/locale.conf</filename> are system-wide and are + inherited by every service or user, unless overridden or unset by + individual programs or individual users.</para> + + <para>Depending on the operating system, other configuration files + might be checked for locale configuration as well, however only as + fallback.</para> + + <para><citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + may be used to alter the settings in this file during runtime from + the command line. Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize them on mounted (but not booted) system + images.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following locale settings may be set using + <filename>/etc/locale.conf</filename>: + <varname>LANG=</varname>, + <varname>LANGUAGE=</varname>, + <varname>LC_CTYPE=</varname>, + <varname>LC_NUMERIC=</varname>, + <varname>LC_TIME=</varname>, + <varname>LC_COLLATE=</varname>, + <varname>LC_MONETARY=</varname>, + <varname>LC_MESSAGES=</varname>, + <varname>LC_PAPER=</varname>, + <varname>LC_NAME=</varname>, + <varname>LC_ADDRESS=</varname>, + <varname>LC_TELEPHONE=</varname>, + <varname>LC_MEASUREMENT=</varname>, + <varname>LC_IDENTIFICATION=</varname>. + Note that <varname>LC_ALL</varname> may not be configured in this + file. For details about the meaning and semantics of these + settings, refer to + <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <example> + <title>German locale with English messages</title> + + <para><filename>/etc/locale.conf</filename>:</para> + + <programlisting>LANG=de_DE.UTF-8 LC_MESSAGES=en_US.UTF-8</programlisting> - </example> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + </example> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/localectl.xml b/man/localectl.xml index b472b6bd9c..aae6e0629c 100644 --- a/man/localectl.xml +++ b/man/localectl.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,227 +22,200 @@ --> <refentry id="localectl" conditional='ENABLE_LOCALED' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>localectl</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>localectl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>localectl</refname> - <refpurpose>Control the system locale and keyboard layout settings</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>localectl</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="req">COMMAND</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>localectl</command> may be used to - query and change the system locale and keyboard layout - settings.</para> - - <para>The system locale controls the language settings - of system services and of the UI before the user logs - in, such as the display manager, as well as the - default for users after login.</para> - - <para>The keyboard settings control the keyboard - layout used on the text console and of the graphical - UI before the user logs in, such as the display - manager, as well as the default for users after - login.</para> - - <para>Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the system locale for mounted (but not - booted) system images.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--no-ask-password</option></term> - - <listitem><para>Do not query the user - for authentication for privileged - operations.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-convert</option></term> - - <listitem><para>If - <command>set-keymap</command> or - <command>set-x11-keymap</command> is - invoked and this option is passed, then - the keymap will not be converted from - the console to X11, or X11 to console, - respectively.</para></listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="host" /> - - <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> - - <para>The following commands are understood:</para> - - <variablelist> - <varlistentry> - <term><command>status</command></term> - - <listitem><para>Show current settings - of the system locale and keyboard - mapping.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-locale LOCALE...</command></term> - - <listitem><para>Set the system - locale. This takes one or more - assignments such as "LANG=de_DE.utf8", - "LC_MESSAGES=en_GB.utf8", and so - on. See - <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details on the available settings - and their meanings. Use - <command>list-locales</command> for a - list of available locales (see below). - </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>list-locales</command></term> - - <listitem><para>List available locales - useful for configuration with - <command>set-locale</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-keymap MAP [TOGGLEMAP]</command></term> - - <listitem><para>Set the system - keyboard mapping for the console and - X11. This takes a mapping name (such - as "de" or "us"), and possibly a - second one to define a toggle keyboard - mapping. Unless - <option>--no-convert</option> is - passed, the selected setting is also - applied as the default system keyboard - mapping of X11, after converting it to - the closest matching X11 keyboard - mapping. Use - <command>list-keymaps</command> for a - list of available keyboard mappings - (see below).</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>list-keymaps</command></term> - - <listitem><para>List available - keyboard mappings for the console, - useful for configuration with - <command>set-keymap</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-x11-keymap LAYOUT [MODEL [VARIANT [OPTIONS]]]</command></term> - - <listitem><para>Set the system default - keyboard mapping for X11 and the - virtual console. This takes a keyboard - mapping name (such as - <literal>de</literal> or - <literal>us</literal>), and possibly a - model, variant, and options, see - <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry> - for details. Unless - <option>--no-convert</option> is - passed, the selected setting is also - applied as the system console keyboard - mapping, after converting it to the - closest matching console keyboard - mapping.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>list-x11-keymap-models</command></term> - <term><command>list-x11-keymap-layouts</command></term> - <term><command>list-x11-keymap-variants [LAYOUT]</command></term> - <term><command>list-x11-keymap-options</command></term> - - <listitem><para>List available X11 - keymap models, layouts, variants and - options, useful for configuration with - <command>set-keymap</command>. The - command - <command>list-x11-keymap-variants</command> - optionally takes a layout parameter to - limit the output to the variants - suitable for the specific - layout.</para></listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <xi:include href="less-variables.xml" /> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry>, - <ulink url="http://www.x.org/releases/current/doc/xorg-docs/input/XKB-Config.html"> - The XKB Configuration Guide - </ulink>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>localectl</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>localectl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>localectl</refname> + <refpurpose>Control the system locale and keyboard layout settings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>localectl</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="req">COMMAND</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>localectl</command> may be used to query and change + the system locale and keyboard layout settings.</para> + + <para>The system locale controls the language settings of system + services and of the UI before the user logs in, such as the + display manager, as well as the default for users after + login.</para> + + <para>The keyboard settings control the keyboard layout used on + the text console and of the graphical UI before the user logs in, + such as the display manager, as well as the default for users + after login.</para> + + <para>Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize the system locale for mounted (but not booted) + system images.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--no-ask-password</option></term> + + <listitem><para>Do not query the user for authentication for + privileged operations.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-convert</option></term> + + <listitem><para>If <command>set-keymap</command> or + <command>set-x11-keymap</command> is invoked and this option + is passed, then the keymap will not be converted from the + console to X11, or X11 to console, + respectively.</para></listitem> + </varlistentry> + + <xi:include href="user-system-options.xml" xpointer="host" /> + + <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> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>status</command></term> + + <listitem><para>Show current settings of the system locale and + keyboard mapping.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-locale LOCALE...</command></term> + + <listitem><para>Set the system locale. This takes one or more + assignments such as "LANG=de_DE.utf8", + "LC_MESSAGES=en_GB.utf8", and so on. See + <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details on the available settings and their meanings. Use + <command>list-locales</command> for a list of available + locales (see below). </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>list-locales</command></term> + + <listitem><para>List available locales useful for + configuration with + <command>set-locale</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-keymap MAP [TOGGLEMAP]</command></term> + + <listitem><para>Set the system keyboard mapping for the + console and X11. This takes a mapping name (such as "de" or + "us"), and possibly a second one to define a toggle keyboard + mapping. Unless <option>--no-convert</option> is passed, the + selected setting is also applied as the default system + keyboard mapping of X11, after converting it to the closest + matching X11 keyboard mapping. Use + <command>list-keymaps</command> for a list of available + keyboard mappings (see below).</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>list-keymaps</command></term> + + <listitem><para>List available keyboard mappings for the + console, useful for configuration with + <command>set-keymap</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-x11-keymap LAYOUT [MODEL [VARIANT [OPTIONS]]]</command></term> + + <listitem><para>Set the system default keyboard mapping for + X11 and the virtual console. This takes a keyboard mapping + name (such as <literal>de</literal> or <literal>us</literal>), + and possibly a model, variant, and options, see + <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry> + for details. Unless <option>--no-convert</option> is passed, + the selected setting is also applied as the system console + keyboard mapping, after converting it to the closest matching + console keyboard mapping.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>list-x11-keymap-models</command></term> + <term><command>list-x11-keymap-layouts</command></term> + <term><command>list-x11-keymap-variants [LAYOUT]</command></term> + <term><command>list-x11-keymap-options</command></term> + + <listitem><para>List available X11 keymap models, layouts, + variants and options, useful for configuration with + <command>set-keymap</command>. The command + <command>list-x11-keymap-variants</command> optionally takes a + layout parameter to limit the output to the variants suitable + for the specific layout.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <xi:include href="less-variables.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>kbd</refentrytitle><manvolnum>4</manvolnum></citerefentry>, + <ulink url="http://www.x.org/releases/current/doc/xorg-docs/input/XKB-Config.html"> + The XKB Configuration Guide + </ulink>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/localtime.xml b/man/localtime.xml index 1cbdf68274..184f5808e9 100644 --- a/man/localtime.xml +++ b/man/localtime.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -24,84 +24,81 @@ --> <refentry id="localtime"> - <refentryinfo> - <title>localtime</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - <author> - <contrib>Developer</contrib> - <firstname>Shawn</firstname> - <surname>Landden</surname> - <email>shawnlandden@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>localtime</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>localtime</refname> - <refpurpose>Local timezone configuration file</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/localtime</filename> -> <filename>../usr/share/zoneinfo/…</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <filename>/etc/localtime</filename> file - configures the system-wide timezone of the local - system that is used by applications for presentation - to the user. It should be an absolute or relative - symbolic link pointing to - <filename>/usr/share/zoneinfo/</filename>, followed by - a timezone identifier such as - <literal>Europe/Berlin</literal> or - <literal>Etc/UTC</literal>. The resulting link should - lead to the corresponding binary - <citerefentry project='man-pages'><refentrytitle>tzfile</refentrytitle><manvolnum>5</manvolnum></citerefentry> - timezone data for the configured timezone.</para> - - <para>Because the timezone identifier is extracted from - the symlink target name of - <filename>/etc/localtime</filename>, this file may not - be a normal file or hardlink.</para> - - <para>The timezone may be overridden for individual - programs by using the TZ environment variable. See - <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - - <para>You may use - <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to change the settings of this file from the command - line during runtime. Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the time zone on mounted (but not - booted) system images.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>tzset</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>localtime</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + <author> + <contrib>Developer</contrib> + <firstname>Shawn</firstname> + <surname>Landden</surname> + <email>shawnlandden@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>localtime</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>localtime</refname> + <refpurpose>Local timezone configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/localtime</filename> -> <filename>../usr/share/zoneinfo/…</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/localtime</filename> file configures the + system-wide timezone of the local system that is used by + applications for presentation to the user. It should be an + absolute or relative symbolic link pointing to + <filename>/usr/share/zoneinfo/</filename>, followed by a timezone + identifier such as <literal>Europe/Berlin</literal> or + <literal>Etc/UTC</literal>. The resulting link should lead to the + corresponding binary + <citerefentry project='man-pages'><refentrytitle>tzfile</refentrytitle><manvolnum>5</manvolnum></citerefentry> + timezone data for the configured timezone.</para> + + <para>Because the timezone identifier is extracted from the + symlink target name of <filename>/etc/localtime</filename>, this + file may not be a normal file or hardlink.</para> + + <para>The timezone may be overridden for individual programs by + using the <varname>$TZ</varname> environment variable. See + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>You may use + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to change the settings of this file from the command line during + runtime. Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize the time zone on mounted (but not booted) system + images.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>tzset</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/loginctl.xml b/man/loginctl.xml index 11ed0ee460..9dda14d454 100644 --- a/man/loginctl.xml +++ b/man/loginctl.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,485 +22,394 @@ --> <refentry id="loginctl" conditional='ENABLE_LOGIND' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>loginctl</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>loginctl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>loginctl</refname> - <refpurpose>Control the systemd login manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>loginctl</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="req">COMMAND</arg> - <arg choice="opt" rep="repeat">NAME</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>loginctl</command> may be used to - introspect and control the state of the - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - login manager <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--no-ask-password</option></term> - - <listitem><para>Do not query the user - for authentication for privileged - operations.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-p</option></term> - <term><option>--property=</option></term> - - <listitem><para>When showing - session/user/seat properties, limit - display to certain properties as - specified as argument. If not - specified, all set properties are - shown. The argument should be a - property name, such as - <literal>Sessions</literal>. If - specified more than once, all - properties with the specified names - are shown.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-a</option></term> - <term><option>--all</option></term> - - <listitem><para>When showing - session/user/seat properties, show all - properties regardless of whether they are - set or not.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</option></term> - <term><option>--full</option></term> - - <listitem><para>Do not ellipsize - process tree entries.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--kill-who=</option></term> - - <listitem><para>When used with - <command>kill-session</command>, - choose which processes to kill. Must - be one of <option>leader</option>, or - <option>all</option> to select whether - to kill only the leader process of the - session or all processes of the - session. If omitted, defaults to - <option>all</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-s</option></term> - <term><option>--signal=</option></term> - - <listitem><para>When used with - <command>kill-session</command> or - <command>kill-user</command>, choose - which signal to send to selected - processes. Must be one of the well - known signal specifiers, such as - <constant>SIGTERM</constant>, - <constant>SIGINT</constant> or - <constant>SIGSTOP</constant>. If - omitted, defaults to - <constant>SIGTERM</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - <term><option>--lines=</option></term> - - <listitem><para>When used with - <command>user-status</command> and - <command>session-status</command>, - controls the number of journal lines - to show, counting from the most recent - ones. Takes a positive integer - argument. Defaults to 10.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-o</option></term> - <term><option>--output=</option></term> - - <listitem><para>When used with - <command>user-status</command> and - <command>session-status</command>, - controls the formatting of the journal - entries that are shown. For the - available choices, see - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - Defaults to - <literal>short</literal>.</para></listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="no-pager" /> - <xi:include href="standard-options.xml" xpointer="no-legend" /> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Commands</title> - - <para>The following commands are understood:</para> - - <refsect2><title>Session Commands</title><variablelist> - - <varlistentry> - <term><command>list-sessions</command></term> - - <listitem><para>List current sessions.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>session-status</command> <optional><replaceable>ID</replaceable>...</optional></term> - - <listitem><para>Show terse runtime - status information about one or more - sessions, followed by the most recent - log data from the journal. Takes one - or more session identifiers as - parameters. If no session identifiers - are passed the status of the caller's - session is shown. This function is - intended to generate human-readable - output. If you are looking for - computer-parsable output, use - <command>show-session</command> - instead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>show-session</command> <optional><replaceable>ID</replaceable>...</optional></term> - - <listitem><para>Show properties of one - or more sessions or the manager - itself. If no argument is specified, - properties of the manager will be - shown. If a session ID is specified, - properties of the session are shown. By - default, empty properties are - suppressed. Use <option>--all</option> - to show those too. To select specific - properties to show, use - <option>--property=</option>. This - command is intended to be used - whenever computer-parsable output is - required. Use - <command>session-status</command> if - you are looking for formatted - human-readable - output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>activate</command> <optional><replaceable>ID</replaceable></optional></term> - - <listitem><para>Activate a - session. This brings a session into - the foreground, if another session is - currently in the foreground on the - respective seat. Takes a session - identifier as argument. If no argument - is specified the session of the caller - is put into - foreground.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>lock-session</command> <optional><replaceable>ID</replaceable>...</optional></term> - <term><command>unlock-session</command> <optional><replaceable>ID</replaceable>...</optional></term> - - <listitem><para>Activates/deactivates - the screen lock on one or more - sessions, if the session supports - it. Takes one or more session - identifiers as arguments. If no - argument is specified the session of - the caller is locked/unlocked. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>lock-sessions</command></term> - <term><command>unlock-sessions</command></term> - - <listitem><para>Activates/deactivates - the screen lock on all current - sessions supporting it. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>terminate-session</command> <replaceable>ID</replaceable>...</term> - - <listitem><para>Terminates a session. - This kills all processes of the - session and deallocates all resources - attached to the session. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>kill-session</command> <replaceable>ID</replaceable>...</term> - - <listitem><para>Send a signal to one - or more processes of the session. Use - <option>--kill-who=</option> to select - which process to kill. Use - <option>--signal=</option> to select - the signal to send.</para></listitem> - </varlistentry> - </variablelist></refsect2> - - <refsect2><title>User Commands</title><variablelist> - <varlistentry> - <term><command>list-users</command></term> - - <listitem><para>List currently logged - in users.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>user-status</command> <optional><replaceable>USER</replaceable>...</optional></term> - - <listitem><para>Show terse runtime - status information about one or more - logged in users, followed by the most - recent log data from the - journal. Takes one or more user names - or numeric user IDs as parameters. If - no parameters are passed the status of - the caller's user is shown. This - function is intended to generate - human-readable output. If you are - looking for computer-parsable output, - use <command>show-user</command> - instead. Users may be specified by - their usernames or numeric user IDs. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>show-user</command> <optional><replaceable>USER</replaceable>...</optional></term> - - <listitem><para>Show properties of one - or more users or the manager - itself. If no argument is specified, - properties of the manager will be - shown. If a user is specified, - properties of the user are shown. By - default, empty properties are - suppressed. Use <option>--all</option> - to show those too. To select specific - properties to show, use - <option>--property=</option>. This - command is intended to be used - whenever computer-parsable output is - required. Use - <command>user-status</command> if - you are looking for formatted - human-readable - output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>enable-linger</command> <optional><replaceable>USER</replaceable>...</optional></term> - <term><command>disable-linger</command> <optional><replaceable>USER</replaceable>...</optional></term> - - <listitem><para>Enable/disable user - lingering for one or more users. If - enabled for a specific user, a user - manager is spawned for the user at - boot and kept around after - logouts. 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.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>terminate-user</command> <replaceable>USER</replaceable>...</term> - - <listitem><para>Terminates all - sessions of a user. This kills all - processes of all sessions of the user - and deallocates all runtime resources - attached to the user. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>kill-user</command> <replaceable>USER</replaceable>...</term> - - <listitem><para>Send a signal to all - processes of a user. Use - <option>--signal=</option> to select - the signal to send.</para></listitem> - </varlistentry> - </variablelist></refsect2> - - <refsect2><title>Seat Commands</title><variablelist> - <varlistentry> - <term><command>list-seats</command></term> - - <listitem><para>List currently - available seats on the local - system.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>seat-status</command> <optional><replaceable>NAME</replaceable>...</optional></term> - - <listitem><para>Show terse runtime - status information about one or more - seats. Takes one or more seat names as - parameters. If no seat names are - passed the status of the caller's - session's seat is shown. This function - is intended to generate human-readable - output. If you are looking for - computer-parsable output, use - <command>show-seat</command> - instead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>show-seat</command> <optional><replaceable>NAME</replaceable>...</optional></term> - - <listitem><para>Show properties of one - or more seats or the manager - itself. If no argument is specified, - properties of the manager will be - shown. If a seat is specified, - properties of the seat are shown. By - default, empty properties are - suppressed. Use <option>--all</option> - to show those too. To select specific - properties to show, use - <option>--property=</option>. This - command is intended to be used - whenever computer-parsable output is - required. Use - <command>seat-status</command> if you - are looking for formatted - human-readable - output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</term> - - <listitem><para>Persistently attach - one or more devices to a seat. The - devices should be specified via device - paths in the <filename>/sys</filename> - file system. To create a new seat, - attach at least one graphics card to a - previously unused seat name. Seat - names may consist only of a-z, A-Z, - 0-9, <literal>-</literal> and - <literal>_</literal> and must be - prefixed with <literal>seat</literal>. - To drop assignment of a device to a - specific seat, just reassign it to a - different seat, or use - <command>flush-devices</command>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><command>flush-devices</command></term> - - <listitem><para>Removes all device - assignments previously created with - <command>attach</command>. After this - call, only automatically generated - seats will remain, and all seat - hardware is assigned to - them.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>terminate-seat</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Terminates all - sessions on a seat. This kills all - processes of all sessions on the seat - and deallocates all runtime resources - attached to them.</para></listitem> - </varlistentry> - </variablelist></refsect2> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <xi:include href="less-variables.xml" /> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>loginctl</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>loginctl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>loginctl</refname> + <refpurpose>Control the systemd login manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>loginctl</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="req">COMMAND</arg> + <arg choice="opt" rep="repeat">NAME</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>loginctl</command> may be used to introspect and + control the state of the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + login manager + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--no-ask-password</option></term> + + <listitem><para>Do not query the user for authentication for + privileged operations.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-p</option></term> + <term><option>--property=</option></term> + + <listitem><para>When showing session/user/seat properties, + limit display to certain properties as specified as argument. + If not specified, all set properties are shown. The argument + should be a property name, such as + <literal>Sessions</literal>. If specified more than once, all + properties with the specified names are + shown.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-a</option></term> + <term><option>--all</option></term> + + <listitem><para>When showing session/user/seat properties, + show all properties regardless of whether they are set or + not.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-l</option></term> + <term><option>--full</option></term> + + <listitem><para>Do not ellipsize process tree entries.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--kill-who=</option></term> + + <listitem><para>When used with + <command>kill-session</command>, choose which processes to + kill. Must be one of <option>leader</option>, or + <option>all</option> to select whether to kill only the leader + process of the session or all processes of the session. If + omitted, defaults to <option>all</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-s</option></term> + <term><option>--signal=</option></term> + + <listitem><para>When used with <command>kill-session</command> + or <command>kill-user</command>, choose which signal to send + to selected processes. Must be one of the well known signal + specifiers, such as <constant>SIGTERM</constant>, + <constant>SIGINT</constant> or <constant>SIGSTOP</constant>. + If omitted, defaults to + <constant>SIGTERM</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-n</option></term> + <term><option>--lines=</option></term> + + <listitem><para>When used with <command>user-status</command> + and <command>session-status</command>, controls the number of + journal lines to show, counting from the most recent ones. + Takes a positive integer argument. Defaults to 10.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-o</option></term> + <term><option>--output=</option></term> + + <listitem><para>When used with <command>user-status</command> + and <command>session-status</command>, controls the formatting + of the journal entries that are shown. For the available + choices, see + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + Defaults to <literal>short</literal>.</para></listitem> + </varlistentry> + + <xi:include href="user-system-options.xml" xpointer="host" /> + <xi:include href="user-system-options.xml" xpointer="machine" /> + + <xi:include href="standard-options.xml" xpointer="no-pager" /> + <xi:include href="standard-options.xml" xpointer="no-legend" /> + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Commands</title> + + <para>The following commands are understood:</para> + + <refsect2><title>Session Commands</title><variablelist> + + <varlistentry> + <term><command>list-sessions</command></term> + + <listitem><para>List current sessions.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>session-status</command> <optional><replaceable>ID</replaceable>...</optional></term> + + <listitem><para>Show terse runtime status information about + one or more sessions, followed by the most recent log data + from the journal. Takes one or more session identifiers as + parameters. If no session identifiers are passed the status of + the caller's session is shown. This function is intended to + generate human-readable output. If you are looking for + computer-parsable output, use <command>show-session</command> + instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>show-session</command> <optional><replaceable>ID</replaceable>...</optional></term> + + <listitem><para>Show properties of one or more sessions or the + manager itself. If no argument is specified, properties of the + manager will be shown. If a session ID is specified, + properties of the session are shown. By default, empty + properties are suppressed. Use <option>--all</option> to show + those too. To select specific properties to show, use + <option>--property=</option>. This command is intended to be + used whenever computer-parsable output is required. Use + <command>session-status</command> if you are looking for + formatted human-readable output.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>activate</command> <optional><replaceable>ID</replaceable></optional></term> + + <listitem><para>Activate a session. This brings a session into + the foreground, if another session is currently in the + foreground on the respective seat. Takes a session identifier + as argument. If no argument is specified the session of the + caller is put into foreground.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>lock-session</command> <optional><replaceable>ID</replaceable>...</optional></term> + <term><command>unlock-session</command> <optional><replaceable>ID</replaceable>...</optional></term> + + <listitem><para>Activates/deactivates the screen lock on one + or more sessions, if the session supports it. Takes one or + more session identifiers as arguments. If no argument is + specified the session of the caller is locked/unlocked. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>lock-sessions</command></term> + <term><command>unlock-sessions</command></term> + + <listitem><para>Activates/deactivates the screen lock on all + current sessions supporting it. </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>terminate-session</command> <replaceable>ID</replaceable>...</term> + + <listitem><para>Terminates a session. This kills all processes + of the session and deallocates all resources attached to the + session. </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>kill-session</command> <replaceable>ID</replaceable>...</term> + + <listitem><para>Send a signal to one or more processes of the + session. Use <option>--kill-who=</option> to select which + process to kill. Use <option>--signal=</option> to select the + signal to send.</para></listitem> + </varlistentry> + </variablelist></refsect2> + + <refsect2><title>User Commands</title><variablelist> + <varlistentry> + <term><command>list-users</command></term> + + <listitem><para>List currently logged in users. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>user-status</command> <optional><replaceable>USER</replaceable>...</optional></term> + + <listitem><para>Show terse runtime status information about + one or more logged in users, followed by the most recent log + data from the journal. Takes one or more user names or numeric + user IDs as parameters. If no parameters are passed the status + of the caller's user is shown. This function is intended to + generate human-readable output. If you are looking for + computer-parsable output, use <command>show-user</command> + instead. Users may be specified by their usernames or numeric + user IDs. </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>show-user</command> <optional><replaceable>USER</replaceable>...</optional></term> + + <listitem><para>Show properties of one or more users or the + manager itself. If no argument is specified, properties of the + manager will be shown. If a user is specified, properties of + the user are shown. By default, empty properties are + suppressed. Use <option>--all</option> to show those too. To + select specific properties to show, use + <option>--property=</option>. This command is intended to be + used whenever computer-parsable output is required. Use + <command>user-status</command> if you are looking for + formatted human-readable output.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>enable-linger</command> <optional><replaceable>USER</replaceable>...</optional></term> + <term><command>disable-linger</command> <optional><replaceable>USER</replaceable>...</optional></term> + + <listitem><para>Enable/disable user lingering for one or more + users. If enabled for a specific user, a user manager is + spawned for the user at boot and kept around after logouts. + 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. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>terminate-user</command> <replaceable>USER</replaceable>...</term> + + <listitem><para>Terminates all sessions of a user. This kills + all processes of all sessions of the user and deallocates all + runtime resources attached to the user.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>kill-user</command> <replaceable>USER</replaceable>...</term> + + <listitem><para>Send a signal to all processes of a user. Use + <option>--signal=</option> to select the signal to send. + </para></listitem> + </varlistentry> + </variablelist></refsect2> + + <refsect2><title>Seat Commands</title><variablelist> + <varlistentry> + <term><command>list-seats</command></term> + + <listitem><para>List currently available seats on the local + system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>seat-status</command> <optional><replaceable>NAME</replaceable>...</optional></term> + + <listitem><para>Show terse runtime status information about + one or more seats. Takes one or more seat names as parameters. + If no seat names are passed the status of the caller's + session's seat is shown. This function is intended to generate + human-readable output. If you are looking for + computer-parsable output, use <command>show-seat</command> + instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>show-seat</command> <optional><replaceable>NAME</replaceable>...</optional></term> + + <listitem><para>Show properties of one or more seats or the + manager itself. If no argument is specified, properties of the + manager will be shown. If a seat is specified, properties of + the seat are shown. By default, empty properties are + suppressed. Use <option>--all</option> to show those too. To + select specific properties to show, use + <option>--property=</option>. This command is intended to be + used whenever computer-parsable output is required. Use + <command>seat-status</command> if you are looking for + formatted human-readable output.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</term> + + <listitem><para>Persistently attach one or more devices to a + seat. The devices should be specified via device paths in the + <filename>/sys</filename> file system. To create a new seat, + attach at least one graphics card to a previously unused seat + name. Seat names may consist only of a-z, A-Z, 0-9, + <literal>-</literal> and <literal>_</literal> and must be + prefixed with <literal>seat</literal>. To drop assignment of a + device to a specific seat, just reassign it to a different + seat, or use <command>flush-devices</command>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>flush-devices</command></term> + + <listitem><para>Removes all device assignments previously + created with <command>attach</command>. After this call, only + automatically generated seats will remain, and all seat + hardware is assigned to them.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>terminate-seat</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Terminates all sessions on a seat. This kills + all processes of all sessions on the seat and deallocates all + runtime resources attached to them.</para></listitem> + </varlistentry> + </variablelist></refsect2> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <xi:include href="less-variables.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/logind.conf.xml b/man/logind.conf.xml index e927cf4451..0818497be0 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,344 +23,272 @@ --> <refentry id="logind.conf" conditional='ENABLE_LOGIND' - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>logind.conf</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>logind.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>logind.conf</refname> - <refname>logind.conf.d</refname> - <refpurpose>Login manager configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/logind.conf</filename></para> - <para><filename>/etc/systemd/logind.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/logind.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/logind.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These files configure various parameters of the systemd login manager, <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - <xi:include href="standard-conf.xml" xpointer="conf" /> - - <refsect1> - <title>Options</title> - - <para>All options are configured in the - <literal>[Login]</literal> section:</para> - - <variablelist> - - <varlistentry> - <term><varname>NAutoVTs=</varname></term> - - <listitem><para>Takes a positive - integer. Configures how many virtual - terminals (VTs) to allocate by default - that, when switched to and are - previously unused, - <literal>autovt</literal> services are - automatically spawned on. These - services are instantiated from the - template unit - <filename>autovt@.service</filename> - for the respective VT TTY name, - for example, <filename>autovt@tty4.service</filename>. By - default, - <filename>autovt@.service</filename> - is linked to - <filename>getty@.service</filename>. - In other words, login prompts are started - dynamically as the user switches to - unused virtual terminals. Hence, this - parameter controls how many login - <literal>gettys</literal> are - available on the VTs. If a VT is - already used by some other subsystem - (for example, a graphical login), this - kind of activation will not be - attempted. Note that the VT configured - in <varname>ReserveVT=</varname> is - always subject to this kind of - activation, even if it is not one of - the VTs configured with the - <varname>NAutoVTs=</varname> - directive. Defaults to 6. When set to - 0, automatic spawning of - <literal>autovt</literal> services is - disabled.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ReserveVT=</varname></term> - - <listitem><para>Takes a positive - integer. Identifies one - virtual terminal that shall - unconditionally be reserved for - <filename>autovt@.service</filename> - activation (see above). The VT - selected with this option will be - marked busy unconditionally, so that no - other subsystem will allocate it. This - functionality is useful to ensure that, - regardless of how many VTs are allocated - by other subsystems, one login - <literal>getty</literal> is always - available. Defaults to 6 (in other - words, there will always be a - <literal>getty</literal> available on - Alt-F6.). When set to 0, VT - reservation is - disabled.</para></listitem> - </varlistentry> - - <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> - will break tools like - <citerefentry><refentrytitle>screen</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> - </varlistentry> - - <varlistentry> - <term><varname>IdleAction=</varname></term> - - <listitem><para>Configures the action - to take when the system is idle. Takes - one of <literal>ignore</literal>, - <literal>poweroff</literal>, - <literal>reboot</literal>, - <literal>halt</literal>, - <literal>kexec</literal>, - <literal>suspend</literal>, - <literal>hibernate</literal>, - <literal>hybrid-sleep</literal>, and - <literal>lock</literal>. Defaults to - <literal>ignore</literal>.</para> - - <para>Note that this requires that - user sessions correctly report the - idle status to the system. The system - will execute the action after all - sessions report that they are idle, - no idle inhibitor lock is active, - and subsequently, the time configured - with <varname>IdleActionSec=</varname> - (see below) has expired.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>IdleActionSec=</varname></term> - - <listitem><para>Configures the delay - after which the action configured in - <varname>IdleAction=</varname> (see - above) is taken after the system is - idle.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>InhibitDelayMaxSec=</varname></term> - - <listitem><para>Specifies the maximum - time a system shutdown or sleep - request is delayed due to an inhibitor - lock of type <literal>delay</literal> - being active before the inhibitor is - ignored and the operation executes - anyway. Defaults to - 5.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>HandlePowerKey=</varname></term> - <term><varname>HandleSuspendKey=</varname></term> - <term><varname>HandleHibernateKey=</varname></term> - <term><varname>HandleLidSwitch=</varname></term> - <term><varname>HandleLidSwitchDocked=</varname></term> - - <listitem><para>Controls whether - logind shall handle the system power - and sleep keys and the lid switch to - trigger actions such as system - power-off or suspend. Can be one of - <literal>ignore</literal>, - <literal>poweroff</literal>, - <literal>reboot</literal>, - <literal>halt</literal>, - <literal>kexec</literal>, - <literal>suspend</literal>, - <literal>hibernate</literal>, - <literal>hybrid-sleep</literal>, and - <literal>lock</literal>. If - <literal>ignore</literal>, logind will - never handle these keys. If - <literal>lock</literal>, all running - sessions will be screen-locked; - otherwise, the specified action will - be taken in the respective event. Only - input devices with the - <literal>power-switch</literal> udev - tag will be watched for key/lid switch - events. <varname>HandlePowerKey=</varname> - defaults to - <literal>poweroff</literal>. - <varname>HandleSuspendKey=</varname> - and - <varname>HandleLidSwitch=</varname> - default to <literal>suspend</literal>. - <varname>HandleLidSwitchDocked=</varname> - defaults to <literal>ignore</literal>. - <varname>HandleHibernateKey=</varname> - defaults to - <literal>hibernate</literal>. If the - system is inserted in a docking station, - or if more than one display is connected, - the action specified by - <varname>HandleLidSwitchDocked=</varname> - occurs; otherwise the - <varname>HandleLidSwitch=</varname> - action occurs.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PowerKeyIgnoreInhibited=</varname></term> - <term><varname>SuspendKeyIgnoreInhibited=</varname></term> - <term><varname>HibernateKeyIgnoreInhibited=</varname></term> - <term><varname>LidSwitchIgnoreInhibited=</varname></term> - - <listitem><para>Controls whether - actions triggered by the power and - sleep keys and the lid switch are - subject to inhibitor locks. These - settings take boolean arguments. If - <literal>no</literal>, the inhibitor - locks taken by applications in order - to block the requested operation are - respected. If <literal>yes</literal>, - the requested operation is executed in - any - case. <varname>PowerKeyIgnoreInhibited=</varname>, - <varname>SuspendKeyIgnoreInhibited=</varname> - and - <varname>HibernateKeyIgnoreInhibited=</varname> - default to <literal>no</literal>. - <varname>LidSwitchIgnoreInhibited=</varname> - defaults to - <literal>yes</literal>. This means - that the lid switch does not respect - suspend blockers by default, but the - power and sleep keys do. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RuntimeDirectorySize=</varname></term> - - <listitem><para>Sets the size limit on - the - <varname>$XDG_RUNTIME_DIR</varname> - runtime directory for each user who - logs in. Takes a size in bytes, - optionally suffixed with the usual K, G, - M, and T suffixes, to the base 1024 - (IEC). Alternatively, a numerical - percentage suffixed by <literal>%</literal> - may be specified, which sets the size - limit relative to the amount of - physical RAM. Defaults to 10%. Note - that this size is a safety limit - only. As each runtime directory is a - tmpfs file system, it will only consume - as much memory as is needed. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RemoveIPC=</varname></term> - - <listitem><para>Controls whether - System V and POSIX IPC objects - belonging to the user shall be removed - when the user fully logs out. Takes a - boolean argument. If enabled, the user - may not consume IPC resources after - the last of the user's sessions - terminated. This covers System V - semaphores, shared memory and message - queues, as well as POSIX shared memory - and message queues. Note that IPC - objects of the root user are excluded - from the effect of this - setting. Defaults to - <literal>yes</literal>.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>logind.conf</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>logind.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>logind.conf</refname> + <refname>logind.conf.d</refname> + <refpurpose>Login manager configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/logind.conf</filename></para> + <para><filename>/etc/systemd/logind.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/logind.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/logind.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These files configure various parameters of the systemd login manager, <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + <xi:include href="standard-conf.xml" xpointer="conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Login]</literal> section:</para> + + <variablelist> + + <varlistentry> + <term><varname>NAutoVTs=</varname></term> + + <listitem><para>Takes a positive integer. Configures how many + virtual terminals (VTs) to allocate by default that, when + switched to and are previously unused, + <literal>autovt</literal> services are automatically spawned + on. These services are instantiated from the template unit + <filename>autovt@.service</filename> for the respective VT TTY + name, for example, <filename>autovt@tty4.service</filename>. + By default, <filename>autovt@.service</filename> is linked to + <filename>getty@.service</filename>. In other words, login + prompts are started dynamically as the user switches to unused + virtual terminals. Hence, this parameter controls how many + login <literal>gettys</literal> are available on the VTs. If a + VT is already used by some other subsystem (for example, a + graphical login), this kind of activation will not be + attempted. Note that the VT configured in + <varname>ReserveVT=</varname> is always subject to this kind + of activation, even if it is not one of the VTs configured + with the <varname>NAutoVTs=</varname> directive. Defaults to + 6. When set to 0, automatic spawning of + <literal>autovt</literal> services is + disabled.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ReserveVT=</varname></term> + + <listitem><para>Takes a positive integer. Identifies one + virtual terminal that shall unconditionally be reserved for + <filename>autovt@.service</filename> activation (see above). + The VT selected with this option will be marked busy + unconditionally, so that no other subsystem will allocate it. + This functionality is useful to ensure that, regardless of how + many VTs are allocated by other subsystems, one login + <literal>getty</literal> is always available. Defaults to 6 + (in other words, there will always be a + <literal>getty</literal> available on Alt-F6.). When set to 0, + VT reservation is disabled.</para></listitem> + </varlistentry> + + <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> + will break tools like + <citerefentry><refentrytitle>screen</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> + </varlistentry> + + <varlistentry> + <term><varname>IdleAction=</varname></term> + + <listitem><para>Configures the action to take when the system + is idle. Takes one of + <literal>ignore</literal>, + <literal>poweroff</literal>, + <literal>reboot</literal>, + <literal>halt</literal>, + <literal>kexec</literal>, + <literal>suspend</literal>, + <literal>hibernate</literal>, + <literal>hybrid-sleep</literal>, and + <literal>lock</literal>. + Defaults to <literal>ignore</literal>.</para> + + <para>Note that this requires that user sessions correctly + report the idle status to the system. The system will execute + the action after all sessions report that they are idle, no + idle inhibitor lock is active, and subsequently, the time + configured with <varname>IdleActionSec=</varname> (see below) + has expired.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IdleActionSec=</varname></term> + + <listitem><para>Configures the delay after which the action + configured in <varname>IdleAction=</varname> (see above) is + taken after the system is idle.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>InhibitDelayMaxSec=</varname></term> + + <listitem><para>Specifies the maximum time a system shutdown + or sleep request is delayed due to an inhibitor lock of type + <literal>delay</literal> being active before the inhibitor is + ignored and the operation executes anyway. Defaults to + 5.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>HandlePowerKey=</varname></term> + <term><varname>HandleSuspendKey=</varname></term> + <term><varname>HandleHibernateKey=</varname></term> + <term><varname>HandleLidSwitch=</varname></term> + <term><varname>HandleLidSwitchDocked=</varname></term> + + <listitem><para>Controls whether logind shall handle the + system power and sleep keys and the lid switch to trigger + actions such as system power-off or suspend. Can be one of + <literal>ignore</literal>, + <literal>poweroff</literal>, + <literal>reboot</literal>, + <literal>halt</literal>, + <literal>kexec</literal>, + <literal>suspend</literal>, + <literal>hibernate</literal>, + <literal>hybrid-sleep</literal>, and + <literal>lock</literal>. + If <literal>ignore</literal>, logind will never handle these + keys. If <literal>lock</literal>, all running sessions will be + screen-locked; otherwise, the specified action will be taken + in the respective event. Only input devices with the + <literal>power-switch</literal> udev tag will be watched for + key/lid switch events. <varname>HandlePowerKey=</varname> + defaults to <literal>poweroff</literal>. + <varname>HandleSuspendKey=</varname> and + <varname>HandleLidSwitch=</varname> default to + <literal>suspend</literal>. + <varname>HandleLidSwitchDocked=</varname> defaults to + <literal>ignore</literal>. + <varname>HandleHibernateKey=</varname> defaults to + <literal>hibernate</literal>. If the system is inserted in a + docking station, or if more than one display is connected, the + action specified by <varname>HandleLidSwitchDocked=</varname> + occurs; otherwise the <varname>HandleLidSwitch=</varname> + action occurs.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PowerKeyIgnoreInhibited=</varname></term> + <term><varname>SuspendKeyIgnoreInhibited=</varname></term> + <term><varname>HibernateKeyIgnoreInhibited=</varname></term> + <term><varname>LidSwitchIgnoreInhibited=</varname></term> + + <listitem><para>Controls whether actions triggered by the + power and sleep keys and the lid switch are subject to + inhibitor locks. These settings take boolean arguments. If + <literal>no</literal>, the inhibitor locks taken by + applications in order to block the requested operation are + respected. If <literal>yes</literal>, the requested operation + is executed in any case. + <varname>PowerKeyIgnoreInhibited=</varname>, + <varname>SuspendKeyIgnoreInhibited=</varname> and + <varname>HibernateKeyIgnoreInhibited=</varname> default to + <literal>no</literal>. + <varname>LidSwitchIgnoreInhibited=</varname> defaults to + <literal>yes</literal>. This means that the lid switch does + not respect suspend blockers by default, but the power and + sleep keys do. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RuntimeDirectorySize=</varname></term> + + <listitem><para>Sets the size limit on the + <varname>$XDG_RUNTIME_DIR</varname> runtime directory for each + user who logs in. Takes a size in bytes, optionally suffixed + with the usual K, G, M, and T suffixes, to the base 1024 + (IEC). Alternatively, a numerical percentage suffixed by + <literal>%</literal> may be specified, which sets the size + limit relative to the amount of physical RAM. Defaults to 10%. + Note that this size is a safety limit only. As each runtime + directory is a tmpfs file system, it will only consume as much + memory as is needed. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RemoveIPC=</varname></term> + + <listitem><para>Controls whether System V and POSIX IPC + objects belonging to the user shall be removed when the user + fully logs out. Takes a boolean argument. If enabled, the user + may not consume IPC resources after the last of the user's + sessions terminated. This covers System V semaphores, shared + memory and message queues, as well as POSIX shared memory and + message queues. Note that IPC objects of the root user are + excluded from the effect of this setting. Defaults to + <literal>yes</literal>.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/machine-id.xml b/man/machine-id.xml index 725370d32d..27a8461756 100644 --- a/man/machine-id.xml +++ b/man/machine-id.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,127 +23,119 @@ --> <refentry id="machine-id"> - <refentryinfo> - <title>machine-id</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>machine-id</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>machine-id</refname> - <refpurpose>Local machine ID configuration file</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/machine-id</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <filename>/etc/machine-id</filename> file - contains the unique machine ID of the local system - that is set during installation. The machine ID is a - single newline-terminated, hexadecimal, 32-character, - lowercase machine ID string. When decoded from - hexadecimal, this corresponds with a 16-byte/128-bit - string.</para> - - <para>The machine ID is usually generated from a - random source during system installation and stays - constant for all subsequent boots. Optionally, for - stateless systems, it is generated during runtime at - boot if it is found to be empty.</para> - - <para>The machine ID does not change based on user - configuration or when hardware is replaced.</para> - - <para>This machine ID adheres to the same format and - logic as the D-Bus machine ID.</para> - - <para>Programs may use this ID to identify the host - with a globally unique ID in the network, which does - not change even if the local network configuration - changes. Due to this and its greater length, it is - a more useful replacement for the - <citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call that POSIX specifies.</para> - - <para>The - <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool may be used by installer tools to initialize the - machine ID at install time. Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize it on mounted (but not booted) system - images.</para> - </refsect1> - - <refsect1> - <title>Relation to OSF UUIDs</title> - - <para>Note that the machine ID historically is not an - OSF UUID as defined by <ulink - url="https://tools.ietf.org/html/rfc4122">RFC - 4122</ulink>, nor a Microsoft GUID; however, starting with - systemd v30, newly generated machine IDs do - qualify as v4 UUIDs.</para> - - <para>In order to maintain compatibility with existing - installations, an application requiring a UUID should - decode the machine ID, and then apply the following - operations to turn it into a valid OSF v4 UUID. With - <literal>id</literal> being an unsigned character - array:</para> - - <programlisting>/* Set UUID version to 4 --- truly random generation */ + <refentryinfo> + <title>machine-id</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>machine-id</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>machine-id</refname> + <refpurpose>Local machine ID configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/machine-id</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/machine-id</filename> file contains the + unique machine ID of the local system that is set during + installation. The machine ID is a single newline-terminated, + hexadecimal, 32-character, lowercase machine ID string. When + decoded from hexadecimal, this corresponds with a 16-byte/128-bit + string.</para> + + <para>The machine ID is usually generated from a random source + during system installation and stays constant for all subsequent + boots. Optionally, for stateless systems, it is generated during + runtime at boot if it is found to be empty.</para> + + <para>The machine ID does not change based on user configuration + or when hardware is replaced.</para> + + <para>This machine ID adheres to the same format and logic as the + D-Bus machine ID.</para> + + <para>Programs may use this ID to identify the host with a + globally unique ID in the network, which does not change even if + the local network configuration changes. Due to this and its + greater length, it is a more useful replacement for the + <citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call that POSIX specifies.</para> + + <para>The + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool may be used by installer tools to initialize the machine ID + at install time. Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize it on mounted (but not booted) system images.</para> + </refsect1> + + <refsect1> + <title>Relation to OSF UUIDs</title> + + <para>Note that the machine ID historically is not an OSF UUID as + defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC + 4122</ulink>, nor a Microsoft GUID; however, starting with systemd + v30, newly generated machine IDs do qualify as v4 UUIDs.</para> + + <para>In order to maintain compatibility with existing + installations, an application requiring a UUID should decode the + machine ID, and then apply the following operations to turn it + into a valid OSF v4 UUID. With <literal>id</literal> being an + unsigned character array:</para> + + <programlisting>/* Set UUID version to 4 --- truly random generation */ id[6] = (id[6] & 0x0F) | 0x40; /* Set the UUID variant to DCE */ id[8] = (id[8] & 0x3F) | 0x80;</programlisting> - <para>(This code is inspired by - <literal>generate_random_uuid()</literal> of - <filename>drivers/char/random.c</filename> from the - Linux kernel sources.)</para> - - </refsect1> - - <refsect1> - <title>History</title> - - <para>The simple configuration file format of - <filename>/etc/machine-id</filename> originates in the - <filename>/var/lib/dbus/machine-id</filename> file - introduced by D-Bus. In fact, this latter file might be a - symlink to - <varname>/etc/machine-id</varname>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <para>(This code is inspired by + <literal>generate_random_uuid()</literal> of + <filename>drivers/char/random.c</filename> from the Linux kernel + sources.)</para> + + </refsect1> + + <refsect1> + <title>History</title> + + <para>The simple configuration file format of + <filename>/etc/machine-id</filename> originates in the + <filename>/var/lib/dbus/machine-id</filename> file introduced by + D-Bus. In fact, this latter file might be a symlink to + <varname>/etc/machine-id</varname>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/machine-info.xml b/man/machine-info.xml index 4dd3741c8a..518face143 100644 --- a/man/machine-info.xml +++ b/man/machine-info.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,188 +23,164 @@ --> <refentry id="machine-info"> - <refentryinfo> - <title>machine-info</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>machine-info</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>machine-info</refname> - <refpurpose>Local machine information file</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/machine-info</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <filename>/etc/machine-info</filename> file - contains machine metadata.</para> - - <para>The basic file format of - <filename>machine-info</filename> is a - newline-separated list of environment-like - shell-compatible variable assignments. It is possible - to source the configuration from shell scripts, - however, beyond mere variable assignments no shell - features are supported, allowing applications to read - the file without implementing a shell compatible - execution engine.</para> - - <para><filename>/etc/machine-info</filename> contains - metadata about the machine that is set by the user or - administrator.</para> - - <para>Depending on the operating system other - configuration files might be checked for machine - information as well, however only as fallback.</para> - - <para>You may use - <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to change the settings of this file from the command - line.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following machine metadata parameters may - be set using - <filename>/etc/machine-info</filename>:</para> - - <variablelist> - - <varlistentry> - <term><varname>PRETTY_HOSTNAME=</varname></term> - - <listitem><para>A pretty - human-readable UTF-8 machine identifier - string. This should contain a name - like <literal>Lennart's - Laptop</literal> which is useful to - present to the user and does not - suffer by the syntax limitations of - internet domain names. If possible, the - internet hostname as configured in - <filename>/etc/hostname</filename> - should be kept similar to this - one. Example: if this value is - <literal>Lennart's Computer</literal> - an Internet hostname of - <literal>lennarts-computer</literal> - might be a good choice. If this - parameter is not set, an application - should fall back to the Internet host - name for presentation - purposes.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ICON_NAME=</varname></term> - - <listitem><para>An icon identifying - this machine according to the <ulink - url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG - Icon Naming Specification</ulink>. If - this parameter is not set, an - application should fall back to - <literal>computer</literal> or a - similar icon name.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>CHASSIS=</varname></term> - - <listitem><para>The chassis - type. Currently, the following chassis - types are defined: - <literal>desktop</literal>, - <literal>laptop</literal>, - <literal>server</literal>, - <literal>tablet</literal>, - <literal>handset</literal>, - <literal>watch</literal>, and - <literal>embedded</literal> as well as - the special chassis types - <literal>vm</literal> and - <literal>container</literal> for - virtualized systems that lack an - immediate physical chassis. Note that - many systems allow detection of the - chassis type automatically (based on - firmware information or - suchlike). This setting (if set) shall - take precedence over automatically - detected information and is useful to - override misdetected configuration or - to manually configure the chassis type - where automatic detection is not - available.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DEPLOYMENT=</varname></term> - - <listitem><para>Describes the system - deployment environment. One of the - following is suggested: - <literal>development</literal>, - <literal>integration</literal>, - <literal>staging</literal>, - <literal>production</literal>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>LOCATION=</varname></term> - - <listitem><para>Describes the system - location if applicable and - known. Takes a human-friendly, - free-form string. This may be as - generic as <literal>Berlin, - Germany</literal> or as specific as - <literal>Left Rack, 2nd - Shelf</literal>.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Example</title> - - <programlisting>PRETTY_HOSTNAME="Lennart's Tablet" + <refentryinfo> + <title>machine-info</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>machine-info</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>machine-info</refname> + <refpurpose>Local machine information file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/machine-info</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/machine-info</filename> file contains + machine metadata.</para> + + <para>The basic file format of <filename>machine-info</filename> + is a newline-separated list of environment-like shell-compatible + variable assignments. It is possible to source the configuration + from shell scripts, however, beyond mere variable assignments no + shell features are supported, allowing applications to read the + file without implementing a shell compatible execution + engine.</para> + + <para><filename>/etc/machine-info</filename> contains metadata + about the machine that is set by the user or administrator.</para> + + <para>Depending on the operating system other configuration files + might be checked for machine information as well, however only as + fallback.</para> + + <para>You may use + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to change the settings of this file from the command line.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following machine metadata parameters may be set using + <filename>/etc/machine-info</filename>:</para> + + <variablelist> + + <varlistentry> + <term><varname>PRETTY_HOSTNAME=</varname></term> + + <listitem><para>A pretty human-readable UTF-8 machine + identifier string. This should contain a name like + <literal>Lennart's Laptop</literal> which is useful to present + to the user and does not suffer by the syntax limitations of + internet domain names. If possible, the internet hostname as + configured in <filename>/etc/hostname</filename> should be + kept similar to this one. Example: if this value is + <literal>Lennart's Computer</literal> an Internet hostname of + <literal>lennarts-computer</literal> might be a good choice. + If this parameter is not set, an application should fall back + to the Internet host name for presentation + purposes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ICON_NAME=</varname></term> + + <listitem><para>An icon identifying this machine according to + the <ulink + url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG + Icon Naming Specification</ulink>. If this parameter is not + set, an application should fall back to + <literal>computer</literal> or a similar icon + name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CHASSIS=</varname></term> + + <listitem><para>The chassis type. Currently, the following + chassis types are defined: + <literal>desktop</literal>, + <literal>laptop</literal>, + <literal>server</literal>, + <literal>tablet</literal>, + <literal>handset</literal>, + <literal>watch</literal>, and + <literal>embedded</literal> + as well as the special chassis types + <literal>vm</literal> and + <literal>container</literal> for + virtualized systems that lack an immediate physical chassis. + Note that many systems allow detection of the chassis type + automatically (based on firmware information or suchlike). + This setting (if set) shall take precedence over automatically + detected information and is useful to override misdetected + configuration or to manually configure the chassis type where + automatic detection is not available.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DEPLOYMENT=</varname></term> + + <listitem><para>Describes the system deployment environment. + One of the following is suggested: + <literal>development</literal>, + <literal>integration</literal>, + <literal>staging</literal>, + <literal>production</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LOCATION=</varname></term> + + <listitem><para>Describes the system location if applicable + and known. Takes a human-friendly, free-form string. This may + be as generic as <literal>Berlin, Germany</literal> or as + specific as <literal>Left Rack, 2nd Shelf</literal>. + </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting>PRETTY_HOSTNAME="Lennart's Tablet" ICON_NAME=computer-tablet CHASSIS=tablet DEPLOYMENT=production</programlisting> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/machinectl.xml b/man/machinectl.xml index 61ea1c45d8..9b07af4226 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,943 +22,741 @@ --> <refentry id="machinectl" conditional='ENABLE_MACHINED' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>machinectl</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>machinectl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>machinectl</refname> - <refpurpose>Control the systemd machine manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>machinectl</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="req">COMMAND</arg> - <arg choice="opt" rep="repeat">NAME</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>machinectl</command> may be used to - introspect and control the state of the - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - virtual machine and container registration manager <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>-p</option></term> - <term><option>--property=</option></term> - - <listitem><para>When showing machine - or image properties, limit the output - to certain properties as specified by - the argument. If not specified, all - set properties are shown. The argument - should be a property name, such as - <literal>Name</literal>. If specified - more than once, all properties with - the specified names are - shown.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-a</option></term> - <term><option>--all</option></term> - - <listitem><para>When showing machine - or image properties, show all - properties regardless of whether they - are set or not.</para> - - <para>When listing VM or container - images, do not suppress images - beginning in a dot character - (<literal>.</literal>).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</option></term> - <term><option>--full</option></term> - - <listitem><para>Do not ellipsize - process tree entries.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-ask-password</option></term> - - <listitem><para>Do not query the user - for authentication for privileged - operations.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--kill-who=</option></term> - - <listitem><para>When used with - <command>kill</command>, - choose which processes to kill. Must - be one of <option>leader</option>, or - <option>all</option> to select whether - to kill only the leader process of the - machine or all processes of the - machine. If omitted, defaults to - <option>all</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-s</option></term> - <term><option>--signal=</option></term> - - <listitem><para>When used with - <command>kill</command>, choose - which signal to send to selected - processes. Must be one of the - well-known signal specifiers, such as - <constant>SIGTERM</constant>, - <constant>SIGINT</constant> or - <constant>SIGSTOP</constant>. If - omitted, defaults to - <constant>SIGTERM</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--mkdir</option></term> - - <listitem><para>When used with - <command>bind</command> creates the - destination directory before applying - the bind mount.</para></listitem> - </varlistentry> - - - <varlistentry> - <term><option>--read-only</option></term> - - <listitem><para>When used with - <command>bind</command> applies a - read-only bind - mount.</para></listitem> - </varlistentry> - - - <varlistentry> - <term><option>-n</option></term> - <term><option>--lines=</option></term> - - <listitem><para>When used with - <command>status</command>, controls - the number of journal lines to show, - counting from the most recent - ones. Takes a positive integer - argument. Defaults to 10.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-o</option></term> - <term><option>--output=</option></term> - - <listitem><para>When used with - <command>status</command>, controls - the formatting of the journal entries - that are shown. For the available - choices, see - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - Defaults to - <literal>short</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--verify=</option></term> - - <listitem><para>When downloading a - container or VM image, specify whether - the image shall be verified before it - is made available. Takes one of - <literal>no</literal>, - <literal>checksum</literal> and - <literal>signature</literal>. If - <literal>no</literal> no verification - is done. If - <literal>checksum</literal> is - specified the download is checked for - integrity after transfer is complete, - but no signatures are verified. If - <literal>signature</literal> is - specified, the checksum is verified - and the images's signature is checked - against a local keyring of trustable - vendors. It is strongly recommended to - set this option to - <literal>signature</literal> if the - server and protocol support this. - Defaults to - <literal>signature</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--force</option></term> - - <listitem><para>When downloading a - container or VM image, and a local - copy by the specified local machine - name already exists, delete it first - and replace it by the newly downloaded - image.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--dkr-index-url</option></term> - - <listitem><para>Specifies the index - server to use for downloading - <literal>dkr</literal> images with the - <command>pull-dkr</command>. Takes a - <literal>http://</literal>, - <literal>https://</literal> URL.</para></listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="no-pager" /> - <xi:include href="standard-options.xml" xpointer="no-legend" /> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Commands</title> - - <para>The following commands are understood:</para> - - <refsect2><title>Machine Commands</title><variablelist> - - <varlistentry> - <term><command>list</command></term> - - <listitem><para>List currently running - (online) virtual machines and - containers. To enumerate container - images that can be started, - use <command>list-images</command> - (see below).</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>status</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Show terse runtime - status information about one or more - virtual machines and containers, - followed by the most recent log data - from the journal. This function is - intended to generate human-readable - output. If you are looking for - computer-parsable output, use - <command>show</command> instead. Note - that the log data shown is reported by - the virtual machine or container - manager, and frequently contains - console output of the machine, but not - necessarily journal contents of the - machine itself.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>show</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Show properties of one - or more registered virtual machines or - containers or the manager itself. If - no argument is specified, properties - of the manager will be shown. If an - NAME is specified, properties of this - virtual machine or container are - shown. By default, empty properties - are suppressed. Use - <option>--all</option> to show those - too. To select specific properties to - show, use - <option>--property=</option>. This - command is intended to be used - whenever computer-parsable output is - required. Use - <command>status</command> if you are - looking for formatted human-readable - output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>start</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Start a container as a - system service, using - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - This starts - <filename>systemd-nspawn@.service</filename>, - instantiated for the specified machine - name, similar to the effect of - <command>systemctl start</command> on - the service - name. <command>systemd-nspawn</command> - looks for a container image by the - specified name in - <filename>/var/lib/machines/</filename> - (and other search paths, see below) and runs - it. Use <command>list-images</command> - (see below), for listing available - container images to start.</para> - - <para>Note that - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - also interfaces with a variety of - other container and VM managers, - <command>systemd-nspawn</command> is - just one implementation of it. Most of - the commands available in - <command>machinectl</command> may be - used on containers or VMs controlled - by other managers, not just - <command>systemd-nspawn</command>. Starting - VMs and container images on those - managers requires manager-specific - tools.</para> - - <para>To interactively start a - container on the command line with - full access to the container's - console, please invoke - <command>systemd-nspawn</command> - directly. To stop a running container - use <command>machinectl - poweroff</command>, see - below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>login</command> <replaceable>NAME</replaceable></term> - - <listitem><para>Open an interactive terminal login - session to a container. This will - create a TTY connection to a specific - container and asks for the execution of a - getty on it. Note that this is only - supported for containers running - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - as init system.</para> - - <para>This command will open a full - login prompt on the container, which - then asks for username and - password. Use - <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> - with the <option>--machine=</option> - switch to invoke a single command, - either interactively or in the - background within a local - container.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>enable</command> <replaceable>NAME</replaceable>...</term> - <term><command>disable</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Enable or disable a - container as a system service to start - at system boot, using - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - This enables or disables - <filename>systemd-nspawn@.service</filename>, - instantiated for the specified machine - name, similar to the effect of - <command>systemctl enable</command> or - <command>systemctl disable</command> - on the service name.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Power off one or more - containers. This will trigger a reboot - by sending SIGRTMIN+4 to the - container's init process, which causes - systemd-compatible init systems to - shut down cleanly. This operation does - not work on containers that do not run - a - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible - init system, such as sysvinit. Use - <command>terminate</command> (see - below) to immediately terminate a - container or VM, without cleanly - shutting it down.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>reboot</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Reboot one or more - containers. This will trigger a reboot - by sending SIGINT to the container's - init process, which is roughly - equivalent to pressing Ctrl+Alt+Del on - a non-containerized system, and is - compatible with containers running any - system manager.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>terminate</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Immediately terminates - a virtual machine or container, - without cleanly shutting it down. This - kills all processes of the virtual - machine or container and deallocates - all resources attached to that - instance. Use - <command>poweroff</command> to issue a - clean shutdown request.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>kill</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Send a signal to one - or more processes of the virtual - machine or container. This means - processes as seen by the host, not the - processes inside the virtual machine - or container. - Use <option>--kill-who=</option> to - select which process to kill. Use - <option>--signal=</option> to select - the signal to send.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term> - - <listitem><para>Bind mounts a - directory from the host into the - specified container. The first - directory argument is the source - directory on the host, the second - directory argument the source - directory on the host. When the latter - is omitted the destination path in the - container is the same as the source - path on the host. When combined with - the <option>--read-only</option> - switch a ready-only bind mount is - created. When combined with the - <option>--mkdir</option> switch the - destination path is first created - before the mount is applied. Note that - this option is currently only - supported for - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - containers.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term> - - <listitem><para>Copies files or - directories from the host system into - a running container. Takes a container - name, followed by the source path on - the host and the destination path in - the container. If the destination path - is omitted the same as the source path - is used.</para></listitem> - </varlistentry> - - - <varlistentry> - <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term> - - <listitem><para>Copies files or - directories from a container into the - host system. Takes a container name, - followed by the source path in the - container the destination path on the - host. If the destination path is - omitted the same as the source path is - used.</para></listitem> - </varlistentry> - </variablelist></refsect2> - - <refsect2><title>Image Commands</title><variablelist> - - <varlistentry> - <term><command>list-images</command></term> - - <listitem><para>Show a list of locally - installed container and VM - images. This enumerates all raw disk - images and container directories and - subvolumes in - <filename>/var/lib/machines/</filename> (and other search paths, see below). Use - <command>start</command> (see above) - to run a container off one of the - listed images. Note that by default - containers whose name begins with a - dot (<literal>.</literal>) are not - shown. To show these too, specify - <option>--all</option>. Note that a - special image <literal>.host</literal> - always implicitly exists and refers to - the image the host itself is booted - from.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>image-status</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Show terse status - information about one or more - container or VM images. This function - is intended to generate human-readable - output. Use - <command>show-image</command> (see - below) to generate computer-parsable - output instead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>show-image</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Show properties of one - or more registered virtual machine or - container images, or the manager - itself. If no argument is specified, - properties of the manager will be - shown. If an NAME is specified, - properties of this virtual machine or - container image are shown. By default, - empty properties are suppressed. Use - <option>--all</option> to show those - too. To select specific properties to - show, use - <option>--property=</option>. This - command is intended to be used - whenever computer-parsable output is - required. Use - <command>image-status</command> if you - are looking for formatted - human-readable - output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term> - - <listitem><para>Clones a container or - disk 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> - </varlistentry> - - <varlistentry> - <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term> - - <listitem><para>Renames a container or - disk image. The arguments specify the - name of the image to rename and the - new name of the - image.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term> - - <listitem><para>Marks or (unmarks) a - container or disk image - read-only. Takes a VM or container - image name, followed by a boolean as - arguments. If the boolean is omitted, - positive is implied, i.e. the image is - marked read-only.</para></listitem> - </varlistentry> - - - <varlistentry> - <term><command>remove</command> <replaceable>NAME</replaceable>...</term> - - <listitem><para>Removes one or more - container or disk images. The special - image <literal>.host</literal>, which - refers to the host's own directory - tree may not be - removed.</para></listitem> - </varlistentry> - - </variablelist></refsect2> - - <refsect2><title>Image Transfer Commands</title><variablelist> - - <varlistentry> - <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term> - - <listitem><para>Downloads a - <filename>.tar</filename> container - image from the specified URL, and - makes it available under the specified - local machine name. The URL must be of - type <literal>http://</literal> or - <literal>https://</literal>, and must - refer to a <filename>.tar</filename>, - <filename>.tar.gz</filename>, - <filename>.tar.xz</filename> or - <filename>.tar.bz2</filename> archive - file. If the local machine name is - omitted the name it is automatically - derived from the last component of the - URL, with its suffix removed.</para> - - <para>The image is verified before it - is made available, unless - <option>--verify=no</option> is - specified. Verification is done via - SHA256SUMS and SHA256SUMS.gpg files, - that need to be made available on the - same web server, under the same URL as - the <filename>.tar</filename> file, - but with the last component (the - filename) of the URL replaced. With - <option>--verify=checksum</option> - only the SHA256 checksum for the file - is verified, based on the - <filename>SHA256SUMS</filename> - file. With - <option>--verify=signature</option> - the SHA256SUMS file is first verified - with detached GPG signature file - <filename>SHA256SUMS.gpg</filename>. The - public key for this verification step - needs to be available in - <filename>/usr/lib/systemd/import-pubring.gpg</filename> - or - <filename>/etc/systemd/import-pubring.gpg</filename>.</para> - - <para>The container image will be - downloaded and stored in a read-only - subvolume in - <filename>/var/lib/machines/</filename>, - that is named after the specified URL - and its HTTP etag. A writable snapshot - is then taken from this subvolume, and - named after the specified local - name. This behaviour ensures that - creating multiple container instances - of the same URL is efficient, as - multiple downloads are not - necessary. In order to create only the - read-only image, and avoid creating - its writable snapshot, specify - <literal>-</literal> as local machine - name.</para> - - <para>Note that the read-only - subvolume is prefixed with - <filename>.tar-</filename>, and - is thus now shown by - <command>list-images</command>, unless - <option>--all</option> is passed.</para> - - <para>Note that pressing C-c during - execution of this command will not - abort the download. Use - <command>cancel-transfer</command>, - described below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term> - - <listitem><para>Downloads a - <filename>.raw</filename> container or - VM disk image from the specified URL, - and makes it available under the - specified local machine name. The URL - must be of type - <literal>http://</literal> or - <literal>https://</literal>. The - container image must either be a - <filename>.qcow2</filename> or raw - disk image, optionally compressed as - <filename>.gz</filename>, - <filename>.xz</filename>, or - <filename>.bz2</filename>. If the - local machine name is omitted the name - it is automatically derived from the - last component of the URL, with its - suffix removed.</para> - - <para>Image verification is identical - for raw and tar images (see above).</para> - - <para>If the the downloaded image is - in <filename>.qcow2</filename> format - it es converted into a raw image file - before it is made available.</para> - - <para>Downloaded images of this type - will be placed as read-only - <filename>.raw</filename> file in - <filename>/var/lib/machines/</filename>. A - local, writable (reflinked) copy is - then made under the specified local - machine name. To omit creation of the - local, writable copy pass - <literal>-</literal> as local machine - name.</para> - - <para>Similar to the behaviour of - <command>pull-tar</command>, the - read-only image is prefixed with - <filename>.raw-</filename>, and thus - now shown by - <command>list-images</command>, unless - <option>--all</option> is - passed.</para> - - <para>Note that pressing C-c during - execution of this command will not - abort the download. Use - <command>cancel-transfer</command>, - described below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>pull-dkr</command> <replaceable>REMOTE</replaceable> [<replaceable>NAME</replaceable>]</term> - - <listitem><para>Downloads a - <literal>dkr</literal> container image - and makes it available locally. The - remote name refers to a - <literal>dkr</literal> container - name. If omitted, the local machine - name is derived from the - <literal>dkr</literal> container - name.</para> - - <para>Image verification is not - available for <literal>dkr</literal> - containers, and thus - <option>--verify=no</option> must - always be specified with this - command.</para> - - <para>This command downloads all - (missing) layers for the specified - container and places them in read-only - subvolumes in - <filename>/var/lib/machines/</filename>. A - writable snapshot of the newest layer - is then created under the specified - local machine name. To omit creation - of this writable snapshot, pass - <literal>-</literal> as local machine - name.</para> - - <para>The read-only layer subvolumes - are prefixed with - <filename>.dkr-</filename>, and thus - now shown by - <command>list-images</command>, unless - <option>--all</option> is - passed.</para> - - <para>To specify the - <literal>dkr</literal> index server to - use for looking up the specified - container, use - <option>--dkr-index-url=</option>.</para> - - <para>Note that pressing C-c during - execution of this command will not - abort the download. Use - <command>cancel-transfer</command>, - described below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>list-transfers</command></term> - - <listitem><para>Shows a list of - container or VM image downloads that - are currently in - progress.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term> - - <listitem><para>Aborts download of the - container or VM image with the - specified ID. To list ongoing - transfers and their IDs, use - <command>list-transfers</command>. - </para></listitem> - </varlistentry> - - </variablelist></refsect2> - - </refsect1> - - <refsect1> - <title>Files and Directories</title> - - <para>Machine images are preferably stored in - <filename>/var/lib/machines/</filename>, but are also - searched for in - <filename>/usr/local/lib/machines/</filename> and - <filename>/usr/lib/machines/</filename>. For - compatibility reasons the directory - <filename>/var/lib/container/</filename> is searched, - too. Note that images stored below - <filename>/usr</filename> are always considered - read-only. It is possible to symlink machines images - from other directories into - <filename>/var/lib/machines/</filename> to make them - available for control with - <command>machinectl</command>.</para> - - <para>Disk images are understood by - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and <command>machinectl</command> in three - formats:</para> - - <itemizedlist> - <listitem><para>A simple directory tree, - containing the files and directories of the - container to boot.</para></listitem> - - <listitem><para>A subvolume (on btrfs file - systems), which are similar to the simple - directories, described above. However, they - have additional benefits, such as efficient - cloning and quota reporting.</para></listitem> - - <listitem><para>"Raw" disk images, i.e. binary - images of disks with a GPT or MBR partition - table. Images of this type are regular - files with the suffix - <literal>.raw</literal>.</para></listitem> - </itemizedlist> - - <para>See - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for more information on image formats, in particular - it's <option>--directory=</option> and - <option>--image=</option> options.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - <example> - <title>Download an Ubuntu image and open a shell in it</title> - - <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>machinectl</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>machinectl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>machinectl</refname> + <refpurpose>Control the systemd machine manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>machinectl</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="req">COMMAND</arg> + <arg choice="opt" rep="repeat">NAME</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>machinectl</command> may be used to introspect and + control the state of the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + virtual machine and container registration manager + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>-p</option></term> + <term><option>--property=</option></term> + + <listitem><para>When showing machine or image properties, + limit the output to certain properties as specified by the + argument. If not specified, all set properties are shown. The + argument should be a property name, such as + <literal>Name</literal>. If specified more than once, all + properties with the specified names are + shown.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-a</option></term> + <term><option>--all</option></term> + + <listitem><para>When showing machine or image properties, show + all properties regardless of whether they are set or + not.</para> + + <para>When listing VM or container images, do not suppress + images beginning in a dot character + (<literal>.</literal>).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-l</option></term> + <term><option>--full</option></term> + + <listitem><para>Do not ellipsize process tree entries.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-ask-password</option></term> + + <listitem><para>Do not query the user for authentication for + privileged operations.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--kill-who=</option></term> + + <listitem><para>When used with <command>kill</command>, choose + which processes to kill. Must be one of + <option>leader</option>, or <option>all</option> to select + whether to kill only the leader process of the machine or all + processes of the machine. If omitted, defaults to + <option>all</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-s</option></term> + <term><option>--signal=</option></term> + + <listitem><para>When used with <command>kill</command>, choose + which signal to send to selected processes. Must be one of the + well-known signal specifiers, such as + <constant>SIGTERM</constant>, <constant>SIGINT</constant> or + <constant>SIGSTOP</constant>. If omitted, defaults to + <constant>SIGTERM</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--mkdir</option></term> + + <listitem><para>When used with <command>bind</command> creates + the destination directory before applying the bind + mount.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><option>--read-only</option></term> + + <listitem><para>When used with <command>bind</command> applies + a read-only bind mount.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><option>-n</option></term> + <term><option>--lines=</option></term> + + <listitem><para>When used with <command>status</command>, + controls the number of journal lines to show, counting from + the most recent ones. Takes a positive integer argument. + Defaults to 10.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-o</option></term> + <term><option>--output=</option></term> + + <listitem><para>When used with <command>status</command>, + controls the formatting of the journal entries that are shown. + For the available choices, see + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + Defaults to <literal>short</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--verify=</option></term> + + <listitem><para>When downloading a container or VM image, + specify whether the image shall be verified before it is made + available. Takes one of <literal>no</literal>, + <literal>checksum</literal> and <literal>signature</literal>. + If <literal>no</literal> no verification is done. If + <literal>checksum</literal> is specified the download is + checked for integrity after transfer is complete, but no + signatures are verified. If <literal>signature</literal> is + specified, the checksum is verified and the images's signature + is checked against a local keyring of trustable vendors. It is + strongly recommended to set this option to + <literal>signature</literal> if the server and protocol + support this. Defaults to + <literal>signature</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--force</option></term> + + <listitem><para>When downloading a container or VM image, and + a local copy by the specified local machine name already + exists, delete it first and replace it by the newly downloaded + image.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--dkr-index-url</option></term> + + <listitem><para>Specifies the index server to use for + downloading <literal>dkr</literal> images with the + <command>pull-dkr</command>. Takes a + <literal>http://</literal>, <literal>https://</literal> + URL.</para></listitem> + </varlistentry> + + <xi:include href="user-system-options.xml" xpointer="host" /> + <xi:include href="user-system-options.xml" xpointer="machine" /> + + <xi:include href="standard-options.xml" xpointer="no-pager" /> + <xi:include href="standard-options.xml" xpointer="no-legend" /> + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Commands</title> + + <para>The following commands are understood:</para> + + <refsect2><title>Machine Commands</title><variablelist> + + <varlistentry> + <term><command>list</command></term> + + <listitem><para>List currently running (online) virtual + machines and containers. To enumerate container images that + can be started, use <command>list-images</command> (see + below).</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>status</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Show terse runtime status information about + one or more virtual machines and containers, followed by the + most recent log data from the journal. This function is + intended to generate human-readable output. If you are looking + for computer-parsable output, use <command>show</command> + instead. Note that the log data shown is reported by the + virtual machine or container manager, and frequently contains + console output of the machine, but not necessarily journal + contents of the machine itself.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>show</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Show properties of one or more registered + virtual machines or containers or the manager itself. If no + argument is specified, properties of the manager will be + shown. If an NAME is specified, properties of this virtual + machine or container are shown. By default, empty properties + are suppressed. Use <option>--all</option> to show those too. + To select specific properties to show, use + <option>--property=</option>. This command is intended to be + used whenever computer-parsable output is required. Use + <command>status</command> if you are looking for formatted + human-readable output.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>start</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Start a container as a system service, using + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + This starts <filename>systemd-nspawn@.service</filename>, + instantiated for the specified machine name, similar to the + effect of <command>systemctl start</command> on the service + name. <command>systemd-nspawn</command> looks for a container + image by the specified name in + <filename>/var/lib/machines/</filename> (and other search + paths, see below) and runs it. Use + <command>list-images</command> (see below), for listing + available container images to start.</para> + + <para>Note that + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + also interfaces with a variety of other container and VM + managers, <command>systemd-nspawn</command> is just one + implementation of it. Most of the commands available in + <command>machinectl</command> may be used on containers or VMs + controlled by other managers, not just + <command>systemd-nspawn</command>. Starting VMs and container + images on those managers requires manager-specific + tools.</para> + + <para>To interactively start a container on the command line + with full access to the container's console, please invoke + <command>systemd-nspawn</command> directly. To stop a running + container use <command>machinectl poweroff</command>, see + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>login</command> <replaceable>NAME</replaceable></term> + + <listitem><para>Open an interactive terminal login session to + a container. This will create a TTY connection to a specific + container and asks for the execution of a getty on it. Note + that this is only supported for containers running + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + as init system.</para> + + <para>This command will open a full login prompt on the + container, which then asks for username and password. Use + <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry> + with the <option>--machine=</option> switch to invoke a single + command, either interactively or in the background within a + local container.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>enable</command> <replaceable>NAME</replaceable>...</term> + <term><command>disable</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Enable or disable a container as a system + service to start at system boot, using + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + This enables or disables + <filename>systemd-nspawn@.service</filename>, instantiated for + the specified machine name, similar to the effect of + <command>systemctl enable</command> or <command>systemctl + disable</command> on the service name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>poweroff</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Power off one or more containers. This will + trigger a reboot by sending SIGRTMIN+4 to the container's init + process, which causes systemd-compatible init systems to shut + down cleanly. This operation does not work on containers that + do not run a + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible + init system, such as sysvinit. Use + <command>terminate</command> (see below) to immediately + terminate a container or VM, without cleanly shutting it + down.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>reboot</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Reboot one or more containers. This will + trigger a reboot by sending SIGINT to the container's init + process, which is roughly equivalent to pressing Ctrl+Alt+Del + on a non-containerized system, and is compatible with + containers running any system manager.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>terminate</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Immediately terminates a virtual machine or + container, without cleanly shutting it down. This kills all + processes of the virtual machine or container and deallocates + all resources attached to that instance. Use + <command>poweroff</command> to issue a clean shutdown + request.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>kill</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Send a signal to one or more processes of the + virtual machine or container. This means processes as seen by + the host, not the processes inside the virtual machine or + container. Use <option>--kill-who=</option> to select which + process to kill. Use <option>--signal=</option> to select the + signal to send.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term> + + <listitem><para>Bind mounts a directory from the host into the + specified container. The first directory argument is the + source directory on the host, the second directory argument + the source directory on the host. When the latter is omitted + the destination path in the container is the same as the + source path on the host. When combined with the + <option>--read-only</option> switch a ready-only bind mount is + created. When combined with the <option>--mkdir</option> + switch the destination path is first created before the mount + is applied. Note that this option is currently only supported + for + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + containers.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>copy-to</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term> + + <listitem><para>Copies files or directories from the host + system into a running container. Takes a container name, + followed by the source path on the host and the destination + path in the container. If the destination path is omitted the + same as the source path is used.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term> + + <listitem><para>Copies files or directories from a container + into the host system. Takes a container name, followed by the + source path in the container the destination path on the host. + If the destination path is omitted the same as the source path + is used.</para></listitem> + </varlistentry> + </variablelist></refsect2> + + <refsect2><title>Image Commands</title><variablelist> + + <varlistentry> + <term><command>list-images</command></term> + + <listitem><para>Show a list of locally installed container and + VM images. This enumerates all raw disk images and container + directories and subvolumes in + <filename>/var/lib/machines/</filename> (and other search + paths, see below). Use <command>start</command> (see above) to + run a container off one of the listed images. Note that by + default containers whose name begins with a dot + (<literal>.</literal>) are not shown. To show these too, + specify <option>--all</option>. Note that a special image + <literal>.host</literal> always implicitly exists and refers + to the image the host itself is booted from.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>image-status</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Show terse status information about one or + more container or VM images. This function is intended to + generate human-readable output. Use + <command>show-image</command> (see below) to generate + computer-parsable output instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>show-image</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Show properties of one or more registered + virtual machine or container images, or the manager itself. If + no argument is specified, properties of the manager will be + shown. If an NAME is specified, properties of this virtual + machine or container image are shown. By default, empty + properties are suppressed. Use <option>--all</option> to show + those too. To select specific properties to show, use + <option>--property=</option>. This command is intended to be + used whenever computer-parsable output is required. Use + <command>image-status</command> if you are looking for + formatted human-readable output.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>clone</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term> + + <listitem><para>Clones a container or disk 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> + </varlistentry> + + <varlistentry> + <term><command>rename</command> <replaceable>NAME</replaceable> <replaceable>NAME</replaceable></term> + + <listitem><para>Renames a container or disk image. The + arguments specify the name of the image to rename and the new + name of the image.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>read-only</command> <replaceable>NAME</replaceable> [<replaceable>BOOL</replaceable>]</term> + + <listitem><para>Marks or (unmarks) a container or disk image + read-only. Takes a VM or container image name, followed by a + boolean as arguments. If the boolean is omitted, positive is + implied, i.e. the image is marked read-only.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><command>remove</command> <replaceable>NAME</replaceable>...</term> + + <listitem><para>Removes one or more container or disk images. + The special image <literal>.host</literal>, which refers to + the host's own directory tree may not be + removed.</para></listitem> + </varlistentry> + + </variablelist></refsect2> + + <refsect2><title>Image Transfer Commands</title><variablelist> + + <varlistentry> + <term><command>pull-tar</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term> + + <listitem><para>Downloads a <filename>.tar</filename> + container image from the specified URL, and makes it available + under the specified local machine name. The URL must be of + type <literal>http://</literal> or + <literal>https://</literal>, and must refer to a + <filename>.tar</filename>, <filename>.tar.gz</filename>, + <filename>.tar.xz</filename> or <filename>.tar.bz2</filename> + archive file. If the local machine name is omitted the name it + is automatically derived from the last component of the URL, + with its suffix removed.</para> + + <para>The image is verified before it is made available, + unless <option>--verify=no</option> is specified. Verification + is done via SHA256SUMS and SHA256SUMS.gpg files, that need to + be made available on the same web server, under the same URL + as the <filename>.tar</filename> file, but with the last + component (the filename) of the URL replaced. With + <option>--verify=checksum</option> only the SHA256 checksum + for the file is verified, based on the + <filename>SHA256SUMS</filename> file. With + <option>--verify=signature</option> the SHA256SUMS file is + first verified with detached GPG signature file + <filename>SHA256SUMS.gpg</filename>. The public key for this + verification step needs to be available in + <filename>/usr/lib/systemd/import-pubring.gpg</filename> or + <filename>/etc/systemd/import-pubring.gpg</filename>.</para> + + <para>The container image will be downloaded and stored in a + read-only subvolume in + <filename>/var/lib/machines/</filename>, that is named after + the specified URL and its HTTP etag. A writable snapshot is + then taken from this subvolume, and named after the specified + local name. This behaviour ensures that creating multiple + container instances of the same URL is efficient, as multiple + downloads are not necessary. In order to create only the + read-only image, and avoid creating its writable snapshot, + specify <literal>-</literal> as local machine name.</para> + + <para>Note that the read-only subvolume is prefixed with + <filename>.tar-</filename>, and is thus now shown by + <command>list-images</command>, unless <option>--all</option> + is passed.</para> + + <para>Note that pressing C-c during execution of this command + will not abort the download. Use + <command>cancel-transfer</command>, described + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>pull-raw</command> <replaceable>URL</replaceable> [<replaceable>NAME</replaceable>]</term> + + <listitem><para>Downloads a <filename>.raw</filename> + container or VM disk image from the specified URL, and makes + it available under the specified local machine name. The URL + must be of type <literal>http://</literal> or + <literal>https://</literal>. The container image must either + be a <filename>.qcow2</filename> or raw disk image, optionally + compressed as <filename>.gz</filename>, + <filename>.xz</filename>, or <filename>.bz2</filename>. If the + local machine name is omitted the name it is automatically + derived from the last component of the URL, with its suffix + removed.</para> + + <para>Image verification is identical for raw and tar images + (see above).</para> + + <para>If the the downloaded image is in + <filename>.qcow2</filename> format it es converted into a raw + image file before it is made available.</para> + + <para>Downloaded images of this type will be placed as + read-only <filename>.raw</filename> file in + <filename>/var/lib/machines/</filename>. A local, writable + (reflinked) copy is then made under the specified local + machine name. To omit creation of the local, writable copy + pass <literal>-</literal> as local machine name.</para> + + <para>Similar to the behaviour of <command>pull-tar</command>, + the read-only image is prefixed with + <filename>.raw-</filename>, and thus now shown by + <command>list-images</command>, unless <option>--all</option> + is passed.</para> + + <para>Note that pressing C-c during execution of this command + will not abort the download. Use + <command>cancel-transfer</command>, described + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>pull-dkr</command> <replaceable>REMOTE</replaceable> [<replaceable>NAME</replaceable>]</term> + + <listitem><para>Downloads a <literal>dkr</literal> container + image and makes it available locally. The remote name refers + to a <literal>dkr</literal> container name. If omitted, the + local machine name is derived from the <literal>dkr</literal> + container name.</para> + + <para>Image verification is not available for + <literal>dkr</literal> containers, and thus + <option>--verify=no</option> must always be specified with + this command.</para> + + <para>This command downloads all (missing) layers for the + specified container and places them in read-only subvolumes in + <filename>/var/lib/machines/</filename>. A writable snapshot + of the newest layer is then created under the specified local + machine name. To omit creation of this writable snapshot, pass + <literal>-</literal> as local machine name.</para> + + <para>The read-only layer subvolumes are prefixed with + <filename>.dkr-</filename>, and thus now shown by + <command>list-images</command>, unless <option>--all</option> + is passed.</para> + + <para>To specify the <literal>dkr</literal> index server to + use for looking up the specified container, use + <option>--dkr-index-url=</option>.</para> + + <para>Note that pressing C-c during execution of this command + will not abort the download. Use + <command>cancel-transfer</command>, described + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>list-transfers</command></term> + + <listitem><para>Shows a list of container or VM image + downloads that are currently in progress.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>cancel-transfers</command> <replaceable>ID</replaceable>...</term> + + <listitem><para>Aborts download of the container or VM image + with the specified ID. To list ongoing transfers and their + IDs, use <command>list-transfers</command>. </para></listitem> + </varlistentry> + + </variablelist></refsect2> + + </refsect1> + + <refsect1> + <title>Files and Directories</title> + + <para>Machine images are preferably stored in + <filename>/var/lib/machines/</filename>, but are also searched for + in <filename>/usr/local/lib/machines/</filename> and + <filename>/usr/lib/machines/</filename>. For compatibility reasons + the directory <filename>/var/lib/container/</filename> is + searched, too. Note that images stored below + <filename>/usr</filename> are always considered read-only. It is + possible to symlink machines images from other directories into + <filename>/var/lib/machines/</filename> to make them available for + control with <command>machinectl</command>.</para> + + <para>Disk images are understood by + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and <command>machinectl</command> in three formats:</para> + + <itemizedlist> + <listitem><para>A simple directory tree, containing the files + and directories of the container to boot.</para></listitem> + + <listitem><para>A subvolume (on btrfs file systems), which are + similar to the simple directories, described above. However, + they have additional benefits, such as efficient cloning and + quota reporting.</para></listitem> + + <listitem><para>"Raw" disk images, i.e. binary images of disks + with a GPT or MBR partition table. Images of this type are + regular files with the suffix + <literal>.raw</literal>.</para></listitem> + </itemizedlist> + + <para>See + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for more information on image formats, in particular it's + <option>--directory=</option> and <option>--image=</option> + options.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + <example> + <title>Download an Ubuntu image and open a shell in it</title> + + <programlisting># machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz # systemd-nspawn -M trusty-server-cloudimg-amd64-root</programlisting> - <para>This downloads and verifies the - specified <filename>.tar</filename> image, and - then uses - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to open a shell in it.</para> - </example> - - <example> - <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 -# passwd -# exit -# machinectl start Fedora-Cloud-Base-20141203-21 -# machinectl login Fedora-Cloud-Base-20141203-21</programlisting> - - <para>This downloads the specified - <filename>.raw</filename> image with - verification disabled. Then a shell is opened - in it and a root password is set. Afterwards - the shell is left, and the machine started as - system service. With the last command a login - prompt into the container is requested.</para> - </example> - - <example> - <title>Download a Fedora <literal>dkr</literal> image</title> - - <programlisting># machinectl pull-dkr --verify=no mattdm/fedora + <para>This downloads and verifies the specified + <filename>.tar</filename> image, and then uses + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to open a shell in it.</para> + </example> + + <example> + <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 # passwd # + exit # machinectl start Fedora-Cloud-Base-20141203-21 # + machinectl login Fedora-Cloud-Base-20141203-21</programlisting> + + <para>This downloads the specified <filename>.raw</filename> + image with verification disabled. Then a shell is opened in it + and a root password is set. Afterwards the shell is left, and + the machine started as system service. With the last command a + login prompt into the container is requested.</para> + </example> + + <example> + <title>Download a Fedora <literal>dkr</literal> image</title> + + <programlisting># machinectl pull-dkr --verify=no mattdm/fedora # systemd-nspawn -M fedora</programlisting> - <para>Downloads a <literal>dkr</literal> image - and opens a shell in it. Note that the - specified download command might require an - index server to be specified with the - <literal>--dkr-index-url=</literal>.</para> - </example> - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <xi:include href="less-variables.xml" /> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <para>Downloads a <literal>dkr</literal> image and opens a shell + in it. Note that the specified download command might require an + index server to be specified with the + <literal>--dkr-index-url=</literal>.</para> + </example> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <xi:include href="less-variables.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/modules-load.d.xml b/man/modules-load.d.xml index 4b578d714c..34a937db68 100644 --- a/man/modules-load.d.xml +++ b/man/modules-load.d.xml @@ -20,83 +20,82 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> <refentry id="modules-load.d" conditional='HAVE_KMOD' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>modules-load.d</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>modules-load.d</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>modules-load.d</refname> - <refpurpose>Configure kernel modules to load at boot</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/modules-load.d/*.conf</filename></para> - <para><filename>/run/modules-load.d/*.conf</filename></para> - <para><filename>/usr/lib/modules-load.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - reads files from the above directories which contain - kernel modules to load during boot in a static list. - Each configuration file is named in the style of - <filename>/etc/modules-load.d/<replaceable>program</replaceable>.conf</filename>. Note - that it is usually a better idea to rely on the - automatic module loading by PCI IDs, USB IDs, DMI IDs - or similar triggers encoded in the kernel modules - themselves instead of static configuration like - this. In fact, most modern kernel modules are prepared - for automatic loading already.</para> - </refsect1> - - <refsect1> - <title>Configuration Format</title> - - <para>The configuration files should simply contain a - list of kernel module names to load, separated by - newlines. Empty lines and lines whose first - non-whitespace character is # or ; are ignored.</para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - - <refsect1> - <title>Example</title> - <example> - <title>/etc/modules-load.d/virtio-net.conf example:</title> - - <programlisting># Load virtio-net.ko at boot + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>modules-load.d</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>modules-load.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>modules-load.d</refname> + <refpurpose>Configure kernel modules to load at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/modules-load.d/*.conf</filename></para> + <para><filename>/run/modules-load.d/*.conf</filename></para> + <para><filename>/usr/lib/modules-load.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + reads files from the above directories which contain kernel + modules to load during boot in a static list. Each configuration + file is named in the style of + <filename>/etc/modules-load.d/<replaceable>program</replaceable>.conf</filename>. + Note that it is usually a better idea to rely on the automatic + module loading by PCI IDs, USB IDs, DMI IDs or similar triggers + encoded in the kernel modules themselves instead of static + configuration like this. In fact, most modern kernel modules are + prepared for automatic loading already.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>The configuration files should simply contain a list of + kernel module names to load, separated by newlines. Empty lines + and lines whose first non-whitespace character is # or ; are + ignored.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/modules-load.d/virtio-net.conf example:</title> + + <programlisting># Load virtio-net.ko at boot virtio-net</programlisting> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/nss-myhostname.xml b/man/nss-myhostname.xml index c7a2cd9ae7..cf2b0200f2 100644 --- a/man/nss-myhostname.xml +++ b/man/nss-myhostname.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -24,140 +24,129 @@ <refentry id="nss-myhostname" conditional='HAVE_MYHOSTNAME'> - <refentryinfo> - <title>nss-myhostname</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>nss-myhostname</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>nss-myhostname</refname> - <refname>libnss_myhostname.so.2</refname> - <refpurpose>Provide hostname resolution for the locally - configured system hostname.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>libnss_myhostname.so.2</filename></para> - </refsynopsisdiv> - - <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> - - <itemizedlist> - <listitem><para>The local, configured hostname - is resolved to all locally configured IP - addresses ordered by their scope, or -- if - none are configured -- the IPv4 address - 127.0.0.2 (which is on the local loopback) and - the IPv6 address ::1 (which is the local - host).</para></listitem> - - <listitem><para>The hostname - <literal>localhost</literal> is resolved to - the IP addresses 127.0.0.1 and - ::1.</para></listitem> - - <listitem><para>The hostname - <literal>gateway</literal> is resolved to all - current default routing gateway addresses, - ordered by their metric. This assigns a stable - hostname to the current gateway, useful for - referencing it independently of the current - network configuration state.</para></listitem> - - </itemizedlist> - - <para>Various software relies on an always-resolvable - local hostname. When using dynamic hostnames, this is - traditionally achieved by patching - <filename>/etc/hosts</filename> at the same time as - changing the hostname. This is problematic since it - requires a writable <filename>/etc</filename> file - system and is fragile because the file might be edited - by the administrator at the same time. With - <command>nss-myhostname</command> enabled changing - <filename>/etc/hosts</filename> is unncessary, 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>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 any - DNS or <filename>/etc/hosts</filename> based mapping - takes precedence.</para> - </refsect1> - - <refsect1> - <title>Example</title> - - <para>Here's an example - <filename>/etc/nsswitch.conf</filename> file, that - enables <command>myhostname</command> - correctly:</para> - -<programlisting>passwd: compat -group: compat -shadow: compat - -hosts: files dns mymachines <command>myhostname</command> + <refentryinfo> + <title>nss-myhostname</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>nss-myhostname</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>nss-myhostname</refname> + <refname>libnss_myhostname.so.2</refname> + <refpurpose>Provide hostname resolution for the locally + configured system hostname.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>libnss_myhostname.so.2</filename></para> + </refsynopsisdiv> + + <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> + + <itemizedlist> + <listitem><para>The local, configured hostname is resolved to + all locally configured IP addresses ordered by their scope, or + — if none are configured — the IPv4 address 127.0.0.2 (which + is on the local loopback) and the IPv6 address ::1 (which is the + local host).</para></listitem> + + <listitem><para>The hostname <literal>localhost</literal> is + resolved to the IP addresses 127.0.0.1 and + ::1.</para></listitem> + + <listitem><para>The hostname <literal>gateway</literal> is + resolved to all current default routing gateway addresses, + ordered by their metric. This assigns a stable hostname to the + current gateway, useful for referencing it independently of the + current network configuration state.</para></listitem> + + </itemizedlist> + + <para>Various software relies on an always-resolvable local + hostname. When using dynamic hostnames, this is traditionally + achieved by patching <filename>/etc/hosts</filename> at the same + time as changing the hostname. This is problematic since it + requires a writable <filename>/etc</filename> file system and is + fragile because the file might be edited by the administrator at + the same time. With <command>nss-myhostname</command> enabled + changing <filename>/etc/hosts</filename> is unncessary, 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>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 any DNS or + <filename>/etc/hosts</filename> based mapping takes + precedence.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <para>Here's an example <filename>/etc/nsswitch.conf</filename> + file, that enables <command>myhostname</command> correctly:</para> + +<programlisting>passwd: compat +group: compat +shadow: compat + +hosts: files dns mymachines <command>myhostname</command> networks: files protocols: db files services: db files -ethers: db files -rpc: db files +ethers: db files +rpc: db files netgroup: nis</programlisting> - <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para> + <para>To test, use <command>glibc</command>'s <command>getent</command> tool:</para> - <programlisting>$ getent ahosts `hostname` -::1 STREAM omega -::1 DGRAM -::1 RAW + <programlisting>$ getent ahosts `hostname` +::1 STREAM omega +::1 DGRAM +::1 RAW 127.0.0.2 STREAM 127.0.0.2 DGRAM 127.0.0.2 RAW</programlisting> - <para>In this case the local hostname is <varname>omega</varname>.</para> + <para>In this case the local hostname is <varname>omega</varname>.</para> - </refsect1> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/nss-mymachines.xml b/man/nss-mymachines.xml index 94673918cb..eb1ed2592b 100644 --- a/man/nss-mymachines.xml +++ b/man/nss-mymachines.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,94 +23,90 @@ <refentry id="nss-mymachines" conditional='ENABLE_MACHINED'> - <refentryinfo> - <title>nss-mymachines</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>nss-mymachines</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>nss-mymachines</refname> - <refname>libnss_mymachines.so.2</refname> - <refpurpose>Provide hostname resolution for local - container instances.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>libnss_mymachines.so.2</filename></para> - </refsynopsisdiv> - - <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 containers running locally, - that are registered with - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The - container names are resolved to IP addresses of the - specific container, ordered by their scope.</para> - - <para>To activate the NSS modules, - <literal>mymachines</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>mymachines</literal> near the end of the - <filename>nsswitch.conf</filename> line to make sure - that this mapping is only used as fallback, and any - DNS or <filename>/etc/hosts</filename> based mapping - takes precedence.</para> - </refsect1> - - <refsect1> - <title>Example</title> - - <para>Here's an example - <filename>/etc/nsswitch.conf</filename> file, that - enables <command>mymachines</command> - correctly:</para> - -<programlisting>passwd: compat -group: compat -shadow: compat - -hosts: files dns <command>mymachines</command> myhostname + <refentryinfo> + <title>nss-mymachines</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>nss-mymachines</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>nss-mymachines</refname> + <refname>libnss_mymachines.so.2</refname> + <refpurpose>Provide hostname resolution for local + container instances.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>libnss_mymachines.so.2</filename></para> + </refsynopsisdiv> + + <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 + containers running locally, that are registered with + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + The container names are resolved to IP addresses of the specific + container, ordered by their scope.</para> + + <para>To activate the NSS modules, <literal>mymachines</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>mymachines</literal> + near the end of the <filename>nsswitch.conf</filename> line to + make sure that this mapping is only used as fallback, and any DNS + or <filename>/etc/hosts</filename> based mapping takes + precedence.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <para>Here's an example <filename>/etc/nsswitch.conf</filename> + file, that enables <command>mymachines</command> correctly:</para> + +<programlisting>passwd: compat +group: compat +shadow: compat + +hosts: files dns <command>mymachines</command> myhostname networks: files protocols: db files services: db files -ethers: db files -rpc: db files +ethers: db files +rpc: db files netgroup: nis</programlisting> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/os-release.xml b/man/os-release.xml index 4fa41e7297..31dfe0ddf2 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,359 +23,286 @@ --> <refentry id="os-release"> - <refentryinfo> - <title>os-release</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>os-release</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>os-release</refname> - <refpurpose>Operating system identification</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/os-release</filename></para> - <para><filename>/usr/lib/os-release</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <filename>/etc/os-release</filename> and - <filename>/usr/lib/os-release</filename> files contain - operating system identification data.</para> - - <para>The basic file format of - <filename>os-release</filename> is a newline-separated - list of environment-like shell-compatible variable - assignments. It is possible to source the - configuration from shell scripts, however, beyond mere - variable assignments, no shell features are supported - (this means variable expansion is explicitly not - supported), allowing applications to read the file - without implementing a shell compatible execution - engine. Variable assignment values must be enclosed in - double or single quotes if they include spaces, - semicolons or other special characters outside of A-Z, - a-z, 0-9. Shell special characters ("$", quotes, - backslash, backtick) must be escaped with backslashes, - following shell style. All strings should be in UTF-8 - format, and non-printable characters should not be used. - It is not supported to concatenate multiple individually - quoted strings. Lines beginning with "#" shall be - ignored as comments.</para> - - <para>The file <filename>/etc/os-release</filename> - takes precedence over - <filename>/usr/lib/os-release</filename>. Applications - should check for the former, and exclusively use its - data if it exists, and only fall back to - <filename>/usr/lib/os-release</filename> if it is - missing. Applications should not read data from both - files at the same - time. <filename>/usr/lib/os-release</filename> is the - recommended place to store OS release information as - part of vendor trees. - <filename>/etc/os-release</filename> should be a - relative symlink to - <filename>/usr/lib/os-release</filename>, - to provide compatibility with applications only - looking at <filename>/etc</filename>. A relative - symlink instead of an absolute symlink is - necessary to avoid breaking the link in a chroot or - initrd environment such as dracut.</para> - - <para><filename>os-release</filename> contains data - that is defined by the operating system vendor and - should generally not be changed by the - administrator.</para> - - <para>As this file only encodes names and identifiers - it should not be localized.</para> - - <para>The <filename>/etc/os-release</filename> and - <filename>/usr/lib/os-release</filename> files might - be symlinks to other files, but it is important that - the file is available from earliest boot on, and hence - must be located on the root file system.</para> - - <para>For a longer rationale for - <filename>os-release</filename> please refer to - the <ulink - url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following OS identifications parameters may be set using - <filename>os-release</filename>:</para> - - <variablelist> - - <varlistentry> - <term><varname>NAME=</varname></term> - - <listitem><para>A string identifying - the operating system, without a - version component, and suitable for - presentation to the user. If not set, - defaults to - <literal>NAME=Linux</literal>. Example: - <literal>NAME=Fedora</literal> or - <literal>NAME="Debian - GNU/Linux"</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>VERSION=</varname></term> - - <listitem><para>A string identifying - the operating system version, - excluding any OS name information, - possibly including a release code - name, and suitable for presentation to - the user. This field is - optional. Example: - <literal>VERSION=17</literal> or - <literal>VERSION="17 (Beefy - Miracle)"</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ID=</varname></term> - - <listitem><para>A lower-case string - (no spaces or other characters outside - of 0-9, a-z, ".", "_" and "-") - identifying the operating system, - excluding any version information and - suitable for processing by scripts or - usage in generated filenames. If not - set, defaults to - <literal>ID=linux</literal>. Example: - <literal>ID=fedora</literal> or - <literal>ID=debian</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ID_LIKE=</varname></term> - - <listitem><para>A space-separated list - of operating system identifiers in the - same syntax as the - <varname>ID=</varname> setting. It should - list identifiers of operating systems - that are closely related to the local - operating system in regards to - packaging and programming interfaces, - for example listing one or more - OS identifiers the local - OS is a derivative from. An - OS should generally only list other OS - identifiers it itself is a derivative - of, and not any OSes that - are derived from it, though symmetric - relationships are possible. Build - scripts and similar should check this - variable if they need to identify the - local operating system and the value - of <varname>ID=</varname> is not - recognized. Operating systems should - be listed in order of how closely the - local operating system relates to the - listed ones, starting with the - closest. This field is - optional. Example: for an operating - system with - <literal>ID=centos</literal>, an - assignment of <literal>ID_LIKE="rhel - fedora"</literal> would be - appropriate. For an operating system - with <literal>ID=ubuntu</literal>, an - assignment of - <literal>ID_LIKE=debian</literal> is - appropriate.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>VERSION_ID=</varname></term> - - <listitem><para>A lower-case string - (mostly numeric, no spaces or other - characters outside of 0-9, a-z, ".", - "_" and "-") identifying the operating - system version, excluding any OS name - information or release code name, and - suitable for processing by scripts or - usage in generated filenames. This - field is optional. Example: - <literal>VERSION_ID=17</literal> or - <literal>VERSION_ID=11.04</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PRETTY_NAME=</varname></term> - - <listitem><para>A pretty operating - system name in a format suitable for - presentation to the user. May or may - not contain a release code name or OS - version of some kind, as suitable. If - not set, defaults to - <literal>PRETTY_NAME="Linux"</literal>. Example: - <literal>PRETTY_NAME="Fedora 17 (Beefy - Miracle)"</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ANSI_COLOR=</varname></term> - - <listitem><para>A suggested - presentation color when showing the - OS name on the console. This - should be specified as string suitable - for inclusion in the ESC [ m - ANSI/ECMA-48 escape code for setting - graphical rendition. This field is - optional. Example: - <literal>ANSI_COLOR="0;31"</literal> - for red, or - <literal>ANSI_COLOR="1;34"</literal> - for light blue.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>CPE_NAME=</varname></term> - - <listitem><para>A CPE name for the - operating system, following the <ulink - url="https://cpe.mitre.org/specification/">Common - Platform Enumeration - Specification</ulink> as proposed by - the MITRE Corporation. This field - is optional. Example: - <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal> - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>HOME_URL=</varname></term> - <term><varname>SUPPORT_URL=</varname></term> - <term><varname>BUG_REPORT_URL=</varname></term> - <term><varname>PRIVACY_POLICY_URL=</varname></term> - - <listitem><para>Links to resources on - the Internet related the operating - system. <varname>HOME_URL=</varname> - should refer to the homepage of the - operating system, or alternatively - some homepage of the specific version - of the operating - system. <varname>SUPPORT_URL=</varname> - should refer to the main support page - for the operating system, if there is - any. This is primarily intended for - operating systems which vendors - provide support - for. <varname>BUG_REPORT_URL=</varname> - should refer to the main bug reporting - page for the operating system, if - there is any. This is primarily - intended for operating systems that - rely on community QA. - <varname>PRIVACY_POLICY_URL=</varname> - should refer to the main privacy policy - page for the operation system, if there - is any. These settings - are optional, and providing only some - of these settings is common. These - URLs are intended to be exposed in - "About this system" UIs behind links - with captions such as "About this - Operating System", "Obtain Support", - "Report a Bug", or "Privacy Policy". The - values should be in <ulink - url="https://tools.ietf.org/html/rfc3986">RFC3986 - format</ulink>, and should be - <literal>http:</literal> or - <literal>https:</literal> URLs, and - possibly <literal>mailto:</literal> or - <literal>tel:</literal>. Only one URL - shall be listed in each setting. If - multiple resources need to be - referenced, it is recommended to - provide an online landing page linking - all available resources. Examples: - <literal>HOME_URL="https://fedoraproject.org/"</literal> - and - <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>BUILD_ID=</varname></term> - - <listitem><para>A string uniquely - identifying the system image used as - the origin for a distribution (it is - not updated with system updates). The - field can be identical between - different VERSION_IDs as BUILD_ID is - an only a unique identifier to a - specific version. Distributions that - release each update as a new version - would only need to use VERSION_ID as - each build is already distinct based - on the VERSION_ID. This field is - optional. Example: - <literal>BUILD_ID="2013-03-20.3"</literal> - or - <literal>BUILD_ID=201303203</literal>. - - </para></listitem> - </varlistentry> - - </variablelist> - - <para>If you are reading this file from C code or a - shell script to determine the OS or a specific version - of it, use the ID and VERSION_ID fields, possibly with - ID_LIKE as fallback for ID. When looking for an OS - identification string for presentation to the user use - the PRETTY_NAME field.</para> - - <para>Note that operating system vendors may choose - not to provide version information, for example to - accommodate for rolling releases. In this case, VERSION - and VERSION_ID may be unset. Applications should not - rely on these fields to be set.</para> - - <para>Operating system vendors may extend the file - format and introduce new fields. It is highly - recommended to prefix new fields with an OS specific - name in order to avoid name clashes. Applications - reading this file must ignore unknown fields. Example: - <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para> - </refsect1> - - <refsect1> - <title>Example</title> - - <programlisting>NAME=Fedora + <refentryinfo> + <title>os-release</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>os-release</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>os-release</refname> + <refpurpose>Operating system identification</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/os-release</filename></para> + <para><filename>/usr/lib/os-release</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/os-release</filename> and + <filename>/usr/lib/os-release</filename> files contain operating + system identification data.</para> + + <para>The basic file format of <filename>os-release</filename> is + a newline-separated list of environment-like shell-compatible + variable assignments. It is possible to source the configuration + from shell scripts, however, beyond mere variable assignments, no + shell features are supported (this means variable expansion is + explicitly not supported), allowing applications to read the file + without implementing a shell compatible execution engine. Variable + assignment values must be enclosed in double or single quotes if + they include spaces, semicolons or other special characters + outside of A-Z, a-z, 0-9. Shell special characters ("$", quotes, + backslash, backtick) must be escaped with backslashes, following + shell style. All strings should be in UTF-8 format, and + non-printable characters should not be used. It is not supported + to concatenate multiple individually quoted strings. Lines + beginning with "#" shall be ignored as comments.</para> + + <para>The file <filename>/etc/os-release</filename> takes + precedence over <filename>/usr/lib/os-release</filename>. + Applications should check for the former, and exclusively use its + data if it exists, and only fall back to + <filename>/usr/lib/os-release</filename> if it is missing. + Applications should not read data from both files at the same + time. <filename>/usr/lib/os-release</filename> is the recommended + place to store OS release information as part of vendor trees. + <filename>/etc/os-release</filename> should be a relative symlink + to <filename>/usr/lib/os-release</filename>, to provide + compatibility with applications only looking at + <filename>/etc</filename>. A relative symlink instead of an + absolute symlink is necessary to avoid breaking the link in a + chroot or initrd environment such as dracut.</para> + + <para><filename>os-release</filename> contains data that is + defined by the operating system vendor and should generally not be + changed by the administrator.</para> + + <para>As this file only encodes names and identifiers it should + not be localized.</para> + + <para>The <filename>/etc/os-release</filename> and + <filename>/usr/lib/os-release</filename> files might be symlinks + to other files, but it is important that the file is available + from earliest boot on, and hence must be located on the root file + system.</para> + + <para>For a longer rationale for <filename>os-release</filename> + please refer to the <ulink + url="http://0pointer.de/blog/projects/os-release">Announcement of + <filename>/etc/os-release</filename></ulink>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following OS identifications parameters may be set using + <filename>os-release</filename>:</para> + + <variablelist> + + <varlistentry> + <term><varname>NAME=</varname></term> + + <listitem><para>A string identifying the operating system, + without a version component, and suitable for presentation to + the user. If not set, defaults to + <literal>NAME=Linux</literal>. Example: + <literal>NAME=Fedora</literal> or <literal>NAME="Debian + GNU/Linux"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VERSION=</varname></term> + + <listitem><para>A string identifying the operating system + version, excluding any OS name information, possibly including + a release code name, and suitable for presentation to the + user. This field is optional. Example: + <literal>VERSION=17</literal> or <literal>VERSION="17 (Beefy + Miracle)"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID=</varname></term> + + <listitem><para>A lower-case string (no spaces or other + characters outside of 0-9, a-z, ".", "_" and "-") identifying + the operating system, excluding any version information and + suitable for processing by scripts or usage in generated + filenames. If not set, defaults to + <literal>ID=linux</literal>. Example: + <literal>ID=fedora</literal> or + <literal>ID=debian</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID_LIKE=</varname></term> + + <listitem><para>A space-separated list of operating system + identifiers in the same syntax as the <varname>ID=</varname> + setting. It should list identifiers of operating systems that + are closely related to the local operating system in regards + to packaging and programming interfaces, for example listing + one or more OS identifiers the local OS is a derivative from. + An OS should generally only list other OS identifiers it + itself is a derivative of, and not any OSes that are derived + from it, though symmetric relationships are possible. Build + scripts and similar should check this variable if they need to + identify the local operating system and the value of + <varname>ID=</varname> is not recognized. Operating systems + should be listed in order of how closely the local operating + system relates to the listed ones, starting with the closest. + This field is optional. Example: for an operating system with + <literal>ID=centos</literal>, an assignment of + <literal>ID_LIKE="rhel fedora"</literal> would be appropriate. + For an operating system with <literal>ID=ubuntu</literal>, an + assignment of <literal>ID_LIKE=debian</literal> is + appropriate.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VERSION_ID=</varname></term> + + <listitem><para>A lower-case string (mostly numeric, no spaces + or other characters outside of 0-9, a-z, ".", "_" and "-") + identifying the operating system version, excluding any OS + name information or release code name, and suitable for + processing by scripts or usage in generated filenames. This + field is optional. Example: <literal>VERSION_ID=17</literal> + or <literal>VERSION_ID=11.04</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PRETTY_NAME=</varname></term> + + <listitem><para>A pretty operating system name in a format + suitable for presentation to the user. May or may not contain + a release code name or OS version of some kind, as suitable. + If not set, defaults to + <literal>PRETTY_NAME="Linux"</literal>. Example: + <literal>PRETTY_NAME="Fedora 17 (Beefy + Miracle)"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ANSI_COLOR=</varname></term> + + <listitem><para>A suggested presentation color when showing + the OS name on the console. This should be specified as string + suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code + for setting graphical rendition. This field is optional. + Example: <literal>ANSI_COLOR="0;31"</literal> for red, or + <literal>ANSI_COLOR="1;34"</literal> for light + blue.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPE_NAME=</varname></term> + + <listitem><para>A CPE name for the operating system, following + the <ulink url="https://cpe.mitre.org/specification/">Common + Platform Enumeration Specification</ulink> as proposed by the + MITRE Corporation. This field is optional. Example: + <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal> + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>HOME_URL=</varname></term> + <term><varname>SUPPORT_URL=</varname></term> + <term><varname>BUG_REPORT_URL=</varname></term> + <term><varname>PRIVACY_POLICY_URL=</varname></term> + + <listitem><para>Links to resources on the Internet related the + operating system. <varname>HOME_URL=</varname> should refer to + the homepage of the operating system, or alternatively some + homepage of the specific version of the operating system. + <varname>SUPPORT_URL=</varname> should refer to the main + support page for the operating system, if there is any. This + is primarily intended for operating systems which vendors + provide support for. <varname>BUG_REPORT_URL=</varname> should + refer to the main bug reporting page for the operating system, + if there is any. This is primarily intended for operating + systems that rely on community QA. + <varname>PRIVACY_POLICY_URL=</varname> should refer to the + main privacy policy page for the operation system, if there is + any. These settings are optional, and providing only some of + these settings is common. These URLs are intended to be + exposed in "About this system" UIs behind links with captions + such as "About this Operating System", "Obtain Support", + "Report a Bug", or "Privacy Policy". The values should be in + <ulink url="https://tools.ietf.org/html/rfc3986">RFC3986 + format</ulink>, and should be <literal>http:</literal> or + <literal>https:</literal> URLs, and possibly + <literal>mailto:</literal> or <literal>tel:</literal>. Only + one URL shall be listed in each setting. If multiple resources + need to be referenced, it is recommended to provide an online + landing page linking all available resources. Examples: + <literal>HOME_URL="https://fedoraproject.org/"</literal> and + <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BUILD_ID=</varname></term> + + <listitem><para>A string uniquely identifying the system image + used as the origin for a distribution (it is not updated with + system updates). The field can be identical between different + VERSION_IDs as BUILD_ID is an only a unique identifier to a + specific version. Distributions that release each update as a + new version would only need to use VERSION_ID as each build is + already distinct based on the VERSION_ID. This field is + optional. Example: <literal>BUILD_ID="2013-03-20.3"</literal> + or <literal>BUILD_ID=201303203</literal>. + + </para></listitem> + </varlistentry> + + </variablelist> + + <para>If you are reading this file from C code or a shell script + to determine the OS or a specific version of it, use the + <varname>ID</varname> and <varname>VERSION_ID</varname> fields, + possibly with <varname>ID_LIKE</varname> as fallback for + <varname>ID</varname>. When looking for an OS identification + string for presentation to the user use the + <varname>PRETTY_NAME</varname> field.</para> + + <para>Note that operating system vendors may choose not to provide + version information, for example to accommodate for rolling + releases. In this case, <varname>VERSION</varname> and + <varname>VERSION_ID</varname> may be unset. Applications should + not rely on these fields to be set.</para> + + <para>Operating system vendors may extend the file + format and introduce new fields. It is highly + recommended to prefix new fields with an OS specific + name in order to avoid name clashes. Applications + reading this file must ignore unknown fields. Example: + <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting>NAME=Fedora VERSION="17 (Beefy Miracle)" ID=fedora VERSION_ID=17 @@ -384,17 +311,17 @@ ANSI_COLOR="0;34" CPE_NAME="cpe:/o:fedoraproject:fedora:17" HOME_URL="https://fedoraproject.org/" BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/pam_systemd.xml b/man/pam_systemd.xml index 3e106ea69b..b4a3f502b4 100644 --- a/man/pam_systemd.xml +++ b/man/pam_systemd.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,292 +23,250 @@ <refentry id="pam_systemd" conditional='HAVE_PAM'> - <refentryinfo> - <title>pam_systemd</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>pam_systemd</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>pam_systemd</refname> - <refpurpose>Register user sessions in the systemd login manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>pam_systemd.so</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>pam_systemd</command> registers user - sessions with the systemd login manager - <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - and hence the systemd control group hierarchy.</para> - - <para>On login, this module ensures the following:</para> - - <orderedlist> - <listitem><para>If it does not exist yet, the - user runtime directory - <filename>/run/user/$USER</filename> is - created and its ownership changed to the user - that is logging in.</para></listitem> - - <listitem><para>The - <varname>$XDG_SESSION_ID</varname> environment - variable is initialized. If auditing is - available and - <command>pam_loginuid.so</command> was run before - this module (which is highly recommended), the - variable is initialized from the auditing - session id - (<filename>/proc/self/sessionid</filename>). Otherwise, - an independent session counter is - used.</para></listitem> - - <listitem><para>A new systemd scope unit is - created for the session. If this is the first - concurrent session of the user, an implicit - slice below <filename>user.slice</filename> is - automatically created and the scope placed into - it. An instance of the system service - <filename>user@.service</filename>, which runs - the systemd user manager instance, is started. - </para></listitem> - </orderedlist> - - <para>On logout, this module ensures the following:</para> - - <orderedlist> - <listitem><para>If enabled in - <citerefentry><refentrytitle>logind.conf</refentrytitle> - <manvolnum>5</manvolnum></citerefentry>, all - processes of the session are terminated. If - the last concurrent session of a user ends, - the user's systemd instance will be - terminated too, and so will the user's slice - unit.</para></listitem> - - <listitem><para>If the last concurrent session - of a user ends, the - <varname>$XDG_RUNTIME_DIR</varname> directory - and all its contents are removed, - too.</para></listitem> - </orderedlist> - - <para>If the system was not booted up with systemd as - init system, this module does nothing and immediately - returns PAM_SUCCESS.</para> - - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist class='pam-directives'> - - <varlistentry> - <term><option>class=</option></term> - - <listitem><para>Takes a string - argument which sets the session class. - The XDG_SESSION_CLASS environmental variable - takes precedence. One of - <literal>user</literal>, - <literal>greeter</literal>, - <literal>lock-screen</literal> or - <literal>background</literal>. See - <citerefentry><refentrytitle>sd_session_get_class</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details about the session class.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>type=</option></term> - - <listitem><para>Takes a string - argument which sets the session type. - The XDG_SESSION_TYPE environmental - variable takes precedence. One of - <literal>unspecified</literal>, - <literal>tty</literal>, - <literal>x11</literal>, - <literal>wayland</literal> or - <literal>mir</literal>. See - <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details about the session type.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>debug<optional>=</optional></option></term> - - <listitem><para>Takes an optional - boolean argument. If yes or without - the argument, the module will log - debugging information as it - operates.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Module Types Provided</title> - - <para>Only <option>session</option> is provided.</para> - </refsect1> - - <refsect1> - <title>Environment</title> - - <para>The following environment variables are set for the processes of the user's session:</para> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$XDG_SESSION_ID</varname></term> - - <listitem><para>A session identifier, - suitable to be used in filenames. The - string itself should be considered - opaque, although often it is just the - audit session ID as reported by - <filename>/proc/self/sessionid</filename>. Each - ID will be assigned only once during - machine uptime. It may hence be used - to uniquely label files or other - resources of this - session.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_RUNTIME_DIR</varname></term> - - <listitem><para>Path to a user-private - user-writable directory that is bound - to the user login time on the - machine. It is automatically created - the first time a user logs in and - removed on the user's final logout. If - a user logs in twice at the same time, - both sessions will see the same - <varname>$XDG_RUNTIME_DIR</varname> - and the same contents. If a user logs - in once, then logs out again, and logs - in again, the directory contents will - have been lost in between, but - applications should not rely on this - behavior and must be able to deal with - stale files. To store session-private - data in this directory, the user - should include the value of - <varname>$XDG_SESSION_ID</varname> in - the filename. This directory shall be - used for runtime file system objects - such as <constant>AF_UNIX</constant> - sockets, FIFOs, PID files and - similar. It is guaranteed that this - directory is local and offers the - greatest possible file system feature - set the operating system provides. For - further details see the <ulink - url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG - Base Directory - Specification</ulink>.</para></listitem> - </varlistentry> - - </variablelist> - - <para>The following environment variables are read by - the module and may be used by the PAM service to pass - metadata to the module:</para> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$XDG_SESSION_TYPE</varname></term> - - <listitem><para>The session type. This - may be used instead of - <option>session=</option> on the - module parameter line, and is usually - preferred.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_SESSION_CLASS</varname></term> - - <listitem><para>The session class. This - may be used instead of - <option>class=</option> on the - module parameter line, and is usually - preferred.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_SESSION_DESKTOP</varname></term> - - <listitem><para>A single, short - identifier string for the desktop - environment. This may be used to - indicate the session desktop used, - where this applies and if this - information is available. For example: - <literal>GNOME</literal>, or - <literal>KDE</literal>. It is - recommended to use the same - identifiers and capitalization as for - <varname>$XDG_CURRENT_DESKTOP</varname>, - as defined by the <ulink - url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop - Entry Specification</ulink>. (However, - note that - <varname>$XDG_SESSION_DESKTOP</varname> - only takes a single item, and not a - colon-separated list like - <varname>$XDG_CURRENT_DESKTOP</varname>.) - See - <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_SEAT</varname></term> - - <listitem><para>The seat name the session - shall be registered for, if - any.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_VTNR</varname></term> - - <listitem><para>The VT number the - session shall be registered for, if - any. (Only applies to seats with a VT - available, such as - <literal>seat0</literal>)</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Example</title> - - <programlisting>#%PAM-1.0 + <refentryinfo> + <title>pam_systemd</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>pam_systemd</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>pam_systemd</refname> + <refpurpose>Register user sessions in the systemd login manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>pam_systemd.so</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>pam_systemd</command> registers user sessions with + the systemd login manager + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + and hence the systemd control group hierarchy.</para> + + <para>On login, this module ensures the following:</para> + + <orderedlist> + <listitem><para>If it does not exist yet, the user runtime + directory <filename>/run/user/$USER</filename> is created and + its ownership changed to the user that is logging + in.</para></listitem> + + <listitem><para>The <varname>$XDG_SESSION_ID</varname> + environment variable is initialized. If auditing is available + and <command>pam_loginuid.so</command> was run before this + module (which is highly recommended), the variable is + initialized from the auditing session id + (<filename>/proc/self/sessionid</filename>). Otherwise, an + independent session counter is used.</para></listitem> + + <listitem><para>A new systemd scope unit is created for the + session. If this is the first concurrent session of the user, an + implicit slice below <filename>user.slice</filename> is + automatically created and the scope placed into it. An instance + of the system service <filename>user@.service</filename>, which + runs the systemd user manager instance, is started. + </para></listitem> + </orderedlist> + + <para>On logout, this module ensures the following:</para> + + <orderedlist> + <listitem><para>If enabled in + <citerefentry><refentrytitle>logind.conf</refentrytitle> + <manvolnum>5</manvolnum></citerefentry>, all processes of the + session are terminated. If the last concurrent session of a user + ends, the user's systemd instance will be terminated too, and so + will the user's slice unit.</para></listitem> + + <listitem><para>If the last concurrent session of a user ends, + the <varname>$XDG_RUNTIME_DIR</varname> directory and all its + contents are removed, too.</para></listitem> + </orderedlist> + + <para>If the system was not booted up with systemd as init system, + this module does nothing and immediately returns + <constant>PAM_SUCCESS</constant>.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist class='pam-directives'> + + <varlistentry> + <term><option>class=</option></term> + + <listitem><para>Takes a string argument which sets the session + class. The XDG_SESSION_CLASS environmental variable takes + precedence. One of + <literal>user</literal>, + <literal>greeter</literal>, + <literal>lock-screen</literal> or + <literal>background</literal>. See + <citerefentry><refentrytitle>sd_session_get_class</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details about the session class.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>type=</option></term> + + <listitem><para>Takes a string argument which sets the session + type. The XDG_SESSION_TYPE environmental variable takes + precedence. One of + <literal>unspecified</literal>, + <literal>tty</literal>, + <literal>x11</literal>, + <literal>wayland</literal> or + <literal>mir</literal>. See + <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details about the session type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>debug<optional>=</optional></option></term> + + <listitem><para>Takes an optional + boolean argument. If yes or without + the argument, the module will log + debugging information as it + operates.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Module Types Provided</title> + + <para>Only <option>session</option> is provided.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <para>The following environment variables are set for the + processes of the user's session:</para> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$XDG_SESSION_ID</varname></term> + + <listitem><para>A session identifier, suitable to be used in + filenames. The string itself should be considered opaque, + although often it is just the audit session ID as reported by + <filename>/proc/self/sessionid</filename>. Each ID will be + assigned only once during machine uptime. It may hence be used + to uniquely label files or other resources of this + session.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_RUNTIME_DIR</varname></term> + + <listitem><para>Path to a user-private user-writable directory + that is bound to the user login time on the machine. It is + automatically created the first time a user logs in and + removed on the user's final logout. If a user logs in twice at + the same time, both sessions will see the same + <varname>$XDG_RUNTIME_DIR</varname> and the same contents. If + a user logs in once, then logs out again, and logs in again, + the directory contents will have been lost in between, but + applications should not rely on this behavior and must be able + to deal with stale files. To store session-private data in + this directory, the user should include the value of + <varname>$XDG_SESSION_ID</varname> in the filename. This + directory shall be used for runtime file system objects such + as <constant>AF_UNIX</constant> sockets, FIFOs, PID files and + similar. It is guaranteed that this directory is local and + offers the greatest possible file system feature set the + operating system provides. For further details see the <ulink + url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory Specification</ulink>.</para></listitem> + </varlistentry> + + </variablelist> + + <para>The following environment variables are read by the module + and may be used by the PAM service to pass metadata to the + module:</para> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$XDG_SESSION_TYPE</varname></term> + + <listitem><para>The session type. This may be used instead of + <option>session=</option> on the module parameter line, and is + usually preferred.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_SESSION_CLASS</varname></term> + + <listitem><para>The session class. This may be used instead of + <option>class=</option> on the module parameter line, and is + usually preferred.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_SESSION_DESKTOP</varname></term> + + <listitem><para>A single, short identifier string for the + desktop environment. This may be used to indicate the session + desktop used, where this applies and if this information is + available. For example: <literal>GNOME</literal>, or + <literal>KDE</literal>. It is recommended to use the same + identifiers and capitalization as for + <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the + <ulink + url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop + Entry Specification</ulink>. (However, note that + <varname>$XDG_SESSION_DESKTOP</varname> only takes a single + item, and not a colon-separated list like + <varname>$XDG_CURRENT_DESKTOP</varname>.) See + <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_SEAT</varname></term> + + <listitem><para>The seat name the session shall be registered + for, if any.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_VTNR</varname></term> + + <listitem><para>The VT number the session shall be registered + for, if any. (Only applies to seats with a VT available, such + as <literal>seat0</literal>)</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting>#%PAM-1.0 auth required pam_unix.so auth required pam_nologin.so account required pam_unix.so @@ -316,23 +274,23 @@ password required pam_unix.so session required pam_unix.so session required pam_loginuid.so session required pam_systemd.so</programlisting> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml index 36013a5e3a..21e3c3c331 100644 --- a/man/resolved.conf.xml +++ b/man/resolved.conf.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,126 +23,109 @@ --> <refentry id="resolved.conf" conditional='ENABLE_RESOLVED' - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>resolved.conf</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>resolved.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>resolved.conf</refname> - <refname>resolved.conf.d</refname> - <refpurpose>Network Name Resolution configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/resolved.conf</filename></para> - <para><filename>/etc/systemd/resolved.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/resolved.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/resolved.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These configuration files control local DNS and LLMNR - name resolving.</para> - - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - <xi:include href="standard-conf.xml" xpointer="conf" /> - - <refsect1> - <title>Options</title> - - <variablelist class='network-directives'> - - <varlistentry> - <term><varname>DNS=</varname></term> - <listitem><para>A space separated list - of IPv4 and IPv6 addresses to be used - as system DNS servers. DNS requests - are sent to one of the listed DNS - servers in parallel to any - per-interface DNS servers acquired - from - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. For - compatibility reasons, if set to the - empty list the DNS servers listed in - <filename>/etc/resolv.conf</filename> - are used, if any are - configured there. This setting - defaults to the empty - list.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>FallbackDNS=</varname></term> - <listitem><para>A space separated list - of IPv4 and IPv6 addresses to be used - as the fallback DNS servers. Any - per-interface DNS servers obtained - from - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - take precedence over this setting, as - do any servers set via - <varname>DNS=</varname> above or - <filename>/etc/resolv.conf</filename>. This - setting is hence only used if no other - DNS server information is known. If - this option is not given, a - compiled-in list of DNS servers is - used instead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>LLMNR=</varname></term> - <listitem><para>Takes a boolean - argument or - <literal>resolve</literal>. Controls - Link-Local Multicast Name Resolution support (<ulink - url="https://tools.ietf.org/html/rfc4795">RFC - 4794</ulink>) on the local host. If - true enables full LLMNR responder and - resolver support. If false disable - both. If set to - <literal>resolve</literal> only - resolving support is enabled, but - responding is disabled. Note that - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - also maintains per-interface LLMNR - settings. LLMNR will be enabled on an - interface only if the per-interface - and the global setting is - on.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>resolved.conf</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + <email>teg@jklm.no</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>resolved.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>resolved.conf</refname> + <refname>resolved.conf.d</refname> + <refpurpose>Network Name Resolution configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/resolved.conf</filename></para> + <para><filename>/etc/systemd/resolved.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/resolved.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/resolved.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These configuration files control local DNS and LLMNR + name resolving.</para> + + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + <xi:include href="standard-conf.xml" xpointer="conf" /> + + <refsect1> + <title>Options</title> + + <variablelist class='network-directives'> + + <varlistentry> + <term><varname>DNS=</varname></term> + <listitem><para>A space separated list of IPv4 and IPv6 + addresses to be used as system DNS servers. DNS requests are + sent to one of the listed DNS servers in parallel to any + per-interface DNS servers acquired from + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + For compatibility reasons, if set to the empty list the DNS + servers listed in <filename>/etc/resolv.conf</filename> are + used, if any are configured there. This setting defaults to + the empty list.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FallbackDNS=</varname></term> + <listitem><para>A space separated list of IPv4 and IPv6 + addresses to be used as the fallback DNS servers. Any + per-interface DNS servers obtained from + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + take precedence over this setting, as do any servers set via + <varname>DNS=</varname> above or + <filename>/etc/resolv.conf</filename>. This setting is hence + only used if no other DNS server information is known. If this + option is not given, a compiled-in list of DNS servers is used + instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LLMNR=</varname></term> + <listitem><para>Takes a boolean argument or + <literal>resolve</literal>. Controls Link-Local Multicast Name + Resolution support (<ulink + url="https://tools.ietf.org/html/rfc4795">RFC 4794</ulink>) on + the local host. If true enables full LLMNR responder and + resolver support. If false disable both. If set to + <literal>resolve</literal> only resolving support is enabled, + but responding is disabled. Note that + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + also maintains per-interface LLMNR settings. LLMNR will be + enabled on an interface only if the per-interface and the + global setting is on.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/runlevel.xml b/man/runlevel.xml index db9a436724..fc1f523855 100644 --- a/man/runlevel.xml +++ b/man/runlevel.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,134 +22,127 @@ --> <refentry id="runlevel" - xmlns:xi="http://www.w3.org/2001/XInclude" - conditional="HAVE_UTMP"> - - <refentryinfo> - <title>runlevel</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>runlevel</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>runlevel</refname> - <refpurpose>Print previous and current SysV runlevel</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>runlevel <arg choice="opt" rep="repeat">options</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>runlevel</command> prints the previous - and current SysV runlevel if they are known.</para> - - <para>The two runlevel characters are separated by a - single space character. If a runlevel cannot be - determined, N is printed instead. If neither can be - determined, the word "unknown" is printed.</para> - - <para>Unless overridden in the environment, this will - check the utmp database for recent runlevel - changes.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following option is understood:</para> - - <variablelist> - <varlistentry> - <term><option>--help</option></term> - - <xi:include href="standard-options.xml" xpointer="help-text" /> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>If one or both runlevels could be determined, 0 - is returned, a non-zero failure code otherwise.</para> - - </refsect1> - - <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$RUNLEVEL</varname></term> - - <listitem><para>If - <varname>$RUNLEVEL</varname> is set, - <command>runlevel</command> will print - this value as current runlevel and - ignore utmp.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$PREVLEVEL</varname></term> - - <listitem><para>If - <varname>$PREVLEVEL</varname> is set, - <command>runlevel</command> will print - this value as previous runlevel and - ignore utmp.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Files</title> - - <variablelist> - <varlistentry> - <term><filename>/var/run/utmp</filename></term> - - <listitem><para>The utmp database - <command>runlevel</command> reads the - previous and current runlevel - from.</para></listitem> - - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>This is a legacy command available for compatibility - only. It should not be used anymore, as the concept of - runlevels is obsolete.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude" + conditional="HAVE_UTMP"> + + <refentryinfo> + <title>runlevel</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>runlevel</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>runlevel</refname> + <refpurpose>Print previous and current SysV runlevel</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>runlevel <arg choice="opt" rep="repeat">options</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>runlevel</command> prints the previous and current + SysV runlevel if they are known.</para> + + <para>The two runlevel characters are separated by a single space + character. If a runlevel cannot be determined, N is printed + instead. If neither can be determined, the word "unknown" is + printed.</para> + + <para>Unless overridden in the environment, this will check the + utmp database for recent runlevel changes.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following option is understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + + <xi:include href="standard-options.xml" xpointer="help-text" /> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>If one or both runlevels could be determined, 0 is returned, + a non-zero failure code otherwise.</para> + + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$RUNLEVEL</varname></term> + + <listitem><para>If <varname>$RUNLEVEL</varname> is set, + <command>runlevel</command> will print this value as current + runlevel and ignore utmp.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$PREVLEVEL</varname></term> + + <listitem><para>If <varname>$PREVLEVEL</varname> is set, + <command>runlevel</command> will print this value as previous + runlevel and ignore utmp.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Files</title> + + <variablelist> + <varlistentry> + <term><filename>/var/run/utmp</filename></term> + + <listitem><para>The utmp database <command>runlevel</command> + reads the previous and current runlevel + from.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>This is a legacy command available for compatibility only. + It should not be used anymore, as the concept of runlevels is + obsolete.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd-daemon.xml b/man/sd-daemon.xml index 5f331e740a..b7ba363656 100644 --- a/man/sd-daemon.xml +++ b/man/sd-daemon.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,71 +22,71 @@ --> <refentry id="sd-daemon" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd-daemon</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd-daemon</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd-daemon</refname> - <refname>SD_EMERG</refname> - <refname>SD_ALERT</refname> - <refname>SD_CRIT</refname> - <refname>SD_ERR</refname> - <refname>SD_WARNING</refname> - <refname>SD_NOTICE</refname> - <refname>SD_INFO</refname> - <refname>SD_DEBUG</refname> - <refpurpose>APIs for - new-style daemons</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> - </funcsynopsis> - - <cmdsynopsis> - <command>pkg-config --cflags --libs libsystemd</command> - </cmdsynopsis> - - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>sd-daemon.h</filename> provide APIs - for new-style daemons, as implemented by the - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - init system.</para> - - <para>See - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information about the functions - implemented. In addition to these functions, a couple - of logging prefixes are defined as macros:</para> - - <programlisting>#define SD_EMERG "<0>" /* system is unusable */ + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd-daemon</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-daemon</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-daemon</refname> + <refname>SD_EMERG</refname> + <refname>SD_ALERT</refname> + <refname>SD_CRIT</refname> + <refname>SD_ERR</refname> + <refname>SD_WARNING</refname> + <refname>SD_NOTICE</refname> + <refname>SD_INFO</refname> + <refname>SD_DEBUG</refname> + <refpurpose>APIs for + new-style daemons</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libsystemd</command> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-daemon.h</filename> provide APIs for new-style + daemons, as implemented by the + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + init system.</para> + + <para>See + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the functions implemented. In addition + to these functions, a couple of logging prefixes are defined as + macros:</para> + + <programlisting>#define SD_EMERG "<0>" /* system is unusable */ #define SD_ALERT "<1>" /* action must be taken immediately */ #define SD_CRIT "<2>" /* critical conditions */ #define SD_ERR "<3>" /* error conditions */ @@ -95,53 +95,50 @@ #define SD_INFO "<6>" /* informational */ #define SD_DEBUG "<7>" /* debug-level messages */</programlisting> - <para>These prefixes are intended to be used in - conjunction with stderr-based logging as implemented - by systemd. If a systemd service definition file is - configured with - <varname>StandardError=journal</varname>, - <varname>StandardError=syslog</varname> or - <varname>StandardError=kmsg</varname>, these prefixes - can be used to encode a log level in lines - printed. This is similar to the kernel - <function>printk()</function>-style logging. See - <citerefentry><refentrytitle>klogctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for more information.</para> - - <para>The log levels are identical to - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s - log level system. To use these prefixes simply prefix - every line with one of these strings. A line that is - not prefixed will be logged at the default log level - SD_INFO.</para> - - <example> - <title>Hello World</title> - - <para>A daemon may log with the log level - NOTICE by issuing this call:</para> - - <programlisting>fprintf(stderr, SD_NOTICE "Hello World!\n");</programlisting> - </example> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <para>These prefixes are intended to be used in conjunction with + stderr-based logging as implemented by systemd. If a systemd + service definition file is configured with + <varname>StandardError=journal</varname>, + <varname>StandardError=syslog</varname> or + <varname>StandardError=kmsg</varname>, these prefixes can be used + to encode a log level in lines printed. This is similar to the + kernel <function>printk()</function>-style logging. See + <citerefentry><refentrytitle>klogctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information.</para> + + <para>The log levels are identical to + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s + log level system. To use these prefixes simply prefix every line + with one of these strings. A line that is not prefixed will be + logged at the default log level SD_INFO.</para> + + <example> + <title>Hello World</title> + + <para>A daemon may log with the log level NOTICE by issuing this + call:</para> + + <programlisting>fprintf(stderr, SD_NOTICE "Hello World!\n");</programlisting> + </example> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd-id128.xml b/man/sd-id128.xml index d9ebb9c680..ea7972055d 100644 --- a/man/sd-id128.xml +++ b/man/sd-id128.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,152 +22,145 @@ --> <refentry id="sd-id128" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd-id128</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd-id128</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd-id128</refname> - <refname>sd_id128_t</refname> - <refname>SD_ID128_MAKE</refname> - <refname>SD_ID128_CONST_STR</refname> - <refname>SD_ID128_FORMAT_STR</refname> - <refname>SD_ID128_FORMAT_VAL</refname> - <refname>sd_id128_equal</refname> - <refpurpose>APIs for processing 128-bit IDs</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> - </funcsynopsis> - - <cmdsynopsis> - <command>pkg-config --cflags --libs libsystemd</command> - </cmdsynopsis> - - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>sd-id128.h</filename> provides APIs to - process and generate 128-bit ID values. The 128-bit ID - values processed and generated by these APIs are a - generalization of OSF UUIDs as defined by <ulink - url="https://tools.ietf.org/html/rfc4122">RFC - 4122</ulink> but use a simpler string - format. These functions impose no structure on the - used IDs, much unlike OSF UUIDs or Microsoft GUIDs, - but are fully compatible with those types of IDs. - </para> - - <para>See - <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry> and - <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information about the implemented - functions.</para> - - <para>A 128-bit ID is implemented as the following - union type:</para> - - <programlisting>typedef union sd_id128 { - uint8_t bytes[16]; - uint64_t qwords[2]; + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd-id128</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-id128</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-id128</refname> + <refname>sd_id128_t</refname> + <refname>SD_ID128_MAKE</refname> + <refname>SD_ID128_CONST_STR</refname> + <refname>SD_ID128_FORMAT_STR</refname> + <refname>SD_ID128_FORMAT_VAL</refname> + <refname>sd_id128_equal</refname> + <refpurpose>APIs for processing 128-bit IDs</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libsystemd</command> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-id128.h</filename> provides APIs to process and + generate 128-bit ID values. The 128-bit ID values processed and + generated by these APIs are a generalization of OSF UUIDs as + defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC + 4122</ulink> but use a simpler string format. These functions + impose no structure on the used IDs, much unlike OSF UUIDs or + Microsoft GUIDs, but are fully compatible with those types of IDs. + </para> + + <para>See + <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the implemented functions.</para> + + <para>A 128-bit ID is implemented as the following + union type:</para> + + <programlisting>typedef union sd_id128 { + uint8_t bytes[16]; + uint64_t qwords[2]; } sd_id128_t;</programlisting> - <para>This union type allows accessing the 128-bit ID - as 16 separate bytes or two 64-bit words. It is generally - safer to access the ID components by their 8-bit array - to avoid endianness issues. This union is intended to - be passed call-by-value (as opposed to - call-by-reference) and may be directly manipulated by - clients.</para> - - <para>A couple of macros are defined to denote and - decode 128-bit IDs:</para> - - <para><function>SD_ID128_MAKE()</function> may be used - to denote a constant 128-bit ID in source code. A - commonly used idiom is to assign a name to a 128-bit - ID using this macro:</para> - - <programlisting>#define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1)</programlisting> - - <para><function>SD_ID128_CONST_STR()</function> may be - used to convert constant 128-bit IDs into constant - strings for output. The following example code will - output the string - "fc2e22bc6ee647b6b90729ab34a250b1":</para> - <programlisting>int main(int argc, char *argv[]) { - puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP)); + <para>This union type allows accessing the 128-bit ID as 16 + separate bytes or two 64-bit words. It is generally safer to + access the ID components by their 8-bit array to avoid endianness + issues. This union is intended to be passed call-by-value (as + opposed to call-by-reference) and may be directly manipulated by + clients.</para> + + <para>A couple of macros are defined to denote and decode 128-bit + IDs:</para> + + <para><function>SD_ID128_MAKE()</function> may be used to denote a + constant 128-bit ID in source code. A commonly used idiom is to + assign a name to a 128-bit ID using this macro:</para> + + <programlisting>#define SD_MESSAGE_COREDUMP SD_ID128_MAKE(fc,2e,22,bc,6e,e6,47,b6,b9,07,29,ab,34,a2,50,b1)</programlisting> + + <para><function>SD_ID128_CONST_STR()</function> may be used to + convert constant 128-bit IDs into constant strings for output. The + following example code will output the string + "fc2e22bc6ee647b6b90729ab34a250b1":</para> + <programlisting>int main(int argc, char *argv[]) { + puts(SD_ID128_CONST_STR(SD_MESSAGE_COREDUMP)); }</programlisting> - <para><function>SD_ID128_FORMAT_STR</function> and - <function>SD_ID128_FORMAT_VAL()</function> may be used - to format a 128-bit ID in a - <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> - format string, as shown in the following - example:</para> - - <programlisting>int main(int argc, char *argv[]) { - sd_id128_t id; - id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); - printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id)); - return 0; + <para><function>SD_ID128_FORMAT_STR</function> and + <function>SD_ID128_FORMAT_VAL()</function> may be used to format a + 128-bit ID in a + <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + format string, as shown in the following example:</para> + + <programlisting>int main(int argc, char *argv[]) { + sd_id128_t id; + id = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); + printf("The ID encoded in this C file is " SD_ID128_FORMAT_STR ".\n", SD_ID128_FORMAT_VAL(id)); + return 0; }</programlisting> - <para>Use <function>sd_id128_equal()</function> to compare two 128-bit IDs:</para> + <para>Use <function>sd_id128_equal()</function> to compare two 128-bit IDs:</para> - <programlisting>int main(int argc, char *argv[]) { - sd_id128_t a, b, c; - a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); - b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e); - c = a; - assert(sd_id128_equal(a, c)); - assert(!sd_id128_equal(a, b)); - return 0; + <programlisting>int main(int argc, char *argv[]) { + sd_id128_t a, b, c; + a = SD_ID128_MAKE(ee,89,be,71,bd,6e,43,d6,91,e6,c5,5d,eb,03,02,07); + b = SD_ID128_MAKE(f2,28,88,9c,5f,09,44,15,9d,d7,04,77,58,cb,e7,3e); + c = a; + assert(sd_id128_equal(a, c)); + assert(!sd_id128_equal(a, b)); + return 0; }</programlisting> - <para>Note that new, randomized IDs may be generated - with - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <option>--new-id</option> option.</para> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + <para>Note that new, randomized IDs may be generated with + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <option>--new-id</option> option.</para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_to_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd-journal.xml b/man/sd-journal.xml index edf7c32d6d..9b1a52207f 100644 --- a/man/sd-journal.xml +++ b/man/sd-journal.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,106 +22,104 @@ --> <refentry id="sd-journal" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd-journal</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd-journal</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd-journal</refname> - <refpurpose>APIs for submitting and querying log entries to and from the journal</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - </funcsynopsis> - - <cmdsynopsis> - <command>pkg-config --cflags --libs libsystemd</command> - </cmdsynopsis> - - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>sd-journal.h</filename> provides APIs - to submit and query log entries. The APIs exposed act - both as client for the - <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - journal service and as parser for the journal files - on disk. - </para> - - <para>See - <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cutoff_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_usage</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_catalog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information about the functions - implemented.</para> - - <para>Command line access for submitting entries to - the journal is available with the - <citerefentry><refentrytitle>systemd-cat</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool. Command line access for querying entries from - the journal is available with the - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool.</para> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cutoff_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_usage</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_catalog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd-journal</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-journal</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-journal</refname> + <refpurpose>APIs for submitting and querying log entries to and + from the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libsystemd</command> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-journal.h</filename> provides APIs to submit + and query log entries. The APIs exposed act both as client for the + <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + journal service and as parser for the journal files on disk. + </para> + + <para>See + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cutoff_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_usage</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_catalog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the functions implemented.</para> + + <para>Command line access for submitting entries to the journal is + available with the + <citerefentry><refentrytitle>systemd-cat</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool. Command line access for querying entries from the journal is + available with the + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool.</para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cutoff_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_usage</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_catalog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd-login.xml b/man/sd-login.xml index f21170db16..328f71164d 100644 --- a/man/sd-login.xml +++ b/man/sd-login.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,117 +22,114 @@ --> <refentry id="sd-login" conditional='HAVE_PAM' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd-login</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd-login</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd-login</refname> - <refpurpose>APIs for - tracking logins</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> - </funcsynopsis> - - <cmdsynopsis> - <command>pkg-config --cflags --libs libsystemd</command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>sd-login.h</filename> provides APIs to - introspect and monitor seat, login session and user - status information on the local system. </para> - - <para>See <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat - on Linux</ulink> for an introduction into multi-seat - support on Linux, the background for this set of APIs.</para> - - <para>Note that these APIs only allow purely passive access - and monitoring of seats, sessions and users. To - actively make changes to the seat configuration, - terminate login sessions, or switch session on a seat - you need to utilize the D-Bus API of - systemd-logind, instead.</para> - - <para>These functions synchronously access data in - <filename>/proc</filename>, - <filename>/sys/fs/cgroup</filename> and - <filename>/run</filename>. All of these are virtual - file systems, hence the runtime cost of the accesses - is relatively cheap.</para> - - <para>It is possible (and often a very good choice) to - mix calls to the synchronous interface of - <filename>sd-login.h</filename> with the asynchronous - D-Bus interface of systemd-logind. However, if this is - done you need to think a bit about possible races - since the stream of events from D-Bus and from - <filename>sd-login.h</filename> interfaces such as the - login monitor are asynchronous and not ordered against - each other.</para> - - <para>If the functions return string arrays, these are - generally <constant>NULL</constant> terminated and need to be freed by the - caller with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use, including the strings referenced - therein. Similarly, individual strings returned need to - be freed, as well.</para> - - <para>As a special exception, instead of an empty - string array <constant>NULL</constant> may be returned, which should be - treated equivalent to an empty string array.</para> - - <para>See - <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information about the functions - implemented.</para> - </refsect1> - - <xi:include href="libsystemd-pkgconfig.xml" /> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd-login</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-login</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-login</refname> + <refpurpose>APIs for + tracking logins</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libsystemd</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-login.h</filename> provides APIs to introspect + and monitor seat, login session and user status information on the + local system. </para> + + <para>See <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat + on Linux</ulink> for an introduction into multi-seat support on + Linux, the background for this set of APIs.</para> + + <para>Note that these APIs only allow purely passive access and + monitoring of seats, sessions and users. To actively make changes + to the seat configuration, terminate login sessions, or switch + session on a seat you need to utilize the D-Bus API of + systemd-logind, instead.</para> + + <para>These functions synchronously access data in + <filename>/proc</filename>, <filename>/sys/fs/cgroup</filename> + and <filename>/run</filename>. All of these are virtual file + systems, hence the runtime cost of the accesses is relatively + cheap.</para> + + <para>It is possible (and often a very good choice) to mix calls + to the synchronous interface of <filename>sd-login.h</filename> + with the asynchronous D-Bus interface of systemd-logind. However, + if this is done you need to think a bit about possible races since + the stream of events from D-Bus and from + <filename>sd-login.h</filename> interfaces such as the login + monitor are asynchronous and not ordered against each + other.</para> + + <para>If the functions return string arrays, these are generally + <constant>NULL</constant> terminated and need to be freed by the + caller with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use, including the strings referenced therein. + Similarly, individual strings returned need to be freed, as + well.</para> + + <para>As a special exception, instead of an empty string array + <constant>NULL</constant> may be returned, which should be treated + equivalent to an empty string array.</para> + + <para>See + <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the functions + implemented.</para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_booted.xml b/man/sd_booted.xml index 28c153a324..4dd674b8ea 100644 --- a/man/sd_booted.xml +++ b/man/sd_booted.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,76 +22,74 @@ --> <refentry id="sd_booted" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_booted</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_booted</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_booted</refname> - <refpurpose>Test whether the system is running the systemd init system</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_booted</function></funcdef> - <paramdef>void</paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para><function>sd_booted()</function> checks whether - the system was booted up using the systemd init system.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On failure, this call returns a negative - errno-style error code. If the system was booted up - with systemd as init system, this call returns a - positive return value, zero otherwise.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - - <para>Internally, this function checks whether the - directory <filename>/run/systemd/system/</filename> - exists. A simple check like this can also be - implemented trivially in shell or any other - language.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_booted</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_booted</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_booted</refname> + <refpurpose>Test whether the system is running the systemd init system</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_booted</function></funcdef> + <paramdef>void</paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para><function>sd_booted()</function> checks whether the system + was booted up using the systemd init system.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, this call returns a negative errno-style error + code. If the system was booted up with systemd as init system, + this call returns a positive return value, zero otherwise.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + + <para>Internally, this function checks whether the directory + <filename>/run/systemd/system/</filename> exists. A simple check + like this can also be implemented trivially in shell or any other + language.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_bus_message_get_cookie.xml b/man/sd_bus_message_get_cookie.xml index 3e3f9bd7be..02374d7508 100644 --- a/man/sd_bus_message_get_cookie.xml +++ b/man/sd_bus_message_get_cookie.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,130 +23,124 @@ <refentry id="sd_bus_message_get_cookie" conditional="ENABLE_KDBUS"> - <refentryinfo> - <title>sd_bus_message_get_cookie</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_message_get_cookie</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_message_get_cookie</refname> - <refname>sd_bus_message_get_reply_cookie</refname> - <refpurpose>Returns the transaction cookie of a message</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_bus_message_get_cookie</function></funcdef> - <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> - <paramdef>uint64_t *<parameter>cookie</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_message_get_reply_cookie</function></funcdef> - <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> - <paramdef>uint64_t *<parameter>cookie</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_bus_message_get_cookie()</function> returns - the transaction cookie of a message. The cookie - uniquely identifies a message within each bus peer, - but is not globally unique. It is assigned when a - message is sent.</para> - - <para><function>sd_bus_message_get_reply_cookie()</function> - returns the transaction cookie of the message the - specified message is a response to. When a reply - message is generated for a method call message, its - cookie is copied over into this field. Note that while - every message that is transferred is identified by a - cookie, only response messages carry a reply cookie - field.</para> - - <para>Both functions take a message object as first - parameter and a place to store the 64-bit cookie - in.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, these calls return 0 or a positive - integer. On failure, these calls return a negative - errno-style error code.</para> - - <para>On success, the cookie/reply cookie is returned - in the specified 64-bit unsigned integer variable.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>A specified parameter - is invalid.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENODATA</constant></term> - - <listitem><para>No cookie has been - assigned to this message. This either - indicates that the message has not - been sent yet and hence has no cookie - assigned, or that the message is not a - method response message and hence - carries a reply cookie - field.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_bus_message_get_cookie()</function> - and <function>sd_bus_message_get_reply_cookie()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_bus_message_get_cookie</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_get_cookie</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_get_cookie</refname> + <refname>sd_bus_message_get_reply_cookie</refname> + <refpurpose>Returns the transaction cookie of a message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_message_get_cookie</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>uint64_t *<parameter>cookie</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_message_get_reply_cookie</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>uint64_t *<parameter>cookie</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_get_cookie()</function> returns the + transaction cookie of a message. The cookie uniquely identifies a + message within each bus peer, but is not globally unique. It is + assigned when a message is sent.</para> + + <para><function>sd_bus_message_get_reply_cookie()</function> + returns the transaction cookie of the message the specified + message is a response to. When a reply message is generated for a + method call message, its cookie is copied over into this field. + Note that while every message that is transferred is identified by + a cookie, only response messages carry a reply cookie + field.</para> + + <para>Both functions take a message object as first parameter and + a place to store the 64-bit cookie in.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code.</para> + + <para>On success, the cookie/reply cookie is returned in the + specified 64-bit unsigned integer variable.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>A specified parameter + is invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>No cookie has been assigned to this message. + This either indicates that the message has not been sent yet + and hence has no cookie assigned, or that the message is not a + method response message and hence carries a reply cookie + field.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_bus_message_get_cookie()</function> and + <function>sd_bus_message_get_reply_cookie()</function> interfaces + are available as a shared library, which can be compiled and + linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_bus_message_get_monotonic_usec.xml b/man/sd_bus_message_get_monotonic_usec.xml index 290faf2a5b..42842116a0 100644 --- a/man/sd_bus_message_get_monotonic_usec.xml +++ b/man/sd_bus_message_get_monotonic_usec.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,168 +23,159 @@ <refentry id="sd_bus_message_get_monotonic_usec" conditional="ENABLE_KDBUS"> - <refentryinfo> - <title>sd_bus_message_get_monotonic_usec</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_message_get_monotonic_usec</refname> - <refname>sd_bus_message_get_realtime_usec</refname> - <refname>sd_bus_message_get_seqnum</refname> - <refpurpose>Retrieve the sender timestamps and sequence number of a message</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_bus_message_get_monotonic_usec</function></funcdef> - <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> - <paramdef>uint64_t *<parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_message_get_realtime_usec</function></funcdef> - <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> - <paramdef>uint64_t *<parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_message_get_seqnum</function></funcdef> - <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> - <paramdef>uint64_t *<parameter>seqnum</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_bus_message_get_monotonic_usec()</function> - returns the monotonic timestamp of the time the - message was sent. This value is in microseconds since - the <literal>CLOCK_MONOTONIC</literal> epoch, see - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details.</para> - - <para>Similar, - <function>sd_bus_message_get_realtime_usec()</function> - returns the realtime (wallclock) timestamp of the time - the message was sent. This value is in microseconds - since Jan 1st, 1970, i.e. in the - <literal>CLOCK_REALTIME</literal> clock.</para> - - <para><function>sd_bus_message_get_seqnum()</function> - returns the kernel-assigned sequence number of the - message. The kernel assigns a global, monotonically - increasing sequence number to all messages transmitted - on the local system, at the time the message was - sent. This sequence number is useful for determining - message send order, even across different busses of - the local system. The sequence number combined with - the boot ID of the system (as returned by - <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>) - is a suitable globally unique identifier for bus - messages.</para> - - <para>Note that the sending order and receiving order - of messages might differ, in particular for broadcast - messages. This means that the sequence number and the - timestamps of messages a client reads are not - necessarily monotonically increasing.</para> - - <para>These timestamps and the sequence number are - attached to each message by the kernel and cannot be - manipulated by the sender.</para> - - <para>Note that these timestamps are only available on - some bus transports, and only after support for them - has been negotiated with the - <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, these calls return 0 or a positive - integer. On failure, these calls return a negative - errno-style error code.</para> - - <para>On success, the timestamp or sequence number is - returned in the specified 64-bit unsigned integer - variable.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>A specified parameter - is invalid.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENODATA</constant></term> - - <listitem><para>No timestamp or - sequence number information is - attached to the passed message. This - error is returned if the underlying - transport does not support - timestamping or assigning of sequence - numbers, or if this feature has not - been negotiated with - <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The - <function>sd_bus_message_get_monotonic_usec()</function>, - <function>sd_bus_message_get_realtime_usec()</function>, - and <function>sd_bus_message_get_seqnum()</function> - interfaces are available as a shared library, which - can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_bus_message_get_monotonic_usec</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_get_monotonic_usec</refname> + <refname>sd_bus_message_get_realtime_usec</refname> + <refname>sd_bus_message_get_seqnum</refname> + <refpurpose>Retrieve the sender timestamps and sequence number of a message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_message_get_monotonic_usec</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_message_get_realtime_usec</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_message_get_seqnum</function></funcdef> + <paramdef>sd_bus_message *<parameter>message</parameter></paramdef> + <paramdef>uint64_t *<parameter>seqnum</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_get_monotonic_usec()</function> + returns the monotonic timestamp of the time the message was sent. + This value is in microseconds since the + <constant>CLOCK_MONOTONIC</constant> epoch, see + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para> + + <para>Similar, + <function>sd_bus_message_get_realtime_usec()</function> returns + the realtime (wallclock) timestamp of the time the message was + sent. This value is in microseconds since Jan 1st, 1970, i.e. in + the <constant>CLOCK_REALTIME</constant> clock.</para> + + <para><function>sd_bus_message_get_seqnum()</function> returns the + kernel-assigned sequence number of the message. The kernel assigns + a global, monotonically increasing sequence number to all messages + transmitted on the local system, at the time the message was sent. + This sequence number is useful for determining message send order, + even across different busses of the local system. The sequence + number combined with the boot ID of the system (as returned by + <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>) + is a suitable globally unique identifier for bus messages.</para> + + <para>Note that the sending order and receiving order of messages + might differ, in particular for broadcast messages. This means + that the sequence number and the timestamps of messages a client + reads are not necessarily monotonically increasing.</para> + + <para>These timestamps and the sequence number are attached to + each message by the kernel and cannot be manipulated by the + sender.</para> + + <para>Note that these timestamps are only available on some bus + transports, and only after support for them has been negotiated + with the + <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code.</para> + + <para>On success, the timestamp or sequence number is returned in + the specified 64-bit unsigned integer variable.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>A specified parameter is + invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>No timestamp or sequence number information is + attached to the passed message. This error is returned if the + underlying transport does not support timestamping or + assigning of sequence numbers, or if this feature has not been + negotiated with + <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The + <function>sd_bus_message_get_monotonic_usec()</function>, + <function>sd_bus_message_get_realtime_usec()</function>, and + <function>sd_bus_message_get_seqnum()</function> interfaces are + available as a shared library, which can be compiled and linked to + with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_bus_request_name.xml b/man/sd_bus_request_name.xml index ca082183cc..6aa132bb26 100644 --- a/man/sd_bus_request_name.xml +++ b/man/sd_bus_request_name.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,206 +23,188 @@ <refentry id="sd_bus_request_name" conditional="ENABLE_KDBUS"> - <refentryinfo> - <title>sd_bus_request_name</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_bus_request_name</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_bus_request_name</refname> - <refname>sd_bus_release_name</refname> - <refpurpose>Request or release a well-known name on a bus</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_bus_request_name</function></funcdef> - <paramdef>sd_bus *<parameter>bus</parameter></paramdef> - <paramdef>const char *<parameter>name</parameter></paramdef> - <paramdef>uint64_t <parameter>flags</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_bus_release_name</function></funcdef> - <paramdef>sd_bus *<parameter>bus</parameter></paramdef> - <paramdef>const char *<parameter>name</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_bus_request_name()</function> requests - a well-known name on a bus. It takes a bus connection, - a valid bus name and a flags parameter. The flags - parameter is a combination of the following - flags:</para> - - <variablelist> - <varlistentry> - <term><varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname></term> - - <listitem><para>After acquiring the - name successfully, permit other peers - to take over the name when they try to - acquire it with the - <varname>SD_BUS_NAME_REPLACE_EXISTING</varname> - flag set. If - <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> - is not set on the original request, - such a request by other peers will be - denied.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SD_BUS_NAME_REPLACE_EXISTING</varname></term> - - <listitem><para>Take over the name - if it is already acquired by another - peer, and that other peer has permitted - takeover by setting - <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> - while acquiring it.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SD_BUS_NAME_QUEUE</varname></term> - - <listitem><para>Queue the acquisition - of the name when the name is already - taken.</para></listitem> - </varlistentry> - </variablelist> - - <para><function>sd_bus_release_name()</function> releases - an acquired well-known name. It takes a bus connection - and a valid bus name as parameters.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, these calls return 0 or a positive - integer. On failure, these calls return a negative - errno-style error code.</para> - - <para>If <varname>SD_BUS_NAME_QUEUE</varname> is - specified, <function>sd_bus_request_name()</function> - will return 0 when the name is already taken by - another peer and the client has been added to the - queue for the name. In that case, the caller can - subscribe to <literal>NameOwnerChanged</literal> - signals to be notified when the name is successfully - acquired. <function>sd_bus_request_name()</function> - returns > 0 when the name has immediately been - acquired successfully.</para> - </refsect1> - - <refsect1> - <title>Errors</title> - - <para>Returned errors may indicate the following problems:</para> - - <variablelist> - <varlistentry> - <term><constant>-EALREADY</constant></term> - - <listitem><para>The caller already is - the owner of the specified - name.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EEXIST</constant></term> - - <listitem><para>The name has already - been acquired by a different peer, and - SD_BUS_NAME_REPLACE_EXISTING was not - specified or the other peer did not - specify SD_BUS_NAME_ALLOW_REPLACEMENT - while acquiring the - name.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ESRCH</constant></term> - - <listitem><para>It was attempted to - release a name that is currently not - registered on the - bus.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EADDRINUSE</constant></term> - - <listitem><para>It was attempted to - release a name that is owned by a - different peer on the - bus.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-EINVAL</constant></term> - - <listitem><para>A specified parameter - is invalid.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ENOTCONN</constant></term> - - <listitem><para>The bus connection has - been disconnected.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>-ECHILD</constant></term> - - <listitem><para>The bus connection has - been created in a different process - than the current one.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_bus_acquire_name()</function> - and <function>sd_bus_release_name()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_bus_request_name</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_request_name</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_request_name</refname> + <refname>sd_bus_release_name</refname> + <refpurpose>Request or release a well-known name on a bus</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_request_name</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>uint64_t <parameter>flags</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_release_name</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_request_name()</function> requests a + well-known name on a bus. It takes a bus connection, a valid bus + name and a flags parameter. The flags parameter is a combination + of the following flags:</para> + + <variablelist> + <varlistentry> + <term><varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname></term> + + <listitem><para>After acquiring the name successfully, permit + other peers to take over the name when they try to acquire it + with the <varname>SD_BUS_NAME_REPLACE_EXISTING</varname> flag + set. If <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> is + not set on the original request, such a request by other peers + will be denied.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SD_BUS_NAME_REPLACE_EXISTING</varname></term> + + <listitem><para>Take over the name if it is already acquired + by another peer, and that other peer has permitted takeover by + setting <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> while + acquiring it.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SD_BUS_NAME_QUEUE</varname></term> + + <listitem><para>Queue the acquisition of the name when the + name is already taken.</para></listitem> + </varlistentry> + </variablelist> + + <para><function>sd_bus_release_name()</function> releases an + acquired well-known name. It takes a bus connection and a valid + bus name as parameters.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code.</para> + + <para>If <varname>SD_BUS_NAME_QUEUE</varname> is specified, + <function>sd_bus_request_name()</function> will return 0 when the + name is already taken by another peer and the client has been + added to the queue for the name. In that case, the caller can + subscribe to <literal>NameOwnerChanged</literal> signals to be + notified when the name is successfully acquired. + <function>sd_bus_request_name()</function> returns > 0 when the + name has immediately been acquired successfully.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EALREADY</constant></term> + + <listitem><para>The caller already is the owner of the + specified name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EEXIST</constant></term> + + <listitem><para>The name has already been acquired by a + different peer, and SD_BUS_NAME_REPLACE_EXISTING was not + specified or the other peer did not specify + SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the + name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESRCH</constant></term> + + <listitem><para>It was attempted to release a name that is + currently not registered on the bus.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EADDRINUSE</constant></term> + + <listitem><para>It was attempted to release a name that is + owned by a different peer on the bus.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>A specified parameter is + invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOTCONN</constant></term> + + <listitem><para>The bus connection has been + disconnected.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection has been created in a + different process than the current one.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_bus_acquire_name()</function> and + <function>sd_bus_release_name()</function> interfaces are + available as a shared library, which can be compiled and linked to + with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml index 76527c3f6f..4390d36ebe 100644 --- a/man/sd_get_seats.xml +++ b/man/sd_get_seats.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,119 +23,119 @@ <refentry id="sd_get_seats" conditional='HAVE_PAM'> - <refentryinfo> - <title>sd_get_seats</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_get_seats</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_get_seats</refname> - <refname>sd_get_sessions</refname> - <refname>sd_get_uids</refname> - <refname>sd_get_machine_names</refname> - <refpurpose>Determine available seats, sessions, logged in users and virtual machines/containers</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_get_seats</function></funcdef> - <paramdef>char ***<parameter>seats</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_get_sessions</function></funcdef> - <paramdef>char ***<parameter>sessions</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_get_uids</function></funcdef> - <paramdef>uid_t **<parameter>users</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_get_machine_names</function></funcdef> - <paramdef>char ***<parameter>machines</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_get_seats()</function> may be used - to determine all currently available local - seats. Returns a <constant>NULL</constant> terminated array of seat - identifiers. The returned array and all strings it - references need to be freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use. Note that instead of an empty array - <constant>NULL</constant> may be returned and should be considered - equivalent to an empty array.</para> - - <para>Similarly, <function>sd_get_sessions()</function> may - be used to determine all current login sessions.</para> - - <para>Similarly, <function>sd_get_uids()</function> may - be used to determine all Unix users who currently have login sessions.</para> - - <para>Similarly, - <function>sd_get_machine_names()</function> may be - used to determine all current virtual machines and - containers on the system.</para> - - <para>Note that the returned lists are not sorted and in an undefined order.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_get_seats()</function>, - <function>sd_get_sessions()</function>, - <function>sd_get_uids()</function> and - <function>sd_get_machine_names()</function> return the - number of entries in the arrays. On failure, these - calls return a negative errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_get_seats()</function>, - <function>sd_get_sessions()</function>, - <function>sd_get_uids()</function> and - <function>sd_get_machine_names()</function> interfaces - are available as a shared library, which can be compiled - and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_get_seats</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_get_seats</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_get_seats</refname> + <refname>sd_get_sessions</refname> + <refname>sd_get_uids</refname> + <refname>sd_get_machine_names</refname> + <refpurpose>Determine available seats, sessions, logged in users and virtual machines/containers</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_get_seats</function></funcdef> + <paramdef>char ***<parameter>seats</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_get_sessions</function></funcdef> + <paramdef>char ***<parameter>sessions</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_get_uids</function></funcdef> + <paramdef>uid_t **<parameter>users</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_get_machine_names</function></funcdef> + <paramdef>char ***<parameter>machines</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_get_seats()</function> may be used to determine + all currently available local seats. Returns a + <constant>NULL</constant> terminated array of seat identifiers. + The returned array and all strings it references need to be freed + with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use. Note that instead of an empty array + <constant>NULL</constant> may be returned and should be considered + equivalent to an empty array.</para> + + <para>Similarly, <function>sd_get_sessions()</function> may be + used to determine all current login sessions.</para> + + <para>Similarly, <function>sd_get_uids()</function> may be used to + determine all Unix users who currently have login sessions.</para> + + <para>Similarly, <function>sd_get_machine_names()</function> may + be used to determine all current virtual machines and containers + on the system.</para> + + <para>Note that the returned lists are not sorted and in an + undefined order.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_get_seats()</function>, + <function>sd_get_sessions()</function>, + <function>sd_get_uids()</function> and + <function>sd_get_machine_names()</function> return the number of + entries in the arrays. On failure, these calls return a negative + errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_get_seats()</function>, + <function>sd_get_sessions()</function>, + <function>sd_get_uids()</function> and + <function>sd_get_machine_names()</function> interfaces are + available as a shared library, which can be compiled and linked to + with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml index b3bf529c38..2ad1f8f728 100644 --- a/man/sd_id128_get_machine.xml +++ b/man/sd_id128_get_machine.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,115 +23,107 @@ <refentry id="sd_id128_get_machine"> - <refentryinfo> - <title>sd_id128_get_machine</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_id128_get_machine</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_id128_get_machine</refname> - <refname>sd_id128_get_boot</refname> - <refpurpose>Retrieve 128-bit IDs</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_id128_get_machine</function></funcdef> - <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_id128_get_boot</function></funcdef> - <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_id128_get_machine()</function> - returns the machine ID of the executing host. This - reads and parses the - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - file. This function caches the machine ID internally - to make retrieving the machine ID a cheap - operation.</para> - - <para><function>sd_id128_get_boot()</function> returns - the boot ID of the executing kernel. This reads and - parses the - <filename>/proc/sys/kernel/random/boot_id</filename> - file exposed by the kernel. It is randomly generated - early at boot and is unique for every running kernel - instance. See - <citerefentry project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> - for more information. This function also internally - caches the returned ID to make this call a cheap - operation.</para> - - <para>Note that - <function>sd_id128_get_boot()</function> always returns - a UUID v4 compatible - ID. <function>sd_id128_get_machine()</function> will - also return a UUID v4-compatible ID on new - installations but might not on older. It is possible - to convert the machine ID into a UUID v4-compatible - one. For more information, see - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>For more information about the - <literal>sd_id128_t</literal> type see - <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>The two calls return 0 on success (in which - case <parameter>ret</parameter> is filled in), or a - negative errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_id128_get_machine()</function> - and <function>sd_id128_get_boot()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <literal>libsystemd</literal> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_id128_get_machine</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_id128_get_machine</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_id128_get_machine</refname> + <refname>sd_id128_get_boot</refname> + <refpurpose>Retrieve 128-bit IDs</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_id128_get_machine</function></funcdef> + <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_id128_get_boot</function></funcdef> + <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_id128_get_machine()</function> returns the + machine ID of the executing host. This reads and parses the + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + file. This function caches the machine ID internally to make + retrieving the machine ID a cheap operation.</para> + + <para><function>sd_id128_get_boot()</function> returns the boot ID + of the executing kernel. This reads and parses the + <filename>/proc/sys/kernel/random/boot_id</filename> file exposed + by the kernel. It is randomly generated early at boot and is + unique for every running kernel instance. See + <citerefentry project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> + for more information. This function also internally caches the + returned ID to make this call a cheap operation.</para> + + <para>Note that <function>sd_id128_get_boot()</function> always + returns a UUID v4 compatible ID. + <function>sd_id128_get_machine()</function> will also return a + UUID v4-compatible ID on new installations but might not on older. + It is possible to convert the machine ID into a UUID v4-compatible + one. For more information, see + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>For more information about the <literal>sd_id128_t</literal> + type see + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The two calls return 0 on success (in which case + <parameter>ret</parameter> is filled in), or a negative + errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_id128_get_machine()</function> and + <function>sd_id128_get_boot()</function> interfaces are available + as a shared library, which can be compiled and linked to with the + <literal>libsystemd</literal> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_id128_randomize.xml b/man/sd_id128_randomize.xml index 870474c63d..ab449d2937 100644 --- a/man/sd_id128_randomize.xml +++ b/man/sd_id128_randomize.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,94 +23,92 @@ <refentry id="sd_id128_randomize"> - <refentryinfo> - <title>sd_id128_randomize</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_id128_randomize</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_id128_randomize</refname> - <refpurpose>Generate 128-bit IDs</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_id128_randomize</function></funcdef> - <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_id128_randomize()</function> - generates a new randomized 128-bit ID and returns it - in <parameter>ret</parameter>. Every invocation - returns a new randomly generated ID. This uses the - <filename>/dev/urandom</filename> kernel random number - generator.</para> - - <para>Note that - <function>sd_id128_randomize()</function> always returns - a UUID v4-compatible ID.</para> - - <para>For more information about the - <literal>sd_id128_t</literal> type, see - <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <option>--new-id</option> option may be used as a - command line front-end for - <function>sd_id128_randomize()</function>.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>The call returns 0 on success (in which - case <parameter>ret</parameter> is filled in), or a - negative errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_id128_randomize()</function> interface - is available as a shared library, which can be compiled - and linked to with the - <literal>libsystemd</literal> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_id128_randomize</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_id128_randomize</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_id128_randomize</refname> + <refpurpose>Generate 128-bit IDs</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_id128_randomize</function></funcdef> + <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_id128_randomize()</function> generates a new + randomized 128-bit ID and returns it in + <parameter>ret</parameter>. Every invocation returns a new + randomly generated ID. This uses the + <filename>/dev/urandom</filename> kernel random number + generator.</para> + + <para>Note that <function>sd_id128_randomize()</function> always + returns a UUID v4-compatible ID.</para> + + <para>For more information about the <literal>sd_id128_t</literal> + type, see + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <option>--new-id</option> option may be used as a command line + front-end for <function>sd_id128_randomize()</function>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The call returns 0 on success (in which case + <parameter>ret</parameter> is filled in), or a negative + errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_id128_randomize()</function> interface is + available as a shared library, which can be compiled and linked to + with the + <literal>libsystemd</literal> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_id128_to_string.xml b/man/sd_id128_to_string.xml index 62badda8e2..e70c80892e 100644 --- a/man/sd_id128_to_string.xml +++ b/man/sd_id128_to_string.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,114 +23,110 @@ <refentry id="sd_id128_to_string"> - <refentryinfo> - <title>sd_id128_to_string</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_id128_to_string</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_id128_to_string</refname> - <refname>sd_id128_from_string</refname> - <refpurpose>Format or parse 128-bit IDs as strings</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>char *<function>sd_id128_to_string</function></funcdef> - <paramdef>sd_id128_t <parameter>id</parameter>, char <parameter>s</parameter>[33]</paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_id128_from_string</function></funcdef> - <paramdef>const char *<parameter>s</parameter>, sd_id128_t *<parameter>ret</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_id128_to_string()</function> - formats a 128-bit ID as a character string. It expects - the ID and a string array capable of storing 33 - characters. The ID will be formatted as 32 lowercase - hexadecimal digits and be terminated by a - <constant>NUL</constant> byte.</para> - - <para><function>sd_id128_from_string()</function> - implements the reverse operation: it takes a 33 - character string with 32 hexadecimal digits (either - lowercase or uppercase, terminated by - <constant>NUL</constant>) and parses them back into a - 128-bit ID returned in - <parameter>ret</parameter>. Alternatively, this call - can also parse a 37-character string with a 128-bit ID - formatted as RFC UUID.</para> - - <para>For more information about the - <literal>sd_id128_t</literal> type see - <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Note - that these calls operate the same way on all - architectures, i.e. the results do not depend on - endianness.</para> - - <para>When formatting a 128-bit ID into a string, it is - often easier to use a format string for - <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This - is easily done using the - <function>SD_ID128_FORMAT_STR</function> and - <function>SD_ID128_FORMAT_VAL()</function> macros. For - more information see - <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_id128_to_string()</function> always - succeeds and returns a pointer to the string array - passed in. <function>sd_id128_from_string</function> - returns 0 on success, in which case - <parameter>ret</parameter> is filled in, or a negative - errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_id128_to_string()</function> - and <function>sd_id128_from_string()</function> interfaces are - available as a shared library, which can be compiled and - linked to with the <literal>libsystemd</literal> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_id128_to_string</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_id128_to_string</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_id128_to_string</refname> + <refname>sd_id128_from_string</refname> + <refpurpose>Format or parse 128-bit IDs as strings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-id128.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>char *<function>sd_id128_to_string</function></funcdef> + <paramdef>sd_id128_t <parameter>id</parameter>, char <parameter>s</parameter>[33]</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_id128_from_string</function></funcdef> + <paramdef>const char *<parameter>s</parameter>, sd_id128_t *<parameter>ret</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_id128_to_string()</function> formats a 128-bit + ID as a character string. It expects the ID and a string array + capable of storing 33 characters. The ID will be formatted as 32 + lowercase hexadecimal digits and be terminated by a + <constant>NUL</constant> byte.</para> + + <para><function>sd_id128_from_string()</function> implements the + reverse operation: it takes a 33 character string with 32 + hexadecimal digits (either lowercase or uppercase, terminated by + <constant>NUL</constant>) and parses them back into a 128-bit ID + returned in <parameter>ret</parameter>. Alternatively, this call + can also parse a 37-character string with a 128-bit ID formatted + as RFC UUID.</para> + + <para>For more information about the <literal>sd_id128_t</literal> + type see + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Note that these calls operate the same way on all architectures, + i.e. the results do not depend on endianness.</para> + + <para>When formatting a 128-bit ID into a string, it is often + easier to use a format string for + <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This is easily done using the + <function>SD_ID128_FORMAT_STR</function> and + <function>SD_ID128_FORMAT_VAL()</function> macros. For more + information see + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_id128_to_string()</function> always succeeds + and returns a pointer to the string array passed in. + <function>sd_id128_from_string</function> returns 0 on success, in + which case <parameter>ret</parameter> is filled in, or a negative + errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_id128_to_string()</function> and + <function>sd_id128_from_string()</function> interfaces are + available as a shared library, which can be compiled and linked to + with the + <literal>libsystemd</literal> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_is_fifo.xml b/man/sd_is_fifo.xml index 17ecca8336..627cb87aaf 100644 --- a/man/sd_is_fifo.xml +++ b/man/sd_is_fifo.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,187 +22,179 @@ --> <refentry id="sd_is_fifo" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_is_fifo</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_is_fifo</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_is_fifo</refname> - <refname>sd_is_socket</refname> - <refname>sd_is_socket_inet</refname> - <refname>sd_is_socket_unix</refname> - <refname>sd_is_mq</refname> - <refname>sd_is_special</refname> - <refpurpose>Check the type of a file descriptor</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_is_fifo</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>const char *<parameter>path</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_is_socket</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>family</parameter></paramdef> - <paramdef>int <parameter>type</parameter></paramdef> - <paramdef>int <parameter>listening</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_is_socket_inet</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>family</parameter></paramdef> - <paramdef>int <parameter>type</parameter></paramdef> - <paramdef>int <parameter>listening</parameter></paramdef> - <paramdef>uint16_t <parameter>port</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_is_socket_unix</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>int <parameter>type</parameter></paramdef> - <paramdef>int <parameter>listening</parameter></paramdef> - <paramdef>const char *<parameter>path</parameter></paramdef> - <paramdef>size_t <parameter>length</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_is_mq</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>const char *<parameter>path</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_is_special</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>const char *<parameter>path</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_is_fifo()</function> may be called - to check whether the specified file descriptor refers - to a FIFO or pipe. If the <parameter>path</parameter> - parameter is not <constant>NULL</constant>, it is - checked whether the FIFO is bound to the specified - file system path.</para> - - <para><function>sd_is_socket()</function> may be - called to check whether the specified file descriptor - refers to a socket. If the - <parameter>family</parameter> parameter is not - <constant>AF_UNSPEC</constant>, it is checked whether - the socket is of the specified family (AF_UNIX, - <constant>AF_INET</constant>, ...). If the - <parameter>type</parameter> parameter is not 0, it is - checked whether the socket is of the specified type - (<constant>SOCK_STREAM</constant>, - <constant>SOCK_DGRAM</constant>, ...). If the - <parameter>listening</parameter> parameter is positive, - it is checked whether the socket is in accepting mode, - i.e. <function>listen()</function> has been called for - it. If <parameter>listening</parameter> is 0, it is - checked whether the socket is not in this mode. If the - parameter is negative, no such check is made. The - <parameter>listening</parameter> parameter should only - be used for stream sockets and should be set to a - negative value otherwise.</para> - - <para><function>sd_is_socket_inet()</function> is - similar to <function>sd_is_socket()</function>, but - optionally checks the IPv4 or IPv6 port number the - socket is bound to, unless <parameter>port</parameter> - is zero. For this call <parameter>family</parameter> - must be passed as either <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or - <constant>AF_INET6</constant>.</para> - - <para><function>sd_is_socket_unix()</function> is - similar to <function>sd_is_socket()</function> but - optionally checks the <constant>AF_UNIX</constant> path the socket is bound - to, unless the <parameter>path</parameter> parameter - is <constant>NULL</constant>. For normal file system <constant>AF_UNIX</constant> sockets, - set the <parameter>length</parameter> parameter to 0. For - Linux abstract namespace sockets, set the - <parameter>length</parameter> to the size of the - address, including the initial 0 byte, and set the - <parameter>path</parameter> to the initial 0 byte of - the socket address.</para> - - <para><function>sd_is_mq()</function> may be called to - check whether the specified file descriptor refers to - a POSIX message queue. If the - <parameter>path</parameter> parameter is not - <constant>NULL</constant>, it is checked whether the - message queue is bound to the specified name.</para> - - <para><function>sd_is_special()</function> may be - called to check whether the specified file descriptor - refers to a special file. If the - <parameter>path</parameter> parameter is not - <constant>NULL</constant>, it is checked whether the file - descriptor is bound to the specified file - name. Special files in this context are character - device nodes and files in <filename>/proc</filename> - or <filename>/sys</filename>.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On failure, these calls return a negative - errno-style error code. If the file descriptor is of - the specified type and bound to the specified address, - a positive return value is returned, otherwise - zero.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - - <para>Internally, these function use a combination of - <filename>fstat()</filename> and - <filename>getsockname()</filename> to check the file - descriptor type and where it is bound to.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_is_fifo</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_is_fifo</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_is_fifo</refname> + <refname>sd_is_socket</refname> + <refname>sd_is_socket_inet</refname> + <refname>sd_is_socket_unix</refname> + <refname>sd_is_mq</refname> + <refname>sd_is_special</refname> + <refpurpose>Check the type of a file descriptor</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_is_fifo</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_socket</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>family</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + <paramdef>int <parameter>listening</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_socket_inet</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>family</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + <paramdef>int <parameter>listening</parameter></paramdef> + <paramdef>uint16_t <parameter>port</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_socket_unix</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + <paramdef>int <parameter>listening</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + <paramdef>size_t <parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_mq</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_special</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_is_fifo()</function> may be called to check + whether the specified file descriptor refers to a FIFO or pipe. If + the <parameter>path</parameter> parameter is not + <constant>NULL</constant>, it is checked whether the FIFO is bound + to the specified file system path.</para> + + <para><function>sd_is_socket()</function> may be called to check + whether the specified file descriptor refers to a socket. If the + <parameter>family</parameter> parameter is not + <constant>AF_UNSPEC</constant>, it is checked whether the socket + is of the specified family (AF_UNIX, <constant>AF_INET</constant>, + ...). If the <parameter>type</parameter> parameter is not 0, it is + checked whether the socket is of the specified type + (<constant>SOCK_STREAM</constant>, + <constant>SOCK_DGRAM</constant>, ...). If the + <parameter>listening</parameter> parameter is positive, it is + checked whether the socket is in accepting mode, i.e. + <function>listen()</function> has been called for it. If + <parameter>listening</parameter> is 0, it is checked whether the + socket is not in this mode. If the parameter is negative, no such + check is made. The <parameter>listening</parameter> parameter + should only be used for stream sockets and should be set to a + negative value otherwise.</para> + + <para><function>sd_is_socket_inet()</function> is similar to + <function>sd_is_socket()</function>, but optionally checks the + IPv4 or IPv6 port number the socket is bound to, unless + <parameter>port</parameter> is zero. For this call + <parameter>family</parameter> must be passed as either + <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or + <constant>AF_INET6</constant>.</para> + + <para><function>sd_is_socket_unix()</function> is similar to + <function>sd_is_socket()</function> but optionally checks the + <constant>AF_UNIX</constant> path the socket is bound to, unless + the <parameter>path</parameter> parameter is + <constant>NULL</constant>. For normal file system + <constant>AF_UNIX</constant> sockets, set the + <parameter>length</parameter> parameter to 0. For Linux abstract + namespace sockets, set the <parameter>length</parameter> to the + size of the address, including the initial 0 byte, and set the + <parameter>path</parameter> to the initial 0 byte of the socket + address.</para> + + <para><function>sd_is_mq()</function> may be called to check + whether the specified file descriptor refers to a POSIX message + queue. If the <parameter>path</parameter> parameter is not + <constant>NULL</constant>, it is checked whether the message queue + is bound to the specified name.</para> + + <para><function>sd_is_special()</function> may be called to check + whether the specified file descriptor refers to a special file. If + the <parameter>path</parameter> parameter is not + <constant>NULL</constant>, it is checked whether the file + descriptor is bound to the specified file name. Special files in + this context are character device nodes and files in + <filename>/proc</filename> or <filename>/sys</filename>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, these calls return a negative errno-style error + code. If the file descriptor is of the specified type and bound to + the specified address, a positive return value is returned, + otherwise zero.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + + <para>Internally, these function use a combination of + <filename>fstat()</filename> and + <filename>getsockname()</filename> to check the file descriptor + type and where it is bound to.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml index 21a5ab1342..420f56356a 100644 --- a/man/sd_journal_add_match.xml +++ b/man/sd_journal_add_match.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,198 +23,186 @@ <refentry id="sd_journal_add_match"> - <refentryinfo> - <title>sd_journal_add_match</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_add_match</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_add_match</refname> - <refname>sd_journal_add_disjunction</refname> - <refname>sd_journal_add_conjunction</refname> - <refname>sd_journal_flush_matches</refname> - <refpurpose>Add or remove entry matches</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_add_match</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>const void *<parameter>data</parameter></paramdef> - <paramdef>size_t <parameter>size</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_add_disjunction</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_add_conjunction</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>void <function>sd_journal_flush_matches</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_add_match()</function> adds - a match by which to filter the entries of the journal - file. Matches applied with this call will filter what - can be iterated through and read from the journal file - via calls like - <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 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, only entries where the - field takes one of the specified values will be - iterated. Well known fields are documented in - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Whenever - a new match is added the current entry position is - reset, and - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> (or a similar call) - needs to be called before entries can be read - again.</para> - - <para><function>sd_journal_add_disjunction()</function> - may be used to insert a disjunction (i.e. logical OR) - in the match list. If this call is invoked, all - previously added matches since the last invocation of - <function>sd_journal_add_disjunction()</function> or - <function>sd_journal_add_conjunction()</function> are - combined in an OR with all matches added afterwards, - until - <function>sd_journal_add_disjunction()</function> or - <function>sd_journal_add_conjunction()</function> is - invoked again to begin the next OR or AND - term. </para> - - <para><function>sd_journal_add_conjunction()</function> - may be used to insert a conjunction (i.e. logical AND) - in the match list. If this call is invoked, all - previously added matches since the last invocation of - <function>sd_journal_add_conjunction()</function> are - combined in an AND with all matches added afterwards, - until - <function>sd_journal_add_conjunction()</function> is - invoked again to begin the next AND term. The - combination of - <function>sd_journal_add_match()</function>, - <function>sd_journal_add_disjunction()</function> and - <function>sd_journal_add_conjunction()</function> may - be used to build complex search terms, even though - full logical expressions are not available. Note that - <function>sd_journal_add_conjunction()</function> - operates one level 'higher' than - <function>sd_journal_add_disjunction()</function>. It - is hence possible to build an expression of AND terms, - consisting of OR terms, consisting of AND terms, - consisting of OR terms of matches (the latter OR - expression is implicitly created for matches with the - same field name, see above).</para> - - <para><function>sd_journal_flush_matches()</function> - may be used to flush all matches, disjunction and - conjunction terms again. After this call all filtering - is removed and all entries in the journal will be - iterated again.</para> - - <para>Note that filtering via matches only applies to - the way the journal is read, it has no effect on storage - on disk.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_journal_add_match()</function>, - <function>sd_journal_add_disjunction()</function> and - <function>sd_journal_add_conjunction()</function> - return 0 on success or a negative errno-style error - code. <function>sd_journal_flush_matches()</function> - returns nothing.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_add_match()</function>, - <function>sd_journal_add_disjunction()</function>, - <function>sd_journal_add_conjunction()</function> and - <function>sd_journal_flush_matches()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>The following example adds matches to a journal - context object to iterate only through messages - generated by the Avahi service at the four error log - levels, plus all messages of the message ID - 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any - service (this example lacks the necessary error - checking):</para> - - <programlisting>... + <refentryinfo> + <title>sd_journal_add_match</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_add_match</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_add_match</refname> + <refname>sd_journal_add_disjunction</refname> + <refname>sd_journal_add_conjunction</refname> + <refname>sd_journal_flush_matches</refname> + <refpurpose>Add or remove entry matches</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_add_match</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const void *<parameter>data</parameter></paramdef> + <paramdef>size_t <parameter>size</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_add_disjunction</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_add_conjunction</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_journal_flush_matches</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_add_match()</function> adds a match by + which to filter the entries of the journal file. Matches applied + with this call will filter what can be iterated through and read + from the journal file via calls like + <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 + 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, + only entries where the field takes one of the specified values + will be iterated. Well known fields are documented in + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + Whenever a new match is added the current entry position is reset, + and + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + (or a similar call) needs to be called before entries can be read + again.</para> + + <para><function>sd_journal_add_disjunction()</function> may be + used to insert a disjunction (i.e. logical OR) in the match list. + If this call is invoked, all previously added matches since the + last invocation of + <function>sd_journal_add_disjunction()</function> or + <function>sd_journal_add_conjunction()</function> are combined in + an OR with all matches added afterwards, until + <function>sd_journal_add_disjunction()</function> or + <function>sd_journal_add_conjunction()</function> is invoked again + to begin the next OR or AND term. </para> + + <para><function>sd_journal_add_conjunction()</function> may be + used to insert a conjunction (i.e. logical AND) in the match list. + If this call is invoked, all previously added matches since the + last invocation of + <function>sd_journal_add_conjunction()</function> are combined in + an AND with all matches added afterwards, until + <function>sd_journal_add_conjunction()</function> is invoked again + to begin the next AND term. The combination of + <function>sd_journal_add_match()</function>, + <function>sd_journal_add_disjunction()</function> and + <function>sd_journal_add_conjunction()</function> may be used to + build complex search terms, even though full logical expressions + are not available. Note that + <function>sd_journal_add_conjunction()</function> operates one + level 'higher' than + <function>sd_journal_add_disjunction()</function>. It is hence + possible to build an expression of AND terms, consisting of OR + terms, consisting of AND terms, consisting of OR terms of matches + (the latter OR expression is implicitly created for matches with + the same field name, see above).</para> + + <para><function>sd_journal_flush_matches()</function> may be used + to flush all matches, disjunction and conjunction terms again. + After this call all filtering is removed and all entries in the + journal will be iterated again.</para> + + <para>Note that filtering via matches only applies to the way the + journal is read, it has no effect on storage on disk.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_add_match()</function>, + <function>sd_journal_add_disjunction()</function> and + <function>sd_journal_add_conjunction()</function> + return 0 on success or a negative errno-style error + code. <function>sd_journal_flush_matches()</function> + returns nothing.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_add_match()</function>, + <function>sd_journal_add_disjunction()</function>, + <function>sd_journal_add_conjunction()</function> and + <function>sd_journal_flush_matches()</function> + interfaces are available as a shared library, which can + be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>The following example adds matches to a journal context + object to iterate only through messages generated by the Avahi + service at the four error log levels, plus all messages of the + message ID 03bb1dab98ab4ecfbf6fff2738bdd964 coming from any + service (this example lacks the necessary error checking):</para> + + <programlisting>... int add_matches(sd_journal *j) { - sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0); - sd_journal_add_match(j, "PRIORITY=0", 0); - sd_journal_add_match(j, "PRIORITY=1", 0); - sd_journal_add_match(j, "PRIORITY=2", 0); - sd_journal_add_match(j, "PRIORITY=3", 0); - sd_journal_add_disjunction(j); - sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0); + sd_journal_add_match(j, "_SYSTEMD_UNIT=avahi-daemon.service", 0); + sd_journal_add_match(j, "PRIORITY=0", 0); + sd_journal_add_match(j, "PRIORITY=1", 0); + sd_journal_add_match(j, "PRIORITY=2", 0); + sd_journal_add_match(j, "PRIORITY=3", 0); + sd_journal_add_disjunction(j); + sd_journal_add_match(j, "MESSAGE_ID=03bb1dab98ab4ecfbf6fff2738bdd964", 0); }</programlisting> - </refsect1> + </refsect1> - <refsect1> - <title>See Also</title> + <refsect1> + <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_get_catalog.xml b/man/sd_journal_get_catalog.xml index c38a645ede..1dcbadd186 100644 --- a/man/sd_journal_get_catalog.xml +++ b/man/sd_journal_get_catalog.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,119 +23,115 @@ <refentry id="sd_journal_get_catalog"> - <refentryinfo> - <title>sd_journal_get_catalog</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_get_catalog</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_get_catalog</refname> - <refname>sd_journal_get_catalog_for_message_id</refname> - <refpurpose>Retrieve message catalog entry</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_get_catalog</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>char **<parameter>ret</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_get_catalog_for_message_id</function></funcdef> - <paramdef>sd_id128_t <parameter>id</parameter></paramdef> - <paramdef>char **<parameter>ret</parameter></paramdef> - </funcprototype> - - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_get_catalog()</function> - retrieves a message catalog entry for the current - journal entry. This will look up an entry in the - message catalog by using the - <literal>MESSAGE_ID=</literal> field of the current - journal entry. Before returning the entry all journal - field names in the catalog entry text enclosed in "@" - will be replaced by the respective field values of the - current entry. If a field name referenced in the - message catalog entry does not exist, in the current - journal entry, the "@" will be removed, but the field - name otherwise left untouched.</para> - - <para><function>sd_journal_get_catalog_for_message_id()</function> - works similar to - <function>sd_journal_get_catalog()</function> but the - entry is looked up by the specified message ID (no - open journal context is necessary for this), and no - field substitution is performed.</para> - - <para>For more information about the journal message - catalog please refer to the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/catalog">Journal - Message Catalogs</ulink> documentation page.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_journal_get_catalog()</function> - and - <function>sd_journal_get_catalog_for_message_id()</function> - return 0 on success or a negative errno-style error - code. If no matching message catalog entry is found, - -ENOENT is returned.</para> - - <para>On successful return, <parameter>ret</parameter> - points to a new string, which must be freed with - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - </para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_get_catalog()</function> and - <function>sd_journal_get_catalog_for_message_id()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_journal_get_catalog</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_get_catalog</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_catalog</refname> + <refname>sd_journal_get_catalog_for_message_id</refname> + <refpurpose>Retrieve message catalog entry</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_catalog</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>char **<parameter>ret</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_get_catalog_for_message_id</function></funcdef> + <paramdef>sd_id128_t <parameter>id</parameter></paramdef> + <paramdef>char **<parameter>ret</parameter></paramdef> + </funcprototype> + + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_catalog()</function> retrieves a + message catalog entry for the current journal entry. This will + look up an entry in the message catalog by using the + <literal>MESSAGE_ID=</literal> field of the current journal entry. + Before returning the entry all journal field names in the catalog + entry text enclosed in "@" will be replaced by the respective + field values of the current entry. If a field name referenced in + the message catalog entry does not exist, in the current journal + entry, the "@" will be removed, but the field name otherwise left + untouched.</para> + + <para><function>sd_journal_get_catalog_for_message_id()</function> + works similar to <function>sd_journal_get_catalog()</function> but + the entry is looked up by the specified message ID (no open + journal context is necessary for this), and no field substitution + is performed.</para> + + <para>For more information about the journal message catalog + please refer to the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/catalog">Journal + Message Catalogs</ulink> documentation page.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_catalog()</function> and + <function>sd_journal_get_catalog_for_message_id()</function> + return 0 on success or a negative errno-style error code. If no + matching message catalog entry is found, -ENOENT is + returned.</para> + + <para>On successful return, <parameter>ret</parameter> points to a + new string, which must be freed with + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_get_catalog()</function> and + <function>sd_journal_get_catalog_for_message_id()</function> + interfaces are available as a shared library, which can be + compiled and linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml index 3f5483bbda..2b7f443f29 100644 --- a/man/sd_journal_get_cursor.xml +++ b/man/sd_journal_get_cursor.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,128 +23,122 @@ <refentry id="sd_journal_get_cursor"> - <refentryinfo> - <title>sd_journal_get_cursor</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_get_cursor</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_get_cursor</refname> - <refname>sd_journal_test_cursor</refname> - <refpurpose>Get cursor string for or test cursor string against the current journal entry</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_get_cursor</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>char **<parameter>cursor</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_test_cursor</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>const char *<parameter>cursor</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_get_cursor()</function> - returns a cursor string for the current journal - entry. A cursor is a serialization of the current - journal position formatted as text. The string only - contains printable characters and can be passed around - in text form. The cursor identifies a journal entry - globally and in a stable way and may be used to later - seek to it via - <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The - cursor string should be considered opaque and not be - parsed by clients. Seeking to a cursor position - without the specific entry being available locally - will seek to the next closest (in terms of time) - available entry. The call takes two arguments: a - journal context object and a pointer to a string - pointer where the cursor string will be placed. The - string is allocated via libc - <citerefentry><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and should be freed after use with - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>Note that - <function>sd_journal_get_cursor()</function> will not - work before - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> - (or related call) has been called at least once, in - order to position the read pointer at a valid - entry.</para> - - <para><function>sd_journal_test_cursor()</function> - may be used to check whether the current position in - the journal matches the specified cursor. This is - useful since cursor strings do not uniquely identify - an entry: the same entry might be referred to by - multiple different cursor strings, and hence string - comparing cursors is not possible. Use this call to - verify after an invocation of - <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry> - whether the entry being sought to was actually found - in the journal or the next closest entry was used - instead.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_journal_get_cursor()</function> - returns 0 on success or a negative errno-style error - code. <function>sd_journal_test_cursor()</function> - returns positive if the current entry matches the - specified cursor, 0 if it does not match the specified - cursor or a negative errno-style error code on - failure.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_get_cursor()</function> - and <function>sd_journal_test_cursor()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_journal_get_cursor</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_get_cursor</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_cursor</refname> + <refname>sd_journal_test_cursor</refname> + <refpurpose>Get cursor string for or test cursor string against the current journal entry</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_cursor</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>char **<parameter>cursor</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_test_cursor</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const char *<parameter>cursor</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_cursor()</function> returns a + cursor string for the current journal entry. A cursor is a + serialization of the current journal position formatted as text. + The string only contains printable characters and can be passed + around in text form. The cursor identifies a journal entry + globally and in a stable way and may be used to later seek to it + via + <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + The cursor string should be considered opaque and not be parsed by + clients. Seeking to a cursor position without the specific entry + being available locally will seek to the next closest (in terms of + time) available entry. The call takes two arguments: a journal + context object and a pointer to a string pointer where the cursor + string will be placed. The string is allocated via libc + <citerefentry><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and should be freed after use with + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>Note that <function>sd_journal_get_cursor()</function> will + not work before + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + (or related call) has been called at least once, in order to + position the read pointer at a valid entry.</para> + + <para><function>sd_journal_test_cursor()</function> + may be used to check whether the current position in + the journal matches the specified cursor. This is + useful since cursor strings do not uniquely identify + an entry: the same entry might be referred to by + multiple different cursor strings, and hence string + comparing cursors is not possible. Use this call to + verify after an invocation of + <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry> + whether the entry being sought to was actually found + in the journal or the next closest entry was used + instead.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_cursor()</function> returns 0 on + success or a negative errno-style error code. + <function>sd_journal_test_cursor()</function> returns positive if + the current entry matches the specified cursor, 0 if it does not + match the specified cursor or a negative errno-style error code on + failure.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_get_cursor()</function> and + <function>sd_journal_test_cursor()</function> interfaces are + available as a shared library, which can be compiled and linked to + with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_get_cutoff_realtime_usec.xml b/man/sd_journal_get_cutoff_realtime_usec.xml index 673cff4591..23e7cc65e8 100644 --- a/man/sd_journal_get_cutoff_realtime_usec.xml +++ b/man/sd_journal_get_cutoff_realtime_usec.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,132 +23,123 @@ <refentry id="sd_journal_get_cutoff_realtime_usec"> - <refentryinfo> - <title>sd_journal_get_cutoff_realtime_usec</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_get_cutoff_realtime_usec</refname> - <refname>sd_journal_get_cutoff_monotonic_usec</refname> - <refpurpose>Read cut-off timestamps from the current journal entry</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_get_cutoff_realtime_usec</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>uint64_t *<parameter>from</parameter></paramdef> - <paramdef>uint64_t *<parameter>to</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_get_cutoff_monotonic_usec</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>sd_id128_t <parameter>boot_id</parameter></paramdef> - <paramdef>uint64_t *<parameter>from</parameter></paramdef> - <paramdef>uint64_t *<parameter>to</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_get_cutoff_realtime_usec()</function> - retrieves the realtime (wallclock) timestamps of the - first and last entries accessible in the journal. It - takes three arguments: the journal context object - <parameter>j</parameter> and two pointers - <parameter>from</parameter> and - <parameter>to</parameter> pointing at 64-bit unsigned - integers to store the timestamps in. The timestamps - are in microseconds since the epoch, - i.e. <constant>CLOCK_REALTIME</constant>. Either one - of the two timestamp arguments may be passed as - <constant>NULL</constant> in case the timestamp is not - needed, but not both.</para> - - <para><function>sd_journal_get_cutoff_monotonic_usec()</function> - retrieves the monotonic timestamps of the first and - last entries accessible in the journal. It takes three - arguments: the journal context object - <parameter>j</parameter>, a 128-bit identifier for the - boot <parameter>boot_id</parameter>, and two pointers - to 64-bit unsigned integers to store the timestamps, - <parameter>from</parameter> and - <parameter>to</parameter>. The timestamps are in - microseconds since boot-up of the specific boot, - i.e. <constant>CLOCK_MONOTONIC</constant>. Since the - monotonic clock begins new with every reboot it only - defines a well-defined point in time when used - together with an identifier identifying the boot, see - <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information. The function will return the - timestamps for the boot identified by the passed boot - ID. Either one of the two timestamp arguments may be - passed as <constant>NULL</constant> in case the - timestamp is not needed, but not both.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_journal_get_cutoff_realtime_usec()</function> - and - <function>sd_journal_get_cutoff_monotonic_usec()</function> - return 1 on success, 0 if not suitable entries are in - the journal or a negative errno-style error code.</para> - - <para>Locations pointed to by parameters - <parameter>from</parameter> and - <parameter>to</parameter> will be set only if the - return value is positive, and obviously, the - parameters are non-null.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The - <function>sd_journal_get_cutoff_realtime_usec()</function> - and - <function>sd_journal_get_cutoff_monotonic_usec()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_journal_get_cutoff_realtime_usec</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_cutoff_realtime_usec</refname> + <refname>sd_journal_get_cutoff_monotonic_usec</refname> + <refpurpose>Read cut-off timestamps from the current journal entry</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_cutoff_realtime_usec</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>uint64_t *<parameter>from</parameter></paramdef> + <paramdef>uint64_t *<parameter>to</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_get_cutoff_monotonic_usec</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>sd_id128_t <parameter>boot_id</parameter></paramdef> + <paramdef>uint64_t *<parameter>from</parameter></paramdef> + <paramdef>uint64_t *<parameter>to</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_cutoff_realtime_usec()</function> + retrieves the realtime (wallclock) timestamps of the first and + last entries accessible in the journal. It takes three arguments: + the journal context object <parameter>j</parameter> and two + pointers <parameter>from</parameter> and <parameter>to</parameter> + pointing at 64-bit unsigned integers to store the timestamps in. + The timestamps are in microseconds since the epoch, i.e. + <constant>CLOCK_REALTIME</constant>. Either one of the two + timestamp arguments may be passed as <constant>NULL</constant> in + case the timestamp is not needed, but not both.</para> + + <para><function>sd_journal_get_cutoff_monotonic_usec()</function> + retrieves the monotonic timestamps of the first and last entries + accessible in the journal. It takes three arguments: the journal + context object <parameter>j</parameter>, a 128-bit identifier for + the boot <parameter>boot_id</parameter>, and two pointers to + 64-bit unsigned integers to store the timestamps, + <parameter>from</parameter> and <parameter>to</parameter>. The + timestamps are in microseconds since boot-up of the specific boot, + i.e. <constant>CLOCK_MONOTONIC</constant>. Since the monotonic + clock begins new with every reboot it only defines a well-defined + point in time when used together with an identifier identifying + the boot, see + <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information. The function will return the timestamps for + the boot identified by the passed boot ID. Either one of the two + timestamp arguments may be passed as <constant>NULL</constant> in + case the timestamp is not needed, but not both.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_cutoff_realtime_usec()</function> + and <function>sd_journal_get_cutoff_monotonic_usec()</function> + return 1 on success, 0 if not suitable entries are in the journal + or a negative errno-style error code.</para> + + <para>Locations pointed to by parameters + <parameter>from</parameter> and <parameter>to</parameter> will be + set only if the return value is positive, and obviously, the + parameters are non-null.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The + <function>sd_journal_get_cutoff_realtime_usec()</function> and + <function>sd_journal_get_cutoff_monotonic_usec()</function> + interfaces are available as a shared library, which can be + compiled and linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml index 19fbcd35c0..1afbd7371c 100644 --- a/man/sd_journal_get_data.xml +++ b/man/sd_journal_get_data.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,228 +23,213 @@ <refentry id="sd_journal_get_data"> - <refentryinfo> - <title>sd_journal_get_data</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_get_data</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_get_data</refname> - <refname>sd_journal_enumerate_data</refname> - <refname>sd_journal_restart_data</refname> - <refname>SD_JOURNAL_FOREACH_DATA</refname> - <refname>sd_journal_set_data_threshold</refname> - <refname>sd_journal_get_data_threshold</refname> - <refpurpose>Read data fields from the current journal entry</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_get_data</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>const char *<parameter>field</parameter></paramdef> - <paramdef>const void **<parameter>data</parameter></paramdef> - <paramdef>size_t *<parameter>length</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_enumerate_data</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>const void **<parameter>data</parameter></paramdef> - <paramdef>size_t *<parameter>length</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>void <function>sd_journal_restart_data</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef><function>SD_JOURNAL_FOREACH_DATA</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>const void *<parameter>data</parameter></paramdef> - <paramdef>size_t <parameter>length</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_set_data_threshold</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>size_t <parameter>sz</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_get_data_threshold</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>size_t *<parameter>sz</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_get_data()</function> gets - the data object associated with a specific field from - the current journal entry. It takes four arguments: - the journal context object, a string with the field - name to request, plus a pair of pointers to - pointer/size variables where the data object and its - size shall be stored in. The field name should be an - entry field name. Well-known field names are listed in - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The - returned data is in a read-only memory map and is only - valid until the next invocation of - <function>sd_journal_get_data()</function> or - <function>sd_journal_enumerate_data()</function>, or - the read pointer is altered. Note that the data - returned will be prefixed with the field name and - '='. Also note that by default data fields larger than - 64K might get truncated to 64K. This threshold may be - changed and turned off with - <function>sd_journal_set_data_threshold()</function> (see - below).</para> - - <para><function>sd_journal_enumerate_data()</function> - may be used to iterate through all fields of the - current entry. On each invocation the data for the - next field is returned. The order of these fields is - not defined. The data returned is in the same format - as with <function>sd_journal_get_data()</function> and - also follows the same life-time semantics.</para> - - <para><function>sd_journal_restart_data()</function> - resets the data enumeration index to the beginning of - the entry. The next invocation of - <function>sd_journal_enumerate_data()</function> will return the first - field of the entry again.</para> - - <para>Note that the - <function>SD_JOURNAL_FOREACH_DATA()</function> macro - may be used as a handy wrapper around - <function>sd_journal_restart_data()</function> and - <function>sd_journal_enumerate_data()</function>.</para> - - <para>Note that these functions will not work before - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> - (or related call) has been called at least - once, in order to position the read pointer at a valid entry.</para> - - <para><function>sd_journal_set_data_threshold()</function> - may be used to change the data field size threshold - for data returned by - <function>sd_journal_get_data()</function>, - <function>sd_journal_enumerate_data()</function> and - <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. 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 threshold defaults to 64K - by default. To retrieve the complete data fields this - threshold should be turned off by setting it to 0, so - that the library always returns the complete data - objects. It is recommended to set this threshold as - low as possible since this relieves the library from - having to decompress large compressed data objects in - full.</para> - - <para><function>sd_journal_get_data_threshold()</function> - returns the currently configured data field size - threshold.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_journal_get_data()</function> - returns 0 on success or a negative errno-style error - code. If the current entry does not include the - specified field, -ENOENT is returned. If - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> - has not been called at least once, -EADDRNOTAVAIL is - returned. <function>sd_journal_enumerate_data()</function> - returns a positive integer if the next field has been - read, 0 when no more fields are known, or a negative - errno-style error - code. <function>sd_journal_restart_data()</function> - returns - nothing. <function>sd_journal_set_data_threshold()</function> - and <function>sd_journal_get_threshold()</function> - return 0 on success or a negative errno-style error - code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_get_data()</function>, - <function>sd_journal_enumerate_data()</function>, - <function>sd_journal_restart_data()</function>, - <function>sd_journal_set_data_threshold()</function> - and - <function>sd_journal_get_data_threshold()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>See - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for a complete example how to use - <function>sd_journal_get_data()</function>.</para> - - <para>Use the - <function>SD_JOURNAL_FOREACH_DATA</function> macro to - iterate through all fields of the current journal - entry:</para> - - <programlisting>... + <refentryinfo> + <title>sd_journal_get_data</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_get_data</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_data</refname> + <refname>sd_journal_enumerate_data</refname> + <refname>sd_journal_restart_data</refname> + <refname>SD_JOURNAL_FOREACH_DATA</refname> + <refname>sd_journal_set_data_threshold</refname> + <refname>sd_journal_get_data_threshold</refname> + <refpurpose>Read data fields from the current journal entry</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_data</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const char *<parameter>field</parameter></paramdef> + <paramdef>const void **<parameter>data</parameter></paramdef> + <paramdef>size_t *<parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_enumerate_data</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const void **<parameter>data</parameter></paramdef> + <paramdef>size_t *<parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_journal_restart_data</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef><function>SD_JOURNAL_FOREACH_DATA</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const void *<parameter>data</parameter></paramdef> + <paramdef>size_t <parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_set_data_threshold</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>size_t <parameter>sz</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_get_data_threshold</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>size_t *<parameter>sz</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_data()</function> gets the data + object associated with a specific field from the current journal + entry. It takes four arguments: the journal context object, a + string with the field name to request, plus a pair of pointers to + pointer/size variables where the data object and its size shall be + stored in. The field name should be an entry field name. + Well-known field names are listed in + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + The returned data is in a read-only memory map and is only valid + until the next invocation of + <function>sd_journal_get_data()</function> or + <function>sd_journal_enumerate_data()</function>, or the read + pointer is altered. Note that the data returned will be prefixed + with the field name and '='. Also note that by default data fields + larger than 64K might get truncated to 64K. This threshold may be + changed and turned off with + <function>sd_journal_set_data_threshold()</function> (see + below).</para> + + <para><function>sd_journal_enumerate_data()</function> may be used + to iterate through all fields of the current entry. On each + invocation the data for the next field is returned. The order of + these fields is not defined. The data returned is in the same + format as with <function>sd_journal_get_data()</function> and also + follows the same life-time semantics.</para> + + <para><function>sd_journal_restart_data()</function> resets the + data enumeration index to the beginning of the entry. The next + invocation of <function>sd_journal_enumerate_data()</function> + will return the first field of the entry again.</para> + + <para>Note that the <function>SD_JOURNAL_FOREACH_DATA()</function> + macro may be used as a handy wrapper around + <function>sd_journal_restart_data()</function> and + <function>sd_journal_enumerate_data()</function>.</para> + + <para>Note that these functions will not work before + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + (or related call) has been called at least once, in order to + position the read pointer at a valid entry.</para> + + <para><function>sd_journal_set_data_threshold()</function> may be + used to change the data field size threshold for data returned by + <function>sd_journal_get_data()</function>, + <function>sd_journal_enumerate_data()</function> and + <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. + 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 + threshold defaults to 64K by default. To retrieve the complete + data fields this threshold should be turned off by setting it to + 0, so that the library always returns the complete data objects. + It is recommended to set this threshold as low as possible since + this relieves the library from having to decompress large + compressed data objects in full.</para> + + <para><function>sd_journal_get_data_threshold()</function> returns + the currently configured data field size threshold.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_data()</function> returns 0 on + success or a negative errno-style error code. If the current entry + does not include the specified field, -ENOENT is returned. If + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + has not been called at least once, -EADDRNOTAVAIL is returned. + <function>sd_journal_enumerate_data()</function> returns a + positive integer if the next field has been read, 0 when no more + fields are known, or a negative errno-style error code. + <function>sd_journal_restart_data()</function> returns nothing. + <function>sd_journal_set_data_threshold()</function> and + <function>sd_journal_get_threshold()</function> return 0 on + success or a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_get_data()</function>, + <function>sd_journal_enumerate_data()</function>, + <function>sd_journal_restart_data()</function>, + <function>sd_journal_set_data_threshold()</function> and + <function>sd_journal_get_data_threshold()</function> interfaces + are available as a shared library, which can be compiled and + linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>See + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for a complete example how to use + <function>sd_journal_get_data()</function>.</para> + + <para>Use the + <function>SD_JOURNAL_FOREACH_DATA</function> macro to + iterate through all fields of the current journal + entry:</para> + + <programlisting>... int print_fields(sd_journal *j) { - const void *data; - size_t length; - SD_JOURNAL_FOREACH_DATA(j, data, length) - printf("%.*s\n", (int) length, data); + const void *data; + size_t length; + SD_JOURNAL_FOREACH_DATA(j, data, length) + printf("%.*s\n", (int) length, data); } ...</programlisting> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml index 3aa79ce100..aaf53b93c7 100644 --- a/man/sd_journal_get_fd.xml +++ b/man/sd_journal_get_fd.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,327 +23,310 @@ <refentry id="sd_journal_get_fd"> - <refentryinfo> - <title>sd_journal_get_fd</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_get_fd</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_get_fd</refname> - <refname>sd_journal_get_events</refname> - <refname>sd_journal_get_timeout</refname> - <refname>sd_journal_process</refname> - <refname>sd_journal_wait</refname> - <refname>sd_journal_reliable_fd</refname> - <refname>SD_JOURNAL_NOP</refname> - <refname>SD_JOURNAL_APPEND</refname> - <refname>SD_JOURNAL_INVALIDATE</refname> - <refpurpose>Journal change notification - interface</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_get_fd</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_get_events</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_get_timeout</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_process</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_wait</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>uint64_t <parameter>timeout_usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_reliable_fd</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_get_fd()</function> returns - a file descriptor that may be asynchronously polled in - an external event loop and is signaled as soon as the - journal changes, because new entries or files were - added, rotation took place, or files have been - deleted, and similar. The file descriptor is suitable - for usage in - <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>. Use - <function>sd_journal_get_events()</function> for an - events mask to watch for. The call takes one argument: - the journal context object. Note that not all file - systems are capable of generating the necessary events - for wakeups from this file descriptor for changes to - be noticed immediately. In particular network files - systems do not generate suitable file change events in - all cases. Cases like this can be detected with - <function>sd_journal_reliable_fd()</function>, - below. <function>sd_journal_get_timeout()</function> - will ensure in these cases that wake-ups happen - frequently enough for changes to be noticed, although - with a certain latency.</para> - - <para><function>sd_journal_get_events()</function> - will return the <function>poll()</function> mask to - wait for. This function will return a combination of - <constant>POLLIN</constant> and - <constant>POLLOUT</constant> and similar to fill into - the <literal>.events</literal> field of - <varname>struct pollfd</varname>.</para> - - <para><function>sd_journal_get_timeout()</function> - will return a timeout value for usage in - <function>poll()</function>. This returns a value in - microseconds since the epoch of - <constant>CLOCK_MONOTONIC</constant> for timing out - <function>poll()</function> in - <varname>timeout_usec</varname>. See - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details about - <constant>CLOCK_MONOTONIC</constant>. If there is no - timeout to wait for, this will fill in - <constant>(uint64_t) -1</constant> instead. Note that - <function>poll()</function> takes a relative timeout - in milliseconds rather than an absolute timeout in - microseconds. To convert the absolute 'us' timeout - into relative 'ms', use code like the - following:</para> - - <programlisting>uint64_t t; + <refentryinfo> + <title>sd_journal_get_fd</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_get_fd</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_fd</refname> + <refname>sd_journal_get_events</refname> + <refname>sd_journal_get_timeout</refname> + <refname>sd_journal_process</refname> + <refname>sd_journal_wait</refname> + <refname>sd_journal_reliable_fd</refname> + <refname>SD_JOURNAL_NOP</refname> + <refname>SD_JOURNAL_APPEND</refname> + <refname>SD_JOURNAL_INVALIDATE</refname> + <refpurpose>Journal change notification + interface</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_fd</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_get_events</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_get_timeout</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_process</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_wait</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>uint64_t <parameter>timeout_usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_reliable_fd</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_fd()</function> returns a file + descriptor that may be asynchronously polled in an external event + loop and is signaled as soon as the journal changes, because new + entries or files were added, rotation took place, or files have + been deleted, and similar. The file descriptor is suitable for + usage in + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>. + Use <function>sd_journal_get_events()</function> for an events + mask to watch for. The call takes one argument: the journal + context object. Note that not all file systems are capable of + generating the necessary events for wakeups from this file + descriptor for changes to be noticed immediately. In particular + network files systems do not generate suitable file change events + in all cases. Cases like this can be detected with + <function>sd_journal_reliable_fd()</function>, below. + <function>sd_journal_get_timeout()</function> will ensure in these + cases that wake-ups happen frequently enough for changes to be + noticed, although with a certain latency.</para> + + <para><function>sd_journal_get_events()</function> will return the + <function>poll()</function> mask to wait for. This function will + return a combination of <constant>POLLIN</constant> and + <constant>POLLOUT</constant> and similar to fill into the + <literal>.events</literal> field of <varname>struct + pollfd</varname>.</para> + + <para><function>sd_journal_get_timeout()</function> will return a + timeout value for usage in <function>poll()</function>. This + returns a value in microseconds since the epoch of + <constant>CLOCK_MONOTONIC</constant> for timing out + <function>poll()</function> in <varname>timeout_usec</varname>. + See + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details about <constant>CLOCK_MONOTONIC</constant>. If there + is no timeout to wait for, this will fill in <constant>(uint64_t) + -1</constant> instead. Note that <function>poll()</function> takes + a relative timeout in milliseconds rather than an absolute timeout + in microseconds. To convert the absolute 'us' timeout into + relative 'ms', use code like the following:</para> + + <programlisting>uint64_t t; int msec; sd_journal_get_timeout(m, &t); if (t == (uint64_t) -1) - msec = -1; + msec = -1; else { - struct timespec ts; - uint64_t n; - clock_getttime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; }</programlisting> - <para>The code above does not do any error checking - for brevity's sake. The calculated <varname>msec</varname> - integer can be passed directly as - <function>poll()</function>'s timeout - parameter.</para> - - <para>After each <function>poll()</function> wake-up - <function>sd_journal_process()</function> needs to be - called to process events. This call will also indicate - what kind of change has been detected (see below; note - that spurious wake-ups are possible).</para> - - <para>A synchronous alternative for using - <function>sd_journal_get_fd()</function>, - <function>sd_journal_get_events()</function>, - <function>sd_journal_get_timeout()</function> and - <function>sd_journal_process()</function> is - <function>sd_journal_wait()</function>. It will - synchronously wait until the journal gets changed. The - maximum time this call sleeps may be controlled with - the <parameter>timeout_usec</parameter> - parameter. Pass <constant>(uint64_t) -1</constant> to - wait indefinitely. Internally this call simply - combines <function>sd_journal_get_fd()</function>, - <function>sd_journal_get_events()</function>, - <function>sd_journal_get_timeout()</function>, - <function>poll()</function> and - <function>sd_journal_process()</function> into - one.</para> - - <para><function>sd_journal_reliable_fd()</function> - may be used to check whether the wakeup events from - the file descriptor returned by - <function>sd_journal_get_fd()</function> are known to - be immediately triggered. On certain file systems - where file change events from the OS are not available - (such as NFS) changes need to be polled for - repeatedly, and hence are detected only with a certain - latency. This call will return a positive value if the - journal changes are detected immediately and zero when - they need to be polled for and hence might be noticed - only with a certain latency. Note that there's usually - no need to invoke this function directly as - <function>sd_journal_get_timeout()</function> on these - file systems will ask for timeouts explicitly - anyway.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_journal_get_fd()</function> returns - a valid file descriptor on success or a negative - errno-style error code.</para> - - <para><function>sd_journal_get_events()</function> - returns a combination of <constant>POLLIN</constant>, - <constant>POLLOUT</constant> and suchlike on success or - a negative errno-style error code.</para> - - <para><function>sd_journal_reliable_fd()</function> - returns a positive integer if the file descriptor - returned by <function>sd_journal_get_fd()</function> - will generate wake-ups immediately for all journal - changes. Returns 0 if there might be a latency - involved.</para> - - <para><function>sd_journal_process()</function> and - <function>sd_journal_wait()</function> return one of - <constant>SD_JOURNAL_NOP</constant>, - <constant>SD_JOURNAL_APPEND</constant> or - <constant>SD_JOURNAL_INVALIDATE</constant> on success or - a negative errno-style error code. If - <constant>SD_JOURNAL_NOP</constant> is returned, the - journal did not change since the last invocation. If - <constant>SD_JOURNAL_APPEND</constant> is returned, new - entries have been appended to the end of the - journal. If <constant>SD_JOURNAL_INVALIDATE</constant>, - journal files were added or removed (possibly due to - rotation). In the latter event, live-view UIs should - probably refresh their entire display, while in the - case of <constant>SD_JOURNAL_APPEND</constant>, it is - sufficient to simply continue reading at the previous - end of the journal.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_get_fd()</function>, - <function>sd_journal_get_events()</function>, - <function>sd_journal_reliable_fd()</function>, - <function>sd_journal_process()</function> and - <function>sd_journal_wait()</function> interfaces are - available as a shared library, which can be compiled and - linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>Iterating through the journal, in a live view tracking all changes:</para> - - <programlisting>#include <stdio.h> + <para>The code above does not do any error checking for brevity's + sake. The calculated <varname>msec</varname> integer can be passed + directly as <function>poll()</function>'s timeout + parameter.</para> + + <para>After each <function>poll()</function> wake-up + <function>sd_journal_process()</function> needs to be called to + process events. This call will also indicate what kind of change + has been detected (see below; note that spurious wake-ups are + possible).</para> + + <para>A synchronous alternative for using + <function>sd_journal_get_fd()</function>, + <function>sd_journal_get_events()</function>, + <function>sd_journal_get_timeout()</function> and + <function>sd_journal_process()</function> is + <function>sd_journal_wait()</function>. It will synchronously wait + until the journal gets changed. The maximum time this call sleeps + may be controlled with the <parameter>timeout_usec</parameter> + parameter. Pass <constant>(uint64_t) -1</constant> to wait + indefinitely. Internally this call simply combines + <function>sd_journal_get_fd()</function>, + <function>sd_journal_get_events()</function>, + <function>sd_journal_get_timeout()</function>, + <function>poll()</function> and + <function>sd_journal_process()</function> into one.</para> + + <para><function>sd_journal_reliable_fd()</function> may be used to + check whether the wakeup events from the file descriptor returned + by <function>sd_journal_get_fd()</function> are known to be + immediately triggered. On certain file systems where file change + events from the OS are not available (such as NFS) changes need to + be polled for repeatedly, and hence are detected only with a + certain latency. This call will return a positive value if the + journal changes are detected immediately and zero when they need + to be polled for and hence might be noticed only with a certain + latency. Note that there's usually no need to invoke this function + directly as <function>sd_journal_get_timeout()</function> on these + file systems will ask for timeouts explicitly anyway.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_fd()</function> returns a valid + file descriptor on success or a negative errno-style error + code.</para> + + <para><function>sd_journal_get_events()</function> returns a + combination of <constant>POLLIN</constant>, + <constant>POLLOUT</constant> and suchlike on success or a negative + errno-style error code.</para> + + <para><function>sd_journal_reliable_fd()</function> returns a + positive integer if the file descriptor returned by + <function>sd_journal_get_fd()</function> will generate wake-ups + immediately for all journal changes. Returns 0 if there might be a + latency involved.</para> + + <para><function>sd_journal_process()</function> and + <function>sd_journal_wait()</function> return one of + <constant>SD_JOURNAL_NOP</constant>, + <constant>SD_JOURNAL_APPEND</constant> or + <constant>SD_JOURNAL_INVALIDATE</constant> on success or a + negative errno-style error code. If + <constant>SD_JOURNAL_NOP</constant> is returned, the journal did + not change since the last invocation. If + <constant>SD_JOURNAL_APPEND</constant> is returned, new entries + have been appended to the end of the journal. If + <constant>SD_JOURNAL_INVALIDATE</constant>, journal files were + added or removed (possibly due to rotation). In the latter event, + live-view UIs should probably refresh their entire display, while + in the case of <constant>SD_JOURNAL_APPEND</constant>, it is + sufficient to simply continue reading at the previous end of the + journal.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_get_fd()</function>, + <function>sd_journal_get_events()</function>, + <function>sd_journal_reliable_fd()</function>, + <function>sd_journal_process()</function> and + <function>sd_journal_wait()</function> interfaces are available as + a shared library, which can be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Iterating through the journal, in a live view tracking all + changes:</para> + + <programlisting>#include <stdio.h> #include <string.h> #include <systemd/sd-journal.h> int main(int argc, char *argv[]) { - int r; - sd_journal *j; - r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); - if (r < 0) { - fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); - return 1; - } - for (;;) { - const void *d; - size_t l; - r = sd_journal_next(j); - if (r < 0) { - fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r)); - break; - } - if (r == 0) { - /* Reached the end, let's wait for changes, and try again */ - r = sd_journal_wait(j, (uint64_t) -1); - if (r < 0) { - fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r)); - break; - } - continue; - } - r = sd_journal_get_data(j, "MESSAGE", &d, &l); - if (r < 0) { - fprintf(stderr, "Failed to read message field: %s\n", strerror(-r)); - continue; - } - printf("%.*s\n", (int) l, (const char*) d); - } - sd_journal_close(j); - return 0; + int r; + sd_journal *j; + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + for (;;) { + const void *d; + size_t l; + r = sd_journal_next(j); + if (r < 0) { + fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r)); + break; + } + if (r == 0) { + /* Reached the end, let's wait for changes, and try again */ + r = sd_journal_wait(j, (uint64_t) -1); + if (r < 0) { + fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r)); + break; + } + continue; + } + r = sd_journal_get_data(j, "MESSAGE", &d, &l); + if (r < 0) { + fprintf(stderr, "Failed to read message field: %s\n", strerror(-r)); + continue; + } + printf("%.*s\n", (int) l, (const char*) d); + } + sd_journal_close(j); + return 0; }</programlisting> - <para>Waiting with <function>poll()</function> (this - example lacks all error checking for the sake of - simplicity):</para> + <para>Waiting with <function>poll()</function> (this + example lacks all error checking for the sake of + simplicity):</para> - <programlisting>#include <sys/poll.h> + <programlisting>#include <sys/poll.h> #include <systemd/sd-journal.h> int wait_for_changes(sd_journal *j) { - struct pollfd pollfd; - int msec; - - sd_journal_get_timeout(m, &t); - if (t == (uint64_t) -1) - msec = -1; - else { - struct timespec ts; - uint64_t n; - clock_getttime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; - } - - pollfd.fd = sd_journal_get_fd(j); - pollfd.events = sd_journal_get_events(j); - poll(&pollfd, 1, msec); - return sd_journal_process(j); + struct pollfd pollfd; + int msec; + + sd_journal_get_timeout(m, &t); + if (t == (uint64_t) -1) + msec = -1; + else { + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; + } + + pollfd.fd = sd_journal_get_fd(j); + pollfd.events = sd_journal_get_events(j); + poll(&pollfd, 1, msec); + return sd_journal_process(j); }</programlisting> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_get_realtime_usec.xml b/man/sd_journal_get_realtime_usec.xml index 18fbdca722..607d74666b 100644 --- a/man/sd_journal_get_realtime_usec.xml +++ b/man/sd_journal_get_realtime_usec.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,124 +23,119 @@ <refentry id="sd_journal_get_realtime_usec"> - <refentryinfo> - <title>sd_journal_get_realtime_usec</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_get_realtime_usec</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_get_realtime_usec</refname> - <refname>sd_journal_get_monotonic_usec</refname> - <refpurpose>Read timestamps from the current journal entry</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_get_realtime_usec</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>uint64_t *<parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_get_monotonic_usec</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>uint64_t *<parameter>usec</parameter></paramdef> - <paramdef>sd_id128_t *<parameter>boot_id</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_get_realtime_usec()</function> - gets the realtime (wallclock) timestamp of the - current journal entry. It takes two arguments: the - journal context object and a pointer to a 64-bit - unsigned integer to store the timestamp in. The - timestamp is in microseconds since the epoch, - i.e. <constant>CLOCK_REALTIME</constant>.</para> - - <para><function>sd_journal_get_monotonic_usec()</function> - gets the monotonic timestamp of the current journal - entry. It takes three arguments: the journal context - object, a pointer to a 64-bit unsigned integer to - store the timestamp in, as well as a 128-bit ID buffer - to store the boot ID of the monotonic timestamp. - The timestamp is in microseconds since boot-up of - the specific boot, - i.e. <constant>CLOCK_MONOTONIC</constant>. Since the - monotonic clock begins new with every reboot, it only - defines a well-defined point in time when used - together with an identifier identifying the boot. See - <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information. If the boot ID parameter is - passed <constant>NULL</constant>, the function will - fail if the monotonic timestamp of the current entry - is not of the current system boot.</para> - - <para>Note that these functions will not work before - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> - (or related call) has been called at least - once, in order to position the read pointer at a valid entry.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_journal_get_realtime_usec()</function> - and - <function>sd_journal_get_monotonic_usec()</function> - returns 0 on success or a negative errno-style error - code. If the boot ID parameter was passed <constant>NULL</constant> and the - monotonic timestamp of the current journal entry is - not of the current system boot, -ESTALE is returned by <function>sd_journal_get_monotonic_usec()</function>.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The - <function>sd_journal_get_realtime_usec()</function> - and - <function>sd_journal_get_monotonic_usec()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_journal_get_realtime_usec</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_get_realtime_usec</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_realtime_usec</refname> + <refname>sd_journal_get_monotonic_usec</refname> + <refpurpose>Read timestamps from the current journal entry</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_realtime_usec</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_get_monotonic_usec</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</parameter></paramdef> + <paramdef>sd_id128_t *<parameter>boot_id</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_realtime_usec()</function> gets the + realtime (wallclock) timestamp of the current journal entry. It + takes two arguments: the journal context object and a pointer to a + 64-bit unsigned integer to store the timestamp in. The timestamp + is in microseconds since the epoch, i.e. + <constant>CLOCK_REALTIME</constant>.</para> + + <para><function>sd_journal_get_monotonic_usec()</function> gets + the monotonic timestamp of the current journal entry. It takes + three arguments: the journal context object, a pointer to a 64-bit + unsigned integer to store the timestamp in, as well as a 128-bit + ID buffer to store the boot ID of the monotonic timestamp. The + timestamp is in microseconds since boot-up of the specific boot, + i.e. <constant>CLOCK_MONOTONIC</constant>. Since the monotonic + clock begins new with every reboot, it only defines a well-defined + point in time when used together with an identifier identifying + the boot. See + <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information. If the boot ID parameter is passed + <constant>NULL</constant>, the function will fail if the monotonic + timestamp of the current entry is not of the current system + boot.</para> + + <para>Note that these functions will not work before + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + (or related call) has been called at least + once, in order to position the read pointer at a valid entry.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_realtime_usec()</function> and + <function>sd_journal_get_monotonic_usec()</function> returns 0 on + success or a negative errno-style error code. If the boot ID + parameter was passed <constant>NULL</constant> and the monotonic + timestamp of the current journal entry is not of the current + system boot, <constant>-ESTALE</constant> is returned by + <function>sd_journal_get_monotonic_usec()</function>.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_get_realtime_usec()</function> and + <function>sd_journal_get_monotonic_usec()</function> interfaces + are available as a shared library, which can be compiled and + linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_get_usage.xml b/man/sd_journal_get_usage.xml index cd996bdb8f..72c804d834 100644 --- a/man/sd_journal_get_usage.xml +++ b/man/sd_journal_get_usage.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,81 +23,78 @@ <refentry id="sd_journal_get_usage"> - <refentryinfo> - <title>sd_journal_get_usage</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_get_usage</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_get_usage</refname> - <refpurpose>Journal disk usage</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_get_usage</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>uint64_t *<parameter>bytes</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_get_usage()</function> - determines the total disk space currently used by - journal files (in bytes). If - <constant>SD_JOURNAL_LOCAL_ONLY</constant> was passed - when opening the journal, this value will only reflect - the size of journal files of the local host, otherwise - of all hosts.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_journal_get_usage()</function> - returns 0 on success or a negative errno-style error - code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_get_usage()</function> - interface is available as a shared library, which can be - compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - </para> - </refsect1> + <refentryinfo> + <title>sd_journal_get_usage</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_get_usage</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_get_usage</refname> + <refpurpose>Journal disk usage</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_get_usage</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>uint64_t *<parameter>bytes</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_get_usage()</function> determines the + total disk space currently used by journal files (in bytes). If + <constant>SD_JOURNAL_LOCAL_ONLY</constant> was passed when opening + the journal, this value will only reflect the size of journal + files of the local host, otherwise of all hosts.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_get_usage()</function> returns 0 on + success or a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_get_usage()</function> interface is + available as a shared library, which can be compiled and linked to + with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml index 4df6b4e6fd..115fe26661 100644 --- a/man/sd_journal_next.xml +++ b/man/sd_journal_next.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,191 +23,185 @@ <refentry id="sd_journal_next"> - <refentryinfo> - <title>sd_journal_next</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_next</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_next</refname> - <refname>sd_journal_previous</refname> - <refname>sd_journal_next_skip</refname> - <refname>sd_journal_previous_skip</refname> - <refname>SD_JOURNAL_FOREACH</refname> - <refname>SD_JOURNAL_FOREACH_BACKWARDS</refname> - <refpurpose>Advance or set back the read pointer in the journal</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_next</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_previous</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_next_skip</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>uint64_t <parameter>skip</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_previous_skip</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>uint64_t <parameter>skip</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef><function>SD_JOURNAL_FOREACH</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef><function>SD_JOURNAL_FOREACH_BACKWARDS</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_next()</function> advances - the read pointer into the journal by one entry. The - only argument taken is a journal context object as - allocated via - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. After - successful invocation the entry may be read with - functions such as - <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>Similarly, <function>sd_journal_previous()</function> sets - the read pointer back one entry.</para> - - <para><function>sd_journal_next_skip()</function> and - <function>sd_journal_previous_skip()</function> - advance/set back the read pointer by multiple entries - at once, as specified in the <varname>skip</varname> - parameter.</para> - - <para>The journal is strictly ordered by reception - time, and hence advancing to the next entry guarantees - that the entry then pointing to is later in time than - then previous one, or has the same timestamp.</para> - - <para>Note that - <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and related calls will fail unless - <function>sd_journal_next()</function> has been - invoked at least once in order to position the read - pointer on a journal entry.</para> - - <para>Note that the - <function>SD_JOURNAL_FOREACH()</function> macro may be used - as a wrapper around - <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and <function>sd_journal_next()</function> in order to - make iterating through the journal easier. See below - for an example. Similarly, - <function>SD_JOURNAL_FOREACH_BACKWARDS()</function> - may be used for iterating the journal in reverse - order.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>The four calls return the number of entries - advanced/set back on success or a negative errno-style - error code. When the end or beginning of the journal - is reached, a number smaller than requested is - returned. More specifically, if - <function>sd_journal_next()</function> or - <function>sd_journal_previous()</function> reach the - end/beginning of the journal they will return 0, - instead of 1 when they are successful. This should be - considered an EOF marker.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_next()</function>, <function>sd_journal_previous()</function>, - <function>sd_journal_next_skip()</function> and - <function>sd_journal_previous_skip()</function> interfaces are - available as a shared library, which can be compiled and - linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>Iterating through the journal:</para> - - <programlisting>#include <stdio.h> + <refentryinfo> + <title>sd_journal_next</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_next</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_next</refname> + <refname>sd_journal_previous</refname> + <refname>sd_journal_next_skip</refname> + <refname>sd_journal_previous_skip</refname> + <refname>SD_JOURNAL_FOREACH</refname> + <refname>SD_JOURNAL_FOREACH_BACKWARDS</refname> + <refpurpose>Advance or set back the read pointer in the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_next</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_previous</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_next_skip</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>uint64_t <parameter>skip</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_previous_skip</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>uint64_t <parameter>skip</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef><function>SD_JOURNAL_FOREACH</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef><function>SD_JOURNAL_FOREACH_BACKWARDS</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_next()</function> advances the read + pointer into the journal by one entry. The only argument taken is + a journal context object as allocated via + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + After successful invocation the entry may be read with functions + such as + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>Similarly, <function>sd_journal_previous()</function> sets + the read pointer back one entry.</para> + + <para><function>sd_journal_next_skip()</function> and + <function>sd_journal_previous_skip()</function> advance/set back + the read pointer by multiple entries at once, as specified in the + <varname>skip</varname> parameter.</para> + + <para>The journal is strictly ordered by reception time, and hence + advancing to the next entry guarantees that the entry then + pointing to is later in time than then previous one, or has the + same timestamp.</para> + + <para>Note that + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and related calls will fail unless + <function>sd_journal_next()</function> has been invoked at least + once in order to position the read pointer on a journal + entry.</para> + + <para>Note that the <function>SD_JOURNAL_FOREACH()</function> + macro may be used as a wrapper around + <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and <function>sd_journal_next()</function> in order to make + iterating through the journal easier. See below for an example. + Similarly, <function>SD_JOURNAL_FOREACH_BACKWARDS()</function> may + be used for iterating the journal in reverse order.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The four calls return the number of entries advanced/set + back on success or a negative errno-style error code. When the end + or beginning of the journal is reached, a number smaller than + requested is returned. More specifically, if + <function>sd_journal_next()</function> or + <function>sd_journal_previous()</function> reach the end/beginning + of the journal they will return 0, instead of 1 when they are + successful. This should be considered an EOF marker.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_next()</function>, + <function>sd_journal_previous()</function>, + <function>sd_journal_next_skip()</function> and + <function>sd_journal_previous_skip()</function> interfaces are + available as a shared library, which can be compiled and linked to + with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Iterating through the journal:</para> + + <programlisting>#include <stdio.h> #include <string.h> #include <systemd/sd-journal.h> int main(int argc, char *argv[]) { - int r; - sd_journal *j; - r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); - if (r < 0) { - fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); - return 1; - } - SD_JOURNAL_FOREACH(j) { - const char *d; - size_t l; - - r = sd_journal_get_data(j, "MESSAGE", (const void **)&d, &l); - if (r < 0) { - fprintf(stderr, "Failed to read message field: %s\n", strerror(-r)); - continue; - } - - printf("%.*s\n", (int) l, d); - } - sd_journal_close(j); - return 0; + int r; + sd_journal *j; + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH(j) { + const char *d; + size_t l; + + r = sd_journal_get_data(j, "MESSAGE", (const void **)&d, &l); + if (r < 0) { + fprintf(stderr, "Failed to read message field: %s\n", strerror(-r)); + continue; + } + + printf("%.*s\n", (int) l, d); + } + sd_journal_close(j); + return 0; }</programlisting> - </refsect1> + </refsect1> - <refsect1> - <title>See Also</title> + <refsect1> + <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index 2d1dbc32f8..fb572802a3 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,231 +23,217 @@ <refentry id="sd_journal_open"> - <refentryinfo> - <title>sd_journal_open</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_open</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_open</refname> - <refname>sd_journal_open_directory</refname> - <refname>sd_journal_open_files</refname> - <refname>sd_journal_open_container</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> - <refpurpose>Open the system journal for reading</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_open</function></funcdef> - <paramdef>sd_journal **<parameter>ret</parameter></paramdef> - <paramdef>int <parameter>flags</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_open_directory</function></funcdef> - <paramdef>sd_journal **<parameter>ret</parameter></paramdef> - <paramdef>const char *<parameter>path</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> - <paramdef>int <parameter>flags</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_open_container</function></funcdef> - <paramdef>sd_journal **<parameter>ret</parameter></paramdef> - <paramdef>const char *<parameter>machine</parameter></paramdef> - <paramdef>int <parameter>flags</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>void <function>sd_journal_close</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_open()</function> opens - the log journal for reading. It will find all journal - files automatically and interleave them automatically - when reading. As first argument it takes a pointer to - a <varname>sd_journal</varname> pointer, which on - success will contain a journal context object. The - second argument is a flags field, which may consist of - the following flags ORed together: - <constant>SD_JOURNAL_LOCAL_ONLY</constant> makes sure - only journal files generated on the local machine will - be opened. <constant>SD_JOURNAL_RUNTIME_ONLY</constant> - makes sure only volatile journal files will be opened, - excluding those which are stored on persistent - storage. <constant>SD_JOURNAL_SYSTEM</constant> - will cause journal files of system services and the - kernel (in opposition to user session processes) to - be opened. <constant>SD_JOURNAL_CURRENT_USER</constant> - will cause journal files of the current user to be - opened. If neither <constant>SD_JOURNAL_SYSTEM</constant> - nor <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><varname>sd_journal</varname> objects cannot be - used in the child after a fork. Functions which take a - journal object as an argument - (<function>sd_journal_next()</function> and others) - will return <constant>-ECHILD</constant> after a fork. - </para> - - <para><function>sd_journal_close()</function> will - close the journal context allocated with - <function>sd_journal_open()</function> or - <function>sd_journal_open_directory()</function> and - free its resources.</para> - - <para>When opening the journal only journal files - accessible to the calling user will be opened. If - journal files are not accessible to the caller, this - will be silently ignored.</para> - - <para>See - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for an example of how to iterate through the journal - after opening it with - <function>sd_journal_open()</function>.</para> - - <para>A journal context object returned by - <function>sd_journal_open()</function> references a - specific journal entry as <emphasis>current</emphasis> entry, - similar to a file seek index in a classic file system - file, but without absolute positions. It may be - altered with - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and related calls. The current entry position may be - exported in <emphasis>cursor</emphasis> strings, as accessible - via - <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Cursor - strings may be used to globally identify a specific - journal entry in a stable way and then later to seek - to it (or if the specific entry is not available - locally, to its closest entry in time) - <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>Notification of journal changes is available via - <function>sd_journal_get_fd()</function> and related - calls.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>The <function>sd_journal_open()</function>, - <function>sd_journal_open_directory()</function>, and - <function>sd_journal_open_files()</function> calls - return 0 on success or a negative errno-style error - code. <function>sd_journal_close()</function> returns - nothing.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_open()</function>, - <function>sd_journal_open_directory()</function> and - <function>sd_journal_close()</function> interfaces are - available as a shared library, which can be compiled and - linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>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> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_journal_open</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_open</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_open</refname> + <refname>sd_journal_open_directory</refname> + <refname>sd_journal_open_files</refname> + <refname>sd_journal_open_container</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> + <refpurpose>Open the system journal for reading</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_open</function></funcdef> + <paramdef>sd_journal **<parameter>ret</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_open_directory</function></funcdef> + <paramdef>sd_journal **<parameter>ret</parameter></paramdef> + <paramdef>const char *<parameter>path</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> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_open_container</function></funcdef> + <paramdef>sd_journal **<parameter>ret</parameter></paramdef> + <paramdef>const char *<parameter>machine</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_journal_close</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_open()</function> opens the log journal + for reading. It will find all journal files automatically and + interleave them automatically when reading. As first argument it + takes a pointer to a <varname>sd_journal</varname> pointer, which + on success will contain a journal context object. The second + argument is a flags field, which may consist of the following + flags ORed together: <constant>SD_JOURNAL_LOCAL_ONLY</constant> + makes sure only journal files generated on the local machine will + be opened. <constant>SD_JOURNAL_RUNTIME_ONLY</constant> makes sure + only volatile journal files will be opened, excluding those which + are stored on persistent storage. + <constant>SD_JOURNAL_SYSTEM</constant> will cause journal files of + system services and the kernel (in opposition to user session + processes) to be opened. + <constant>SD_JOURNAL_CURRENT_USER</constant> will cause journal + files of the current user to be opened. If neither + <constant>SD_JOURNAL_SYSTEM</constant> nor + <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><varname>sd_journal</varname> objects cannot be used in the + child after a fork. Functions which take a journal object as an + argument (<function>sd_journal_next()</function> and others) will + return <constant>-ECHILD</constant> after a fork. + </para> + + <para><function>sd_journal_close()</function> will close the + journal context allocated with + <function>sd_journal_open()</function> or + <function>sd_journal_open_directory()</function> and free its + resources.</para> + + <para>When opening the journal only journal files accessible to + the calling user will be opened. If journal files are not + accessible to the caller, this will be silently ignored.</para> + + <para>See + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for an example of how to iterate through the journal after opening + it with <function>sd_journal_open()</function>.</para> + + <para>A journal context object returned by + <function>sd_journal_open()</function> references a specific + journal entry as <emphasis>current</emphasis> entry, similar to a + file seek index in a classic file system file, but without + absolute positions. It may be altered with + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_journal_seek_head</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and related calls. The current entry position may be exported in + <emphasis>cursor</emphasis> strings, as accessible via + <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Cursor strings may be used to globally identify a specific journal + entry in a stable way and then later to seek to it (or if the + specific entry is not available locally, to its closest entry in + time) + <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>Notification of journal changes is available via + <function>sd_journal_get_fd()</function> and related calls.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The <function>sd_journal_open()</function>, + <function>sd_journal_open_directory()</function>, and + <function>sd_journal_open_files()</function> calls return 0 on + success or a negative errno-style error code. + <function>sd_journal_close()</function> returns nothing.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_open()</function>, + <function>sd_journal_open_directory()</function> and + <function>sd_journal_close()</function> interfaces are available + as a shared library, which can be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>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> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml index 055094c9a2..068b10e7ca 100644 --- a/man/sd_journal_print.xml +++ b/man/sd_journal_print.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,248 +23,238 @@ <refentry id="sd_journal_print"> - <refentryinfo> - <title>sd_journal_print</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_print</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_print</refname> - <refname>sd_journal_printv</refname> - <refname>sd_journal_send</refname> - <refname>sd_journal_sendv</refname> - <refname>sd_journal_perror</refname> - <refname>SD_JOURNAL_SUPPRESS_LOCATION</refname> - <refpurpose>Submit log entries to the journal</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_print</function></funcdef> - <paramdef>int <parameter>priority</parameter></paramdef> - <paramdef>const char *<parameter>format</parameter></paramdef> - <paramdef>...</paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_printv</function></funcdef> - <paramdef>int <parameter>priority</parameter></paramdef> - <paramdef>const char *<parameter>format</parameter></paramdef> - <paramdef>va_list <parameter>ap</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_send</function></funcdef> - <paramdef>const char *<parameter>format</parameter></paramdef> - <paramdef>...</paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_sendv</function></funcdef> - <paramdef>const struct iovec *<parameter>iov</parameter></paramdef> - <paramdef>int <parameter>n</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_perror</function></funcdef> - <paramdef>const char *<parameter>message</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_print()</function> may be - used to submit simple, plain text log entries to the - system journal. The first argument is a priority - value. This is followed by a format string and its - parameters, similar to - <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The - priority value is one of - <constant>LOG_EMERG</constant>, - <constant>LOG_ALERT</constant>, - <constant>LOG_CRIT</constant>, - <constant>LOG_ERR</constant>, - <constant>LOG_WARNING</constant>, - <constant>LOG_NOTICE</constant>, - <constant>LOG_INFO</constant>, - <constant>LOG_DEBUG</constant>, as defined in - <filename>syslog.h</filename>, see - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details. It is recommended to use this call to - submit log messages in the application locale or system - locale and in UTF-8 format, but no such restrictions - are enforced.</para> - - <para><function>sd_journal_printv()</function> is - similar to <function>sd_journal_print()</function> but - takes a variable argument list encapsulated in an - object of type <varname>va_list</varname> (see - <citerefentry><refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information) instead of the format string. It - is otherwise equivalent in behavior.</para> - - <para><function>sd_journal_send()</function> may be - used to submit structured log entries to the system - journal. It takes a series of format strings, each - immediately followed by their associated parameters, - terminated by <constant>NULL</constant>. The strings passed should be of - the format <literal>VARIABLE=value</literal>. The - variable name must be in uppercase and consist only of - characters, numbers and underscores, and may not begin - with an underscore. (All assignments that do not - follow this syntax will be ignored.) The value can be - of any size and format. It is highly recommended to - submit text strings formatted in the UTF-8 character - encoding only, and submit binary fields only when - formatting in UTF-8 strings is not sensible. A number - of well known fields are defined, see - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details, but additional application defined fields - may be used. A variable may be assigned more than one - value per entry.</para> - - <para><function>sd_journal_sendv()</function> is - similar to <function>sd_journal_send()</function> but - takes an array of <varname>struct iovec</varname> (as - defined in <filename>uio.h</filename>, see - <citerefentry><refentrytitle>readv</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details) instead of the format string. Each - structure should reference one field of the entry to - submit. The second argument specifies the number of - structures in the array. - <function>sd_journal_sendv()</function> is - particularly useful to submit binary objects to the - journal where that is necessary.</para> - - <para><function>sd_journal_perror()</function> is a - similar to - <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and writes a message to the journal that consists of - the passed string, suffixed with ": " and a human - readable representation of the current error code - stored in - <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If - the message string is passed as <constant>NULL</constant> or empty string, - only the error string representation will be written, - prefixed with nothing. An additional journal field - ERRNO= is included in the entry containing the numeric - error code formatted as decimal string. The log - priority used is <constant>LOG_ERR</constant> (3).</para> - - <para>Note that <function>sd_journal_send()</function> - is a wrapper around - <function>sd_journal_sendv()</function> to make it - easier to use when only text strings shall be - submitted. Also, the following two calls are - mostly equivalent:</para> - - <programlisting>sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid()); + <refentryinfo> + <title>sd_journal_print</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_print</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_print</refname> + <refname>sd_journal_printv</refname> + <refname>sd_journal_send</refname> + <refname>sd_journal_sendv</refname> + <refname>sd_journal_perror</refname> + <refname>SD_JOURNAL_SUPPRESS_LOCATION</refname> + <refpurpose>Submit log entries to the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_print</function></funcdef> + <paramdef>int <parameter>priority</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_printv</function></funcdef> + <paramdef>int <parameter>priority</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>va_list <parameter>ap</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_send</function></funcdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_sendv</function></funcdef> + <paramdef>const struct iovec *<parameter>iov</parameter></paramdef> + <paramdef>int <parameter>n</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_perror</function></funcdef> + <paramdef>const char *<parameter>message</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_print()</function> may be used to + submit simple, plain text log entries to the system journal. The + first argument is a priority value. This is followed by a format + string and its parameters, similar to + <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + The priority value is one of + <constant>LOG_EMERG</constant>, + <constant>LOG_ALERT</constant>, + <constant>LOG_CRIT</constant>, + <constant>LOG_ERR</constant>, + <constant>LOG_WARNING</constant>, + <constant>LOG_NOTICE</constant>, + <constant>LOG_INFO</constant>, + <constant>LOG_DEBUG</constant>, as defined in + <filename>syslog.h</filename>, see + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details. It is recommended to use this call to submit log + messages in the application locale or system locale and in UTF-8 + format, but no such restrictions are enforced.</para> + + <para><function>sd_journal_printv()</function> is similar to + <function>sd_journal_print()</function> but takes a variable + argument list encapsulated in an object of type + <varname>va_list</varname> (see + <citerefentry><refentrytitle>stdarg</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information) instead of the format string. It is + otherwise equivalent in behavior.</para> + + <para><function>sd_journal_send()</function> may be used to submit + structured log entries to the system journal. It takes a series of + format strings, each immediately followed by their associated + parameters, terminated by <constant>NULL</constant>. The strings + passed should be of the format <literal>VARIABLE=value</literal>. + The variable name must be in uppercase and consist only of + characters, numbers and underscores, and may not begin with an + underscore. (All assignments that do not follow this syntax will + be ignored.) The value can be of any size and format. It is highly + recommended to submit text strings formatted in the UTF-8 + character encoding only, and submit binary fields only when + formatting in UTF-8 strings is not sensible. A number of well + known fields are defined, see + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details, but additional application defined fields may be + used. A variable may be assigned more than one value per + entry.</para> + + <para><function>sd_journal_sendv()</function> is similar to + <function>sd_journal_send()</function> but takes an array of + <varname>struct iovec</varname> (as defined in + <filename>uio.h</filename>, see + <citerefentry><refentrytitle>readv</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details) instead of the format string. Each structure should + reference one field of the entry to submit. The second argument + specifies the number of structures in the array. + <function>sd_journal_sendv()</function> is particularly useful to + submit binary objects to the journal where that is + necessary.</para> + + <para><function>sd_journal_perror()</function> is a similar to + <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and writes a message to the journal that consists of the passed + string, suffixed with ": " and a human readable representation of + the current error code stored in + <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + If the message string is passed as <constant>NULL</constant> or + empty string, only the error string representation will be + written, prefixed with nothing. An additional journal field ERRNO= + is included in the entry containing the numeric error code + formatted as decimal string. The log priority used is + <constant>LOG_ERR</constant> (3).</para> + + <para>Note that <function>sd_journal_send()</function> is a + wrapper around <function>sd_journal_sendv()</function> to make it + easier to use when only text strings shall be submitted. Also, the + following two calls are mostly equivalent:</para> + + <programlisting>sd_journal_print(LOG_INFO, "Hello World, this is PID %lu!", (unsigned long) getpid()); sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(), - "PRIORITY=%i", LOG_INFO, - NULL);</programlisting> - - <para>Note that these calls implicitly add fields for - the source file, function name and code line where - invoked. This is implemented with macros. If this is - not desired, it can be turned off by defining - SD_JOURNAL_SUPPRESS_LOCATION before including - <filename>sd-journal.h</filename>.</para> - - <para><citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - and <function>sd_journal_print()</function> may - largely be used interchangeably - functionality-wise. However, note that log messages - logged via the former take a different path to the - journal server than the later, and hence global - chronological ordering between the two streams cannot - be guaranteed. Using - <function>sd_journal_print()</function> has the - benefit of logging source code line, filenames, and - functions as metadata along all entries, and - guaranteeing chronological ordering with structured - log entries that are generated via - <function>sd_journal_send()</function>. Using - <function>syslog()</function> has the benefit of being - more portable.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>The four calls return 0 on success or a negative - errno-style error code. The - <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> - variable itself is not altered.</para> - - <para>If - <citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry> - is not running (the socket is not present), those - functions do nothing, and also return 0.</para> - </refsect1> - - <refsect1> - <title>Async signal safety</title> - <para><function>sd_journal_sendv()</function> is "async signal - safe" in the meaning of <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - </para> - - <para><function>sd_journal_print</function>, - <function>sd_journal_printv</function>, - <function>sd_journal_send</function>, and - <function>sd_journal_perror</function> are - not async signal safe.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_print()</function>, - <function>sd_journal_printv()</function>, - <function>sd_journal_send()</function> and - <function>sd_journal_sendv()</function> interfaces - are available as a shared library, which can be compiled - and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + "PRIORITY=%i", LOG_INFO, + NULL);</programlisting> + + <para>Note that these calls implicitly add fields for the source + file, function name and code line where invoked. This is + implemented with macros. If this is not desired, it can be turned + off by defining SD_JOURNAL_SUPPRESS_LOCATION before including + <filename>sd-journal.h</filename>.</para> + + <para><citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and <function>sd_journal_print()</function> may + largely be used interchangeably + functionality-wise. However, note that log messages + logged via the former take a different path to the + journal server than the later, and hence global + chronological ordering between the two streams cannot + be guaranteed. Using + <function>sd_journal_print()</function> has the + benefit of logging source code line, filenames, and + functions as metadata along all entries, and + guaranteeing chronological ordering with structured + log entries that are generated via + <function>sd_journal_send()</function>. Using + <function>syslog()</function> has the benefit of being + more portable.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The four calls return 0 on success or a negative errno-style + error code. The + <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> + variable itself is not altered.</para> + + <para>If + <citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry> + is not running (the socket is not present), those functions do + nothing, and also return 0.</para> + </refsect1> + + <refsect1> + <title>Async signal safety</title> + <para><function>sd_journal_sendv()</function> is "async signal + safe" in the meaning of + <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> + + <para><function>sd_journal_print</function>, + <function>sd_journal_printv</function>, + <function>sd_journal_send</function>, and + <function>sd_journal_perror</function> are + not async signal safe.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_print()</function>, + <function>sd_journal_printv()</function>, + <function>sd_journal_send()</function> and + <function>sd_journal_sendv()</function> interfaces are available + as a shared library, which can be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>perror</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml index 8f0e6b8160..ac0e5f633f 100644 --- a/man/sd_journal_query_unique.xml +++ b/man/sd_journal_query_unique.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,193 +23,184 @@ <refentry id="sd_journal_query_unique"> - <refentryinfo> - <title>sd_journal_query_unique</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_query_unique</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_query_unique</refname> - <refname>sd_journal_enumerate_unique</refname> - <refname>sd_journal_restart_unique</refname> - <refname>SD_JOURNAL_FOREACH_UNIQUE</refname> - <refpurpose>Read unique data fields from the journal</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_query_unique</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>const char *<parameter>field</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_enumerate_unique</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>const void **<parameter>data</parameter></paramdef> - <paramdef>size_t *<parameter>length</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>void <function>sd_journal_restart_unique</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>const void *<parameter>data</parameter></paramdef> - <paramdef>size_t <parameter>length</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_query_unique()</function> - queries the journal for all unique values the - specified field can take. It takes two arguments: the - journal to query and the field name to look - for. Well-known field names are listed on - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Field - names must be specified without a trailing '='. After - this function has been executed successfully the field - values may be queried using - <function>sd_journal_enumerate_unique()</function>. Invoking - this call a second time will change the field name - being queried and reset the enumeration index to the - first field value that matches.</para> - - <para><function>sd_journal_enumerate_unique()</function> - may be used to iterate through all data fields which - match the previously selected field name as set with - <function>sd_journal_query_unique()</function>. On - each invocation the next field data matching the field - name is returned. The order of the returned data - fields is not defined. It takes three arguments: the - journal context object, plus a pair of pointers to - pointer/size variables where the data object and its - size shall be stored in. The returned data is in a - read-only memory map and is only valid until the next - invocation of - <function>sd_journal_enumerate_unique()</function>. Note - that the data returned will be prefixed with the field - name and '='. Note that this call is subject to the - data field size threshold as controlled by - <function>sd_journal_set_data_threshold()</function>.</para> - - <para><function>sd_journal_restart_unique()</function> - resets the data enumeration index to the beginning of - the list. The next invocation of - <function>sd_journal_enumerate_unique()</function> - will return the first field data matching the field - name again.</para> - - <para>Note that the - <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro - may be used as a handy wrapper around - <function>sd_journal_restart_unique()</function> and - <function>sd_journal_enumerate_unique()</function>.</para> - - <para>Note that these functions currently are not - influenced by matches set with - <function>sd_journal_add_match()</function> but this - might change in a later version of this - software.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para><function>sd_journal_query_unique()</function> - returns 0 on success or a negative errno-style error - code. <function>sd_journal_enumerate_unique()</function> - returns a positive integer if the next field data has - been read, 0 when no more fields are known, or a - negative errno-style error - code. <function>sd_journal_restart_unique()</function> - returns nothing.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_query_unique()</function>, - <function>sd_journal_enumerate_unique()</function> and - <function>sd_journal_restart_unique()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>Use the - <function>SD_JOURNAL_FOREACH_UNIQUE</function> macro - to iterate through all values a field of the journal - can take. The following example lists all unit names - referenced in the journal:</para> - - <programlisting>#include <stdio.h> + <refentryinfo> + <title>sd_journal_query_unique</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_query_unique</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_query_unique</refname> + <refname>sd_journal_enumerate_unique</refname> + <refname>sd_journal_restart_unique</refname> + <refname>SD_JOURNAL_FOREACH_UNIQUE</refname> + <refpurpose>Read unique data fields from the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_query_unique</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const char *<parameter>field</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_enumerate_unique</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const void **<parameter>data</parameter></paramdef> + <paramdef>size_t *<parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_journal_restart_unique</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const void *<parameter>data</parameter></paramdef> + <paramdef>size_t <parameter>length</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_query_unique()</function> queries the + journal for all unique values the specified field can take. It + takes two arguments: the journal to query and the field name to + look for. Well-known field names are listed on + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + Field names must be specified without a trailing '='. After this + function has been executed successfully the field values may be + queried using <function>sd_journal_enumerate_unique()</function>. + Invoking this call a second time will change the field name being + queried and reset the enumeration index to the first field value + that matches.</para> + + <para><function>sd_journal_enumerate_unique()</function> may be + used to iterate through all data fields which match the previously + selected field name as set with + <function>sd_journal_query_unique()</function>. On each invocation + the next field data matching the field name is returned. The order + of the returned data fields is not defined. It takes three + arguments: the journal context object, plus a pair of pointers to + pointer/size variables where the data object and its size shall be + stored in. The returned data is in a read-only memory map and is + only valid until the next invocation of + <function>sd_journal_enumerate_unique()</function>. Note that the + data returned will be prefixed with the field name and '='. Note + that this call is subject to the data field size threshold as + controlled by + <function>sd_journal_set_data_threshold()</function>.</para> + + <para><function>sd_journal_restart_unique()</function> resets the + data enumeration index to the beginning of the list. The next + invocation of <function>sd_journal_enumerate_unique()</function> + will return the first field data matching the field name + again.</para> + + <para>Note that the + <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro may be used + as a handy wrapper around + <function>sd_journal_restart_unique()</function> and + <function>sd_journal_enumerate_unique()</function>.</para> + + <para>Note that these functions currently are not influenced by + matches set with <function>sd_journal_add_match()</function> but + this might change in a later version of this software.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_journal_query_unique()</function> returns 0 on + success or a negative errno-style error code. + <function>sd_journal_enumerate_unique()</function> returns a + positive integer if the next field data has been read, 0 when no + more fields are known, or a negative errno-style error code. + <function>sd_journal_restart_unique()</function> returns + nothing.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_query_unique()</function>, + <function>sd_journal_enumerate_unique()</function> and + <function>sd_journal_restart_unique()</function> interfaces are + available as a shared library, which can be compiled and linked to + with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Use the <function>SD_JOURNAL_FOREACH_UNIQUE</function> macro + to iterate through all values a field of the journal can take. The + following example lists all unit names referenced in the + journal:</para> + + <programlisting>#include <stdio.h> #include <string.h> #include <systemd/sd-journal.h> int main(int argc, char *argv[]) { - sd_journal *j; - const void *d; - size_t l; - int r; - - r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); - if (r < 0) { - fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); - return 1; - } - r = sd_journal_query_unique(j, "_SYSTEMD_UNIT"); - if (r < 0) { - fprintf(stderr, "Failed to query journal: %s\n", strerror(-r)); - return 1; - } - SD_JOURNAL_FOREACH_UNIQUE(j, d, l) - printf("%.*s\n", (int) l, (const char*) d); - sd_journal_close(j); - return 0; + sd_journal *j; + const void *d; + size_t l; + int r; + + r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY); + if (r < 0) { + fprintf(stderr, "Failed to open journal: %s\n", strerror(-r)); + return 1; + } + r = sd_journal_query_unique(j, "_SYSTEMD_UNIT"); + if (r < 0) { + fprintf(stderr, "Failed to query journal: %s\n", strerror(-r)); + return 1; + } + SD_JOURNAL_FOREACH_UNIQUE(j, d, l) + printf("%.*s\n", (int) l, (const char*) d); + sd_journal_close(j); + return 0; }</programlisting> - </refsect1> + </refsect1> - <refsect1> - <title>See Also</title> + <refsect1> + <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml index 2ef37e5288..d74c2d5bbc 100644 --- a/man/sd_journal_seek_head.xml +++ b/man/sd_journal_seek_head.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,157 +23,150 @@ <refentry id="sd_journal_seek_head"> - <refentryinfo> - <title>sd_journal_seek_head</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_seek_head</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_seek_head</refname> - <refname>sd_journal_seek_tail</refname> - <refname>sd_journal_seek_monotonic_usec</refname> - <refname>sd_journal_seek_realtime_usec</refname> - <refname>sd_journal_seek_cursor</refname> - <refpurpose>Seek to a position in the - journal</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_seek_head</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_seek_tail</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_seek_monotonic_usec</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>sd_id128_t <parameter>boot_id</parameter></paramdef> - <paramdef>uint64_t <parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_seek_realtime_usec</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>uint64_t <parameter>usec</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_journal_seek_cursor</function></funcdef> - <paramdef>sd_journal *<parameter>j</parameter></paramdef> - <paramdef>const char *<parameter>cursor</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_seek_head()</function> - seeks to the beginning of the journal, i.e. the oldest - available entry.</para> - - <para>Similarly, - <function>sd_journal_seek_tail()</function> may be - used to seek to the end of the journal, i.e. the most - recent available entry.</para> - - <para><function>sd_journal_seek_monotonic_usec()</function> - seeks to the entry with the specified monotonic - timestamp, - i.e. <constant>CLOCK_MONOTONIC</constant>. Since - monotonic time restarts on every reboot a boot ID - needs to be specified as well.</para> - - <para><function>sd_journal_seek_realtime_usec()</function> - seeks to the entry with the specified realtime - (wallclock) timestamp, - i.e. <constant>CLOCK_REALTIME</constant>. Note that - the realtime clock is not necessarily monotonic. If a - realtime timestamp is ambiguous, it is not defined - which position is sought to.</para> - - <para><function>sd_journal_seek_cursor()</function> - seeks to the entry located at the specified cursor - string. For details on cursors, see - <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If - no entry matching the specified cursor is found the - call will seek to the next closest entry (in terms of - time) instead. To verify whether the newly selected - entry actually matches the cursor, use - <citerefentry><refentrytitle>sd_journal_test_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>Note that these calls do not actually make any - entry the new current entry, this needs to be done in - a separate step with a subsequent - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> - invocation (or a similar call). Only then, entry data - may be retrieved via - <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If - no entry exists that matches exactly the specified - seek address, the next closest is sought to. If - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> - is used, the closest following entry will be sought to, - if - <citerefentry><refentrytitle>sd_journal_previous</refentrytitle><manvolnum>3</manvolnum></citerefentry> - is used the closest preceding entry is sought - to.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>The functions return 0 on success or a negative - errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_seek_head()</function>, - <function>sd_journal_seek_tail()</function>, - <function>sd_journal_seek_monotonic_usec()</function>, - <function>sd_journal_seek_realtime_usec()</function>, - and <function>sd_journal_seek_cursor()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_journal_seek_head</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_seek_head</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_seek_head</refname> + <refname>sd_journal_seek_tail</refname> + <refname>sd_journal_seek_monotonic_usec</refname> + <refname>sd_journal_seek_realtime_usec</refname> + <refname>sd_journal_seek_cursor</refname> + <refpurpose>Seek to a position in the + journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_seek_head</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_seek_tail</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_seek_monotonic_usec</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>sd_id128_t <parameter>boot_id</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_seek_realtime_usec</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_journal_seek_cursor</function></funcdef> + <paramdef>sd_journal *<parameter>j</parameter></paramdef> + <paramdef>const char *<parameter>cursor</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_seek_head()</function> seeks to the + beginning of the journal, i.e. the oldest available entry.</para> + + <para>Similarly, <function>sd_journal_seek_tail()</function> may + be used to seek to the end of the journal, i.e. the most recent + available entry.</para> + + <para><function>sd_journal_seek_monotonic_usec()</function> seeks + to the entry with the specified monotonic timestamp, i.e. + <constant>CLOCK_MONOTONIC</constant>. Since monotonic time + restarts on every reboot a boot ID needs to be specified as + well.</para> + + <para><function>sd_journal_seek_realtime_usec()</function> seeks + to the entry with the specified realtime (wallclock) timestamp, + i.e. <constant>CLOCK_REALTIME</constant>. Note that the realtime + clock is not necessarily monotonic. If a realtime timestamp is + ambiguous, it is not defined which position is sought to.</para> + + <para><function>sd_journal_seek_cursor()</function> seeks to the + entry located at the specified cursor string. For details on + cursors, see + <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + If no entry matching the specified cursor is found the call will + seek to the next closest entry (in terms of time) instead. To + verify whether the newly selected entry actually matches the + cursor, use + <citerefentry><refentrytitle>sd_journal_test_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>Note that these calls do not actually make any entry the new + current entry, this needs to be done in a separate step with a + subsequent + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + invocation (or a similar call). Only then, entry data may be + retrieved via + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + If no entry exists that matches exactly the specified seek + address, the next closest is sought to. If + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> + is used, the closest following entry will be sought to, if + <citerefentry><refentrytitle>sd_journal_previous</refentrytitle><manvolnum>3</manvolnum></citerefentry> + is used the closest preceding entry is sought to.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The functions return 0 on success or a negative errno-style + error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_seek_head()</function>, + <function>sd_journal_seek_tail()</function>, + <function>sd_journal_seek_monotonic_usec()</function>, + <function>sd_journal_seek_realtime_usec()</function>, + and <function>sd_journal_seek_cursor()</function> + interfaces are available as a shared library, which can + be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_journal_stream_fd.xml b/man/sd_journal_stream_fd.xml index 045b3fb21e..2ea7731b48 100644 --- a/man/sd_journal_stream_fd.xml +++ b/man/sd_journal_stream_fd.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,108 +23,101 @@ <refentry id="sd_journal_stream_fd"> - <refentryinfo> - <title>sd_journal_stream_fd</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_journal_stream_fd</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_journal_stream_fd</refname> - <refpurpose>Create log stream file descriptor to the journal</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_journal_stream_fd</function></funcdef> - <paramdef>const char *<parameter>identifier</parameter></paramdef> - <paramdef>int <parameter>priority</parameter></paramdef> - <paramdef>int <parameter>level_prefix</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_journal_stream_fd()</function> may - be used to create a log stream file descriptor. Log - messages written to this file descriptor as simple - newline-separated text strings are written to the - journal. This file descriptor can be used internally - by applications or be made standard output or standard - error of other processes executed.</para> - - <para><function>sd_journal_stream_fd()</function> - takes a short program identifier string as first - argument, which will be written to the journal as - _SYSLOG_IDENTIFIER= field for each log entry (see - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for more information). The second argument shall be - the default priority level for all messages. The - priority level is one of <constant>LOG_EMERG</constant>, - <constant>LOG_ALERT</constant>, - <constant>LOG_CRIT</constant>, - <constant>LOG_ERR</constant>, - <constant>LOG_WARNING</constant>, - <constant>LOG_NOTICE</constant>, - <constant>LOG_INFO</constant>, - <constant>LOG_DEBUG</constant>, as defined in - <filename>syslog.h</filename>, see - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details. The third argument is a boolean: if true - kernel-style log level prefixes (such as - <constant>SD_WARNING</constant>) are interpreted, see - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information.</para> - - <para>It is recommended that applications log UTF-8 - messages only with this API, but this is not - enforced.</para> - - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>The call returns a valid write-only file descriptor on success or a - negative errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_journal_stream_fd()</function> - interface is available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>Creating a log stream suitable for - <citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>:</para> - - <programlisting>#include <syslog.h> + <refentryinfo> + <title>sd_journal_stream_fd</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_journal_stream_fd</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_journal_stream_fd</refname> + <refpurpose>Create log stream file descriptor to the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_journal_stream_fd</function></funcdef> + <paramdef>const char *<parameter>identifier</parameter></paramdef> + <paramdef>int <parameter>priority</parameter></paramdef> + <paramdef>int <parameter>level_prefix</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_journal_stream_fd()</function> may be used to + create a log stream file descriptor. Log messages written to this + file descriptor as simple newline-separated text strings are + written to the journal. This file descriptor can be used + internally by applications or be made standard output or standard + error of other processes executed.</para> + + <para><function>sd_journal_stream_fd()</function> takes a short + program identifier string as first argument, which will be written + to the journal as _SYSLOG_IDENTIFIER= field for each log entry + (see + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for more information). The second argument shall be the default + priority level for all messages. The priority level is one of + <constant>LOG_EMERG</constant>, <constant>LOG_ALERT</constant>, + <constant>LOG_CRIT</constant>, <constant>LOG_ERR</constant>, + <constant>LOG_WARNING</constant>, <constant>LOG_NOTICE</constant>, + <constant>LOG_INFO</constant>, <constant>LOG_DEBUG</constant>, as + defined in <filename>syslog.h</filename>, see + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details. The third argument is a boolean: if true kernel-style + log level prefixes (such as <constant>SD_WARNING</constant>) are + interpreted, see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information.</para> + + <para>It is recommended that applications log UTF-8 messages only + with this API, but this is not enforced.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The call returns a valid write-only file descriptor on + success or a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_journal_stream_fd()</function> interface is + available as a shared library, which can be compiled and linked to + with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Creating a log stream suitable for + <citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>:</para> + + <programlisting>#include <syslog.h> #include <stdio.h> #include <string.h> #include <unistd.h> @@ -132,39 +125,39 @@ #include <systemd/sd-daemon.h> int main(int argc, char *argv[]) { - int fd; - FILE *log; - fd = sd_journal_stream_fd("test", LOG_INFO, 1); - if (fd < 0) { - fprintf(stderr, "Failed to create stream fd: %s\n", strerror(-fd)); - return 1; - } - log = fdopen(fd, "w"); - if (!log) { - fprintf(stderr, "Failed to create file object: %m\n"); - close(fd); - return 1; - } - fprintf(log, "Hello World!\n"); - fprintf(log, SD_WARNING "This is a warning!\n"); - fclose(log); - return 0; + int fd; + FILE *log; + fd = sd_journal_stream_fd("test", LOG_INFO, 1); + if (fd < 0) { + fprintf(stderr, "Failed to create stream fd: %s\n", strerror(-fd)); + return 1; + } + log = fdopen(fd, "w"); + if (!log) { + fprintf(stderr, "Failed to create file object: %m\n"); + close(fd); + return 1; + } + fprintf(log, "Hello World!\n"); + fprintf(log, SD_WARNING "This is a warning!\n"); + fclose(log); + return 0; }</programlisting> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>fprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index 4377745634..9b9705eb2e 100644 --- a/man/sd_listen_fds.xml +++ b/man/sd_listen_fds.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,164 +22,155 @@ --> <refentry id="sd_listen_fds" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_listen_fds</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_listen_fds</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_listen_fds</refname> - <refname>SD_LISTEN_FDS_START</refname> - <refpurpose>Check for file descriptors passed by the system manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> - - <funcsynopsisinfo>#define SD_LISTEN_FDS_START 3</funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_listen_fds</function></funcdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_listen_fds()</function> shall be - called by a daemon to check for file descriptors - passed by the init system as part of the socket-based - activation logic.</para> - - <para>If the <parameter>unset_environment</parameter> - parameter is non-zero, - <function>sd_listen_fds()</function> will unset the - <varname>$LISTEN_FDS</varname> and <varname>$LISTEN_PID</varname> - environment variables before returning (regardless of - whether the function call itself succeeded or - not). Further calls to - <function>sd_listen_fds()</function> will then fail, - but the variables are no longer inherited by child - processes.</para> - - <para>If a daemon receives more than one file - descriptor, they will be passed in the same order as - configured in the systemd socket unit file (see - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). Nonetheless, it is recommended to verify - the correct socket types before using them. To - simplify this checking, the functions - <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry> - are provided. In order to maximize flexibility, it is - recommended to make these checks as loose as possible - without allowing incorrect setups. i.e. often, the - actual port number a socket is bound to matters little - for the service to work, hence it should not be - verified. On the other hand, whether a socket is a - datagram or stream socket matters a lot for the most - common program logics and should be checked.</para> - - <para>This function call will set the FD_CLOEXEC flag - for all passed file descriptors to avoid further - inheritance to children of the calling process.</para> - - <para>If multiple socket units activate the same - service the order of the file descriptors passed to - its main process is undefined. If additional file - descriptors have been passed to the service manager - using - <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s - <literal>FDSTORE=1</literal> messages, these file - descriptors are passed last, in arbitrary order, and - with duplicates removed.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On failure, this call returns a negative - errno-style error code. If - <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> - was not set or was not correctly set for this daemon and - hence no file descriptors were received, 0 is - returned. Otherwise, the number of file descriptors - passed is returned. The application may find them - starting with file descriptor SD_LISTEN_FDS_START, - i.e. file descriptor 3.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - - <para>Internally, this function checks whether the - <varname>$LISTEN_PID</varname> environment variable - equals the daemon PID. If not, it returns - immediately. Otherwise, it parses the number passed in - the <varname>$LISTEN_FDS</varname> environment - variable, then sets the FD_CLOEXEC flag for the parsed - number of file descriptors starting from - SD_LISTEN_FDS_START. Finally, it returns the parsed - number.</para> - </refsect1> - - <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$LISTEN_PID</varname></term> - <term><varname>$LISTEN_FDS</varname></term> - - <listitem><para>Set by the init system - for supervised processes that use - socket-based activation. This - environment variable specifies the - data - <function>sd_listen_fds()</function> - parses. See above for - details.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_listen_fds</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_listen_fds</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_listen_fds</refname> + <refname>SD_LISTEN_FDS_START</refname> + <refpurpose>Check for file descriptors passed by the system manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcsynopsisinfo>#define SD_LISTEN_FDS_START 3</funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_listen_fds</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_listen_fds()</function> shall be called by a + daemon to check for file descriptors passed by the init system as + part of the socket-based activation logic.</para> + + <para>If the <parameter>unset_environment</parameter> parameter is + non-zero, <function>sd_listen_fds()</function> will unset the + <varname>$LISTEN_FDS</varname> and <varname>$LISTEN_PID</varname> + environment variables before returning (regardless of whether the + function call itself succeeded or not). Further calls to + <function>sd_listen_fds()</function> will then fail, but the + variables are no longer inherited by child processes.</para> + + <para>If a daemon receives more than one file descriptor, they + will be passed in the same order as configured in the systemd + socket unit file (see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Nonetheless, it is recommended to verify the correct + socket types before using them. To simplify this checking, the + functions + <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry> + are provided. In order to maximize flexibility, it is recommended + to make these checks as loose as possible without allowing + incorrect setups. i.e. often, the actual port number a socket is + bound to matters little for the service to work, hence it should + not be verified. On the other hand, whether a socket is a datagram + or stream socket matters a lot for the most common program logics + and should be checked.</para> + + <para>This function call will set the FD_CLOEXEC flag for all + passed file descriptors to avoid further inheritance to children + of the calling process.</para> + + <para>If multiple socket units activate the same service the order + of the file descriptors passed to its main process is undefined. + If additional file descriptors have been passed to the service + manager using + <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s + <literal>FDSTORE=1</literal> messages, these file descriptors are + passed last, in arbitrary order, and with duplicates + removed.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, this call returns a negative errno-style error + code. If + <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> was + not set or was not correctly set for this daemon and hence no file + descriptors were received, 0 is returned. Otherwise, the number of + file descriptors passed is returned. The application may find them + starting with file descriptor SD_LISTEN_FDS_START, i.e. file + descriptor 3.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + + <para>Internally, this function checks whether the + <varname>$LISTEN_PID</varname> environment variable equals the + daemon PID. If not, it returns immediately. Otherwise, it parses + the number passed in the <varname>$LISTEN_FDS</varname> + environment variable, then sets the FD_CLOEXEC flag for the parsed + number of file descriptors starting from SD_LISTEN_FDS_START. + Finally, it returns the parsed number.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDS</varname></term> + + <listitem><para>Set by the init system + for supervised processes that use + socket-based activation. This + environment variable specifies the + data + <function>sd_listen_fds()</function> + parses. See above for + details.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index ba6623826f..a7b47a3207 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,223 +23,211 @@ <refentry id="sd_login_monitor_new" conditional='HAVE_PAM'> - <refentryinfo> - <title>sd_login_monitor_new</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_login_monitor_new</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_login_monitor_new</refname> - <refname>sd_login_monitor_unref</refname> - <refname>sd_login_monitor_flush</refname> - <refname>sd_login_monitor_get_fd</refname> - <refname>sd_login_monitor_get_events</refname> - <refname>sd_login_monitor_get_timeout</refname> - <refname>sd_login_monitor</refname> - <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_new</function></funcdef> - <paramdef>const char *<parameter>category</parameter></paramdef> - <paramdef>sd_login_monitor **<parameter>ret</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>sd_login_monitor *<function>sd_login_monitor_unref</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_flush</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_get_events</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_login_monitor_new()</function> may - be used to monitor login sessions, users, seats, and - virtual machines/containers. Via a monitor object a - file descriptor can be integrated into an application - defined event loop which is woken up each time a user - logs in, logs out or a seat is added or removed, or a - session, user, seat or virtual machine/container - changes state otherwise. The first parameter takes a - string which can be <literal>seat</literal> (to get - only notifications about seats being added, removed or - changed), <literal>session</literal> (to get only - notifications about sessions being created or removed - or changed), <literal>uid</literal> (to get only - notifications when a user changes state in respect to - logins) or <literal>machine</literal> (to get only - notifications when a virtual machine or container is - started or stopped). If notifications shall be - generated in all these conditions, <constant>NULL</constant> may be - passed. Note that in the future additional categories - may be defined. The second parameter returns a monitor - object and needs to be freed with the - <function>sd_login_monitor_unref()</function> call - after use.</para> - - <para><function>sd_login_monitor_unref()</function> - may be used to destroy a monitor object. Note that - this will invalidate any file descriptor returned by - <function>sd_login_monitor_get_fd()</function>.</para> - - <para><function>sd_login_monitor_flush()</function> - may be used to reset the wakeup state of the monitor - object. Whenever an event causes the monitor to wake - up the event loop via the file descriptor this - function needs to be called to reset the wake-up - state. If this call is not invoked, the file descriptor - will immediately wake up the event loop again.</para> - - <para><function>sd_login_monitor_get_fd()</function> - may be used to retrieve the file descriptor of the - monitor object that may be integrated in an - application defined event loop, based around - <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry> - or a similar interface. The application should include - the returned file descriptor as wake-up source for the - events mask returned by - <function>sd_login_monitor_get_events()</function>. It - should pass a timeout value as returned by - <function>sd_login_monitor_get_timeout()</function>. Whenever - a wake-up is triggered the file descriptor needs to be - reset via - <function>sd_login_monitor_flush()</function>. An - application needs to reread the login state with a - function like - <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or similar to determine what changed.</para> - - <para><function>sd_login_monitor_get_events()</function> - will return the <function>poll()</function> mask to - wait for. This function will return a combination of - <constant>POLLIN</constant>, <constant>POLLOUT</constant> - and similar to fill into the - <literal>.events</literal> field of <varname>struct - pollfd</varname>.</para> - - <para><function>sd_login_monitor_get_timeout()</function> - will return a timeout value for usage in - <function>poll()</function>. This returns a value in - microseconds since the epoch of <constant>CLOCK_MONOTONIC</constant> - for timing out <function>poll()</function> in - <varname>timeout_usec</varname>. See - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details about - <constant>CLOCK_MONOTONIC</constant>. If there is no - timeout to wait for this will fill in - <constant>(uint64_t) -1</constant> instead. Note that - <function>poll()</function> takes a relative timeout - in milliseconds rather than an absolute timeout in - microseconds. To convert the absolute 'us' timeout into - relative 'ms', use code like the following:</para> - - <programlisting>uint64_t t; + <refentryinfo> + <title>sd_login_monitor_new</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_login_monitor_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_login_monitor_new</refname> + <refname>sd_login_monitor_unref</refname> + <refname>sd_login_monitor_flush</refname> + <refname>sd_login_monitor_get_fd</refname> + <refname>sd_login_monitor_get_events</refname> + <refname>sd_login_monitor_get_timeout</refname> + <refname>sd_login_monitor</refname> + <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_new</function></funcdef> + <paramdef>const char *<parameter>category</parameter></paramdef> + <paramdef>sd_login_monitor **<parameter>ret</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_login_monitor *<function>sd_login_monitor_unref</function></funcdef> + <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_flush</function></funcdef> + <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef> + <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_get_events</function></funcdef> + <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef> + <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> + <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_login_monitor_new()</function> may be used to + monitor login sessions, users, seats, and virtual + machines/containers. Via a monitor object a file descriptor can be + integrated into an application defined event loop which is woken + up each time a user logs in, logs out or a seat is added or + removed, or a session, user, seat or virtual machine/container + changes state otherwise. The first parameter takes a string which + can be <literal>seat</literal> (to get only notifications about + seats being added, removed or changed), <literal>session</literal> + (to get only notifications about sessions being created or removed + or changed), <literal>uid</literal> (to get only notifications + when a user changes state in respect to logins) or + <literal>machine</literal> (to get only notifications when a + virtual machine or container is started or stopped). If + notifications shall be generated in all these conditions, + <constant>NULL</constant> may be passed. Note that in the future + additional categories may be defined. The second parameter returns + a monitor object and needs to be freed with the + <function>sd_login_monitor_unref()</function> call after + use.</para> + + <para><function>sd_login_monitor_unref()</function> may be used to + destroy a monitor object. Note that this will invalidate any file + descriptor returned by + <function>sd_login_monitor_get_fd()</function>.</para> + + <para><function>sd_login_monitor_flush()</function> may be used to + reset the wakeup state of the monitor object. Whenever an event + causes the monitor to wake up the event loop via the file + descriptor this function needs to be called to reset the wake-up + state. If this call is not invoked, the file descriptor will + immediately wake up the event loop again.</para> + + <para><function>sd_login_monitor_get_fd()</function> may be used + to retrieve the file descriptor of the monitor object that may be + integrated in an application defined event loop, based around + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry> + or a similar interface. The application should include the + returned file descriptor as wake-up source for the events mask + returned by <function>sd_login_monitor_get_events()</function>. It + should pass a timeout value as returned by + <function>sd_login_monitor_get_timeout()</function>. Whenever a + wake-up is triggered the file descriptor needs to be reset via + <function>sd_login_monitor_flush()</function>. An application + needs to reread the login state with a function like + <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or similar to determine what changed.</para> + + <para><function>sd_login_monitor_get_events()</function> will + return the <function>poll()</function> mask to wait for. This + function will return a combination of <constant>POLLIN</constant>, + <constant>POLLOUT</constant> and similar to fill into the + <literal>.events</literal> field of <varname>struct + pollfd</varname>.</para> + + <para><function>sd_login_monitor_get_timeout()</function> will + return a timeout value for usage in <function>poll()</function>. + This returns a value in microseconds since the epoch of + <constant>CLOCK_MONOTONIC</constant> for timing out + <function>poll()</function> in <varname>timeout_usec</varname>. + See + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details about <constant>CLOCK_MONOTONIC</constant>. If there + is no timeout to wait for this will fill in <constant>(uint64_t) + -1</constant> instead. Note that <function>poll()</function> takes + a relative timeout in milliseconds rather than an absolute timeout + in microseconds. To convert the absolute 'us' timeout into + relative 'ms', use code like the following:</para> + + <programlisting>uint64_t t; int msec; sd_login_monitor_get_timeout(m, &t); if (t == (uint64_t) -1) - msec = -1; + msec = -1; else { - struct timespec ts; - uint64_t n; - clock_getttime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; }</programlisting> - <para>The code above does not do any error checking - for brevity's sake. The calculated <varname>msec</varname> - integer can be passed directly as - <function>poll()</function>'s timeout - parameter.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>sd_login_monitor_new()</function>, - <function>sd_login_monitor_flush()</function> and - <function>sd_login_monitor_get_timeout()</function> - return 0 or a positive integer. On success, - <function>sd_login_monitor_get_fd()</function> returns - a Unix file descriptor. On success, - <function>sd_login_monitor_get_events()</function> - returns a combination of <constant>POLLIN</constant>, - <constant>POLLOUT</constant> and suchlike. On failure, - these calls return a negative errno-style error - code.</para> - - <para><function>sd_login_monitor_unref()</function> - always returns <constant>NULL</constant>.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_login_monitor_new()</function>, - <function>sd_login_monitor_unref()</function>, - <function>sd_login_monitor_flush()</function>, - <function>sd_login_monitor_get_fd()</function>, - <function>sd_login_monitor_get_events()</function> and - <function>sd_login_monitor_get_timeout()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> + <para>The code above does not do any error checking for brevity's + sake. The calculated <varname>msec</varname> integer can be passed + directly as <function>poll()</function>'s timeout + parameter.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>sd_login_monitor_new()</function>, + <function>sd_login_monitor_flush()</function> and + <function>sd_login_monitor_get_timeout()</function> + return 0 or a positive integer. On success, + <function>sd_login_monitor_get_fd()</function> returns + a Unix file descriptor. On success, + <function>sd_login_monitor_get_events()</function> + returns a combination of <constant>POLLIN</constant>, + <constant>POLLOUT</constant> and suchlike. On failure, + these calls return a negative errno-style error + code.</para> + + <para><function>sd_login_monitor_unref()</function> + always returns <constant>NULL</constant>.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_login_monitor_new()</function>, + <function>sd_login_monitor_unref()</function>, + <function>sd_login_monitor_flush()</function>, + <function>sd_login_monitor_get_fd()</function>, + <function>sd_login_monitor_get_events()</function> and + <function>sd_login_monitor_get_timeout()</function> + interfaces are available as a shared library, which can be + compiled and linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_machine_get_class.xml b/man/sd_machine_get_class.xml index d06b75231a..5b881ccea1 100644 --- a/man/sd_machine_get_class.xml +++ b/man/sd_machine_get_class.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,104 +23,101 @@ <refentry id="sd_machine_get_class"> - <refentryinfo> - <title>sd_machine_get_class</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_machine_get_class</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_machine_get_class</refname> - <refname>sd_machine_get_ifindices</refname> - <refpurpose>Determine the class and network interface - indices of a locally running virtual machine or - container.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_machine_get_class</function></funcdef> - <paramdef>const char* <parameter>machine</parameter></paramdef> - <paramdef>char *<parameter>class</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_machine_get_ifindices</function></funcdef> - <paramdef>const char* <parameter>machine</parameter></paramdef> - <paramdef>int **<parameter>ifindices</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_machine_get_class()</function> may - be used to determine the class of a locally running - virtual machine or container that is registered with - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The - string returned is either <literal>vm</literal> or - <literal>container</literal>. The returned string - needs to be freed with the libc <citerefentry - project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_machine_get_ifindices()</function> - may be used to determine the numeric indices of the - network interfaces on the host that are pointing - towards the specified locally running virtual machine - or container that is registered with - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The - returned array needs to be freed with the libc - <citerefentry - project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, these calls return 0 or a positive - integer. On failure, these calls return a negative - errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_machine_get_class()</function> and - <function>sd_machine_get_ifindices()</function> interfaces are - available as a shared library, which can be compiled - and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_pid_get_machine_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_machine_get_class</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_machine_get_class</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_machine_get_class</refname> + <refname>sd_machine_get_ifindices</refname> + <refpurpose>Determine the class and network interface indices of a + locally running virtual machine or container.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_machine_get_class</function></funcdef> + <paramdef>const char* <parameter>machine</parameter></paramdef> + <paramdef>char *<parameter>class</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_machine_get_ifindices</function></funcdef> + <paramdef>const char* <parameter>machine</parameter></paramdef> + <paramdef>int **<parameter>ifindices</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_machine_get_class()</function> may be used to + determine the class of a locally running virtual machine or + container that is registered with + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + The string returned is either <literal>vm</literal> or + <literal>container</literal>. The returned string needs to be + freed with the libc <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_machine_get_ifindices()</function> may be used + to determine the numeric indices of the network interfaces on the + host that are pointing towards the specified locally running + virtual machine or container that is registered with + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + The returned array needs to be freed with the libc <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_machine_get_class()</function> and + <function>sd_machine_get_ifindices()</function> interfaces are + available as a shared library, which can be compiled and linked to + with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_pid_get_machine_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_notify.xml b/man/sd_notify.xml index b7c33da63a..87e59c9cc2 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,407 +22,355 @@ --> <refentry id="sd_notify" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_notify</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_notify</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_notify</refname> - <refname>sd_notifyf</refname> - <refname>sd_pid_notify</refname> - <refname>sd_pid_notifyf</refname> - <refname>sd_pid_notify_with_fds</refname> - <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_notify</function></funcdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>const char *<parameter>state</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_notifyf</function></funcdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>const char *<parameter>format</parameter></paramdef> - <paramdef>...</paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_notify</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>const char *<parameter>state</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_notifyf</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>const char *<parameter>format</parameter></paramdef> - <paramdef>...</paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_notify_with_fds</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>const char *<parameter>state</parameter></paramdef> - <paramdef>const int *<parameter>fds</parameter></paramdef> - <paramdef>unsigned <parameter>n_fds</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para><function>sd_notify()</function> may be called - by a service to notify the service manager about - state changes. It can be used to send arbitrary - information, encoded in an environment-block-like - string. Most importantly it can be used for start-up - completion notification.</para> - - <para>If the <parameter>unset_environment</parameter> - parameter is non-zero, <function>sd_notify()</function> - will unset the <varname>$NOTIFY_SOCKET</varname> - environment variable before returning (regardless of - whether the function call itself succeeded or - not). Further calls to - <function>sd_notify()</function> will then fail, but - the variable is no longer inherited by child - processes.</para> - - <para>The <parameter>state</parameter> parameter - should contain a newline-separated list of variable - assignments, similar in style to an environment - block. A trailing newline is implied if none is - specified. The string may contain any kind of variable - assignments, but the following shall be considered - well-known:</para> - - <variablelist> - <varlistentry> - <term>READY=1</term> - - <listitem><para>Tells the service - manager that service startup is - finished. This is only used by systemd - if the service definition file has - Type=notify set. Since there is little - value in signaling non-readiness, the - only value services should send is - <literal>READY=1</literal> - (i.e. <literal>READY=0</literal> is - not defined).</para></listitem> - </varlistentry> - - <varlistentry> - <term>RELOADING=1</term> - - <listitem><para>Tells the service manager - that the service is reloading its - configuration. This is useful to allow - the service manager to track the service's - internal state, and present it to the - user. Note that a service that sends - this notification must also send a - <literal>READY=1</literal> - notification when it completed - reloading its - configuration.</para></listitem> - </varlistentry> - - <varlistentry> - <term>STOPPING=1</term> - - <listitem><para>Tells the service manager - that the service is beginning its - shutdown. This is useful to allow the - service manager to track the service's - internal state, and present it to the - user.</para></listitem> - </varlistentry> - - <varlistentry> - <term>STATUS=...</term> - - <listitem><para>Passes a single-line - UTF-8 status string back to the service manager - that describes the service state. This - is free-form and can be used for - various purposes: general state - feedback, fsck-like programs could - pass completion percentages and - failing programs could pass a human - readable error message. Example: - <literal>STATUS=Completed 66% of file - system - check...</literal></para></listitem> - </varlistentry> - - <varlistentry> - <term>ERRNO=...</term> - - <listitem><para>If a service fails, the - errno-style error code, formatted as - string. Example: <literal>ERRNO=2</literal> for - ENOENT.</para></listitem> - </varlistentry> - - <varlistentry> - <term>BUSERROR=...</term> - - <listitem><para>If a service fails, the - D-Bus error-style error code. Example: - <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem> - </varlistentry> - - <varlistentry> - <term>MAINPID=...</term> - - <listitem><para>The main process ID (PID) of the - service, in case the service manager did - not fork off the process - itself. Example: - <literal>MAINPID=4711</literal></para></listitem> - </varlistentry> - - <varlistentry> - <term>WATCHDOG=1</term> - - <listitem><para>Tells the service manager to - update the watchdog timestamp. This is - the keep-alive ping that services need - to issue in regular intervals if - <varname>WatchdogSec=</varname> is - enabled for it. See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information how to enable this - functionality and - <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for the details of how the service can - check if the the watchdog is enabled. - </para></listitem> - </varlistentry> - - - <varlistentry> - <term>FDSTORE=1</term> - - <listitem><para>Stores additional file - descriptors in the service - manager. File descriptors sent this - way will be maintained per-service by - the service manager and be passed - again using the usual file descriptor - passing logic on the next invocation - of the service (see - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>). This - is useful for implementing service - restart schemes where services - serialize their state to - <filename>/run</filename>, push their - file descriptors to the system - manager, and are then restarted, - retrieving their state again via - socket passing and - <filename>/run</filename>. Note that - the service manager will accept - messages for a service only if - <varname>FileDescriptorStoreMax=</varname> - is set to non-zero for it (defaults to - zero). See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Multiple arrays of file - descriptors may be sent in separate - messages, in which case the arrays are - combined. Note that the service - manager removes duplicate file - descriptors before passing them to the - service. Use - <function>sd_pid_notify_with_fds()</function> - to send messages with - <literal>FDSTORE=1</literal>, see - below.</para></listitem> - </varlistentry> - - </variablelist> - - <para>It is recommended to prefix variable names that - are not listed above with <varname>X_</varname> to - avoid namespace clashes.</para> - - <para>Note that systemd will accept status data sent - from a service only if the - <varname>NotifyAccess=</varname> option is correctly - set in the service definition file. See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - - <para><function>sd_notifyf()</function> is similar to - <function>sd_notify()</function> but takes a - <function>printf()</function>-like format string plus - arguments.</para> - - <para><function>sd_pid_notify()</function> and - <function>sd_pid_notifyf()</function> are similar to - <function>sd_notify()</function> and - <function>sd_notifyf()</function> but take a process - ID (PID) to use as originating PID for the message as - first argument. This is useful to send notification - messages on behalf of other processes, provided the - appropriate privileges are available. If the PID - argument is specified as 0 the process ID of the - calling process is used, in which case the calls are - fully equivalent to <function>sd_notify()</function> - and <function>sd_notifyf()</function>.</para> - - <para><function>sd_pid_notify_with_fds()</function> is - similar to <function>sd_pid_notify()</function> but - takes an additional array of file descriptors. These - file descriptors are sent along the notification - message to the service manager. This is particularly - useful for sending <literal>FDSTORE=1</literal> - messages, as described above. The additional arguments - are a pointer to the file descriptor array plus the - number of file descriptors in the array. If the number - of file descriptors is passed as 0, the call is fully - equivalent to <function>sd_pid_notify()</function>, - i.e. no file descriptors are passed. Note that sending - file descriptors to the service manager on messages - that do not expect them (i.e. without - <literal>FDSTORE=1</literal>) they are immediately - closed on reception.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On failure, these calls return a negative - errno-style error code. If - <varname>$NOTIFY_SOCKET</varname> was not set and - hence no status data could be sent, 0 is returned. If - the status was sent, these functions return with a - positive return value. In order to support both, init - systems that implement this scheme and those which - do not, it is generally recommended to ignore the return - value of this call.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - - <para>Internally, these functions send a single - datagram with the state string as payload to the - <constant>AF_UNIX</constant> socket referenced in the - <varname>$NOTIFY_SOCKET</varname> environment - variable. If the first character of - <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the string is - understood as Linux abstract namespace socket. The - datagram is accompanied by the process credentials of - the sending service, using SCM_CREDENTIALS.</para> - </refsect1> - - <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$NOTIFY_SOCKET</varname></term> - - <listitem><para>Set by the service manager - for supervised processes for status - and start-up completion - notification. This environment variable - specifies the socket - <function>sd_notify()</function> talks - to. See above for details.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Start-up Notification</title> - - <para>When a service finished starting up, it - might issue the following call to notify - the service manager:</para> - - <programlisting>sd_notify(0, "READY=1");</programlisting> - </example> - - <example> - <title>Extended Start-up Notification</title> - - <para>A service could send the following after - completing initialization:</para> - - <programlisting>sd_notifyf(0, "READY=1\n" - "STATUS=Processing requests...\n" - "MAINPID=%lu", - (unsigned long) getpid());</programlisting> - </example> - - <example> - <title>Error Cause Notification</title> - - <para>A service could send the following shortly before exiting, on failure:</para> - - <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n" - "ERRNO=%i", - strerror(errno), - errno);</programlisting> - </example> - - <example> - <title>Store a File Descriptor in the Service Manager</title> - - <para>To store an open file descriptor in the - service manager, in order to continue - operation after a service restart without - losing state use - <literal>FDSTORE=1</literal>:</para> - - <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);</programlisting> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_notify</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_notify</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_notify</refname> + <refname>sd_notifyf</refname> + <refname>sd_pid_notify</refname> + <refname>sd_pid_notifyf</refname> + <refname>sd_pid_notify_with_fds</refname> + <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_notify</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>state</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_notifyf</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_notify</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>state</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_notifyf</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_notify_with_fds</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>state</parameter></paramdef> + <paramdef>const int *<parameter>fds</parameter></paramdef> + <paramdef>unsigned <parameter>n_fds</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para><function>sd_notify()</function> may be called by a service + to notify the service manager about state changes. It can be used + to send arbitrary information, encoded in an + environment-block-like string. Most importantly it can be used for + start-up completion notification.</para> + + <para>If the <parameter>unset_environment</parameter> parameter is + non-zero, <function>sd_notify()</function> will unset the + <varname>$NOTIFY_SOCKET</varname> environment variable before + returning (regardless of whether the function call itself + succeeded or not). Further calls to + <function>sd_notify()</function> will then fail, but the variable + is no longer inherited by child processes.</para> + + <para>The <parameter>state</parameter> parameter should contain a + newline-separated list of variable assignments, similar in style + to an environment block. A trailing newline is implied if none is + specified. The string may contain any kind of variable + assignments, but the following shall be considered + well-known:</para> + + <variablelist> + <varlistentry> + <term>READY=1</term> + + <listitem><para>Tells the service manager that service startup + is finished. This is only used by systemd if the service + definition file has Type=notify set. Since there is little + value in signaling non-readiness, the only value services + should send is <literal>READY=1</literal> (i.e. + <literal>READY=0</literal> is not defined).</para></listitem> + </varlistentry> + + <varlistentry> + <term>RELOADING=1</term> + + <listitem><para>Tells the service manager that the service is + reloading its configuration. This is useful to allow the + service manager to track the service's internal state, and + present it to the user. Note that a service that sends this + notification must also send a <literal>READY=1</literal> + notification when it completed reloading its + configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <term>STOPPING=1</term> + + <listitem><para>Tells the service manager that the service is + beginning its shutdown. This is useful to allow the service + manager to track the service's internal state, and present it + to the user.</para></listitem> + </varlistentry> + + <varlistentry> + <term>STATUS=...</term> + + <listitem><para>Passes a single-line UTF-8 status string back + to the service manager that describes the service state. This + is free-form and can be used for various purposes: general + state feedback, fsck-like programs could pass completion + percentages and failing programs could pass a human readable + error message. Example: <literal>STATUS=Completed 66% of file + system check...</literal></para></listitem> + </varlistentry> + + <varlistentry> + <term>ERRNO=...</term> + + <listitem><para>If a service fails, the errno-style error + code, formatted as string. Example: <literal>ERRNO=2</literal> + for ENOENT.</para></listitem> + </varlistentry> + + <varlistentry> + <term>BUSERROR=...</term> + + <listitem><para>If a service fails, the D-Bus error-style + error code. Example: + <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem> + </varlistentry> + + <varlistentry> + <term>MAINPID=...</term> + + <listitem><para>The main process ID (PID) of the service, in + case the service manager did not fork off the process itself. + Example: <literal>MAINPID=4711</literal></para></listitem> + </varlistentry> + + <varlistentry> + <term>WATCHDOG=1</term> + + <listitem><para>Tells the service manager to update the + watchdog timestamp. This is the keep-alive ping that services + need to issue in regular intervals if + <varname>WatchdogSec=</varname> is enabled for it. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information how to enable this functionality and + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for the details of how the service can check if the the + watchdog is enabled. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>FDSTORE=1</term> + + <listitem><para>Stores additional file descriptors in the + service manager. File descriptors sent this way will be + maintained per-service by the service manager and be passed + again using the usual file descriptor passing logic on the + next invocation of the service (see + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>). + This is useful for implementing service restart schemes where + services serialize their state to <filename>/run</filename>, + push their file descriptors to the system manager, and are + then restarted, retrieving their state again via socket + passing and <filename>/run</filename>. Note that the service + manager will accept messages for a service only if + <varname>FileDescriptorStoreMax=</varname> is set to non-zero + for it (defaults to zero). See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Multiple arrays of file descriptors may be sent + in separate messages, in which case the arrays are combined. + Note that the service manager removes duplicate file + descriptors before passing them to the service. Use + <function>sd_pid_notify_with_fds()</function> to send messages + with <literal>FDSTORE=1</literal>, see + below.</para></listitem> + </varlistentry> + + </variablelist> + + <para>It is recommended to prefix variable names that are not + listed above with <varname>X_</varname> to avoid namespace + clashes.</para> + + <para>Note that systemd will accept status data sent from a + service only if the <varname>NotifyAccess=</varname> option is + correctly set in the service definition file. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + + <para><function>sd_notifyf()</function> is similar to + <function>sd_notify()</function> but takes a + <function>printf()</function>-like format string plus + arguments.</para> + + <para><function>sd_pid_notify()</function> and + <function>sd_pid_notifyf()</function> are similar to + <function>sd_notify()</function> and + <function>sd_notifyf()</function> but take a process ID (PID) to + use as originating PID for the message as first argument. This is + useful to send notification messages on behalf of other processes, + provided the appropriate privileges are available. If the PID + argument is specified as 0 the process ID of the calling process + is used, in which case the calls are fully equivalent to + <function>sd_notify()</function> and + <function>sd_notifyf()</function>.</para> + + <para><function>sd_pid_notify_with_fds()</function> is similar to + <function>sd_pid_notify()</function> but takes an additional array + of file descriptors. These file descriptors are sent along the + notification message to the service manager. This is particularly + useful for sending <literal>FDSTORE=1</literal> messages, as + described above. The additional arguments are a pointer to the + file descriptor array plus the number of file descriptors in the + array. If the number of file descriptors is passed as 0, the call + is fully equivalent to <function>sd_pid_notify()</function>, i.e. + no file descriptors are passed. Note that sending file descriptors + to the service manager on messages that do not expect them (i.e. + without <literal>FDSTORE=1</literal>) they are immediately closed + on reception.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, these calls return a negative errno-style error + code. If <varname>$NOTIFY_SOCKET</varname> was not set and hence + no status data could be sent, 0 is returned. If the status was + sent, these functions return with a positive return value. In + order to support both, init systems that implement this scheme and + those which do not, it is generally recommended to ignore the + return value of this call.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + + <para>Internally, these functions send a single datagram with the + state string as payload to the <constant>AF_UNIX</constant> socket + referenced in the <varname>$NOTIFY_SOCKET</varname> environment + variable. If the first character of + <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the + string is understood as Linux abstract namespace socket. The + datagram is accompanied by the process credentials of the sending + service, using SCM_CREDENTIALS.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$NOTIFY_SOCKET</varname></term> + + <listitem><para>Set by the service manager for supervised + processes for status and start-up completion notification. + This environment variable specifies the socket + <function>sd_notify()</function> talks to. See above for + details.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Start-up Notification</title> + + <para>When a service finished starting up, it might issue the + following call to notify the service manager:</para> + + <programlisting>sd_notify(0, "READY=1");</programlisting> + </example> + + <example> + <title>Extended Start-up Notification</title> + + <para>A service could send the following after completing + initialization:</para> + + <programlisting>sd_notifyf(0, "READY=1\n" + "STATUS=Processing requests...\n" + "MAINPID=%lu", + (unsigned long) getpid());</programlisting> + </example> + + <example> + <title>Error Cause Notification</title> + + <para>A service could send the following shortly before exiting, on failure:</para> + + <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n" + "ERRNO=%i", + strerror(errno), + errno);</programlisting> + </example> + + <example> + <title>Store a File Descriptor in the Service Manager</title> + + <para>To store an open file descriptor in the service manager, + in order to continue operation after a service restart without + losing state use <literal>FDSTORE=1</literal>:</para> + + <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml index 050f701da3..f708d0d5e1 100644 --- a/man/sd_pid_get_session.xml +++ b/man/sd_pid_get_session.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,250 +23,239 @@ <refentry id="sd_pid_get_session" conditional='HAVE_PAM'> - <refentryinfo> - <title>sd_pid_get_session</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_pid_get_session</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_pid_get_session</refname> - <refname>sd_pid_get_unit</refname> - <refname>sd_pid_get_user_unit</refname> - <refname>sd_pid_get_owner_uid</refname> - <refname>sd_pid_get_machine_name</refname> - <refname>sd_pid_get_slice</refname> - <refname>sd_peer_get_session</refname> - <refname>sd_peer_get_unit</refname> - <refname>sd_peer_get_user_unit</refname> - <refname>sd_peer_get_owner_uid</refname> - <refname>sd_peer_get_machine_name</refname> - <refname>sd_peer_get_slice</refname> - <refpurpose>Determine session, service, owner of a - session, container/VM or slice of a specific - PID or socket peer</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_pid_get_session</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>char **<parameter>session</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_get_unit</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>char **<parameter>unit</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_get_user_unit</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>char **<parameter>unit</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>uid_t *<parameter>uid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_get_machine_name</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>char **<parameter>name</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_get_slice</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>char **<parameter>slice</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_session</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>char **<parameter>session</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_unit</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>char **<parameter>unit</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_user_unit</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>char **<parameter>unit</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_owner_uid</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>uid_t *<parameter>uid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_machine_name</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>char **<parameter>name</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_peer_get_slice</function></funcdef> - <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>char **<parameter>slice</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_pid_get_session()</function> may be - used to determine the login session identifier of a - process identified by the specified process - identifier. The session identifier is a short string, - suitable for usage in file system paths. Note that not - all processes are part of a login session (e.g. system - service processes, user processes that are shared - between multiple sessions of the same user, or kernel - threads). For processes not being part of a login - session this function will fail. The returned string - needs to be freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_pid_get_unit()</function> may be - used to determine the systemd system unit (i.e. system - service) identifier of a process identified by the - specified PID. The unit name is a short string, - suitable for usage in file system paths. Note that not - all processes are part of a system unit/service - (e.g. user processes, or kernel threads). For - processes not being part of a systemd system unit this - function will fail. (More specifically: this call will - not work for processes that are part of user units, - use <function>sd_pid_get_user_unit()</function> for - that.) The returned string needs to be freed with the - libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_pid_get_user_unit()</function> may - be used to determine the systemd user unit (i.e. user - service) identifier of a process identified by the - specified PID. This is similar to - <function>sd_pid_get_unit()</function> but applies to - user units instead of system units.</para> - - <para><function>sd_pid_get_owner_uid()</function> may - be used to determine the Unix user identifier of the - owner of the session of a process identified the - specified PID. Note that this function will succeed - for user processes which are shared between multiple - login sessions of the same user, where - <function>sd_pid_get_session()</function> will - fail. For processes not being part of a login session - and not being a shared process of a user this function - will fail.</para> - - <para><function>sd_pid_get_machine_name()</function> - may be used to determine the name of the VM or - container is a member of. The machine name is a short - string, suitable for usage in file system paths. The - returned string needs to be freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_pid_get_slice()</function> may be - used to determine the slice unit the process is a - member of. See - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details about slices. The returned string needs to - be freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para>If the <varname>pid</varname> parameter of any - of these functions is passed as 0, the operation is - executed for the calling process.</para> - - <para>The <function>sd_peer_get_session()</function>, - <function>sd_peer_get_unit()</function>, - <function>sd_peer_get_user_unit()</function>, - <function>sd_peer_get_owner_uid()</function>, - <function>sd_peer_get_machine_name()</function> and - <function>sd_peer_get_slice()</function> calls operate - similar to their PID counterparts, but operate on a - connected AF_UNIX socket and retrieve information - about the connected peer process.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, these calls return 0 or a positive - integer. On failure, these calls return a negative - errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_pid_get_session()</function>, - <function>sd_pid_get_unit()</function>, - <function>sd_pid_get_user_unit()</function>, - <function>sd_pid_get_owner_uid()</function>, - <function>sd_pid_get_machine_name()</function>, - <function>sd_pid_get_slice()</function>, - <function>sd_peer_get_session()</function>, - <function>sd_peer_get_unit()</function>, - <function>sd_peer_get_user_unit()</function>, - <function>sd_peer_get_owner_uid()</function>, - <function>sd_peer_get_machine_name()</function> and - <function>sd_peer_get_slice()</function> interfaces are - available as a shared library, which can be compiled - and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - - <para>Note that the login session identifier as - returned by <function>sd_pid_get_session()</function> - is completely unrelated to the process session - identifier as returned by - <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_pid_get_session</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_pid_get_session</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_pid_get_session</refname> + <refname>sd_pid_get_unit</refname> + <refname>sd_pid_get_user_unit</refname> + <refname>sd_pid_get_owner_uid</refname> + <refname>sd_pid_get_machine_name</refname> + <refname>sd_pid_get_slice</refname> + <refname>sd_peer_get_session</refname> + <refname>sd_peer_get_unit</refname> + <refname>sd_peer_get_user_unit</refname> + <refname>sd_peer_get_owner_uid</refname> + <refname>sd_peer_get_machine_name</refname> + <refname>sd_peer_get_slice</refname> + <refpurpose>Determine session, service, owner of a + session, container/VM or slice of a specific + PID or socket peer</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_pid_get_session</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>session</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_unit</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_user_unit</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_machine_name</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_slice</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>slice</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_session</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>session</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_unit</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_user_unit</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_owner_uid</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_machine_name</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_slice</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>slice</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_pid_get_session()</function> may be used to + determine the login session identifier of a process identified by + the specified process identifier. The session identifier is a + short string, suitable for usage in file system paths. Note that + not all processes are part of a login session (e.g. system service + processes, user processes that are shared between multiple + sessions of the same user, or kernel threads). For processes not + being part of a login session this function will fail. The + returned string needs to be freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_pid_get_unit()</function> may be used to + determine the systemd system unit (i.e. system service) identifier + of a process identified by the specified PID. The unit name is a + short string, suitable for usage in file system paths. Note that + not all processes are part of a system unit/service (e.g. user + processes, or kernel threads). For processes not being part of a + systemd system unit this function will fail. (More specifically: + this call will not work for processes that are part of user units, + use <function>sd_pid_get_user_unit()</function> for that.) The + returned string needs to be freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_pid_get_user_unit()</function> may be used to + determine the systemd user unit (i.e. user service) identifier of + a process identified by the specified PID. This is similar to + <function>sd_pid_get_unit()</function> but applies to user units + instead of system units.</para> + + <para><function>sd_pid_get_owner_uid()</function> may be used to + determine the Unix user identifier of the owner of the session of + a process identified the specified PID. Note that this function + will succeed for user processes which are shared between multiple + login sessions of the same user, where + <function>sd_pid_get_session()</function> will fail. For processes + not being part of a login session and not being a shared process + of a user this function will fail.</para> + + <para><function>sd_pid_get_machine_name()</function> may be used + to determine the name of the VM or container is a member of. The + machine name is a short string, suitable for usage in file system + paths. The returned string needs to be freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_pid_get_slice()</function> may be used to + determine the slice unit the process is a member of. See + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details about slices. The returned string needs to be freed + with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para>If the <varname>pid</varname> parameter of any of these + functions is passed as 0, the operation is executed for the + calling process.</para> + + <para>The <function>sd_peer_get_session()</function>, + <function>sd_peer_get_unit()</function>, + <function>sd_peer_get_user_unit()</function>, + <function>sd_peer_get_owner_uid()</function>, + <function>sd_peer_get_machine_name()</function> and + <function>sd_peer_get_slice()</function> calls operate similar to + their PID counterparts, but operate on a connected AF_UNIX socket + and retrieve information about the connected peer process.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_pid_get_session()</function>, + <function>sd_pid_get_unit()</function>, + <function>sd_pid_get_user_unit()</function>, + <function>sd_pid_get_owner_uid()</function>, + <function>sd_pid_get_machine_name()</function>, + <function>sd_pid_get_slice()</function>, + <function>sd_peer_get_session()</function>, + <function>sd_peer_get_unit()</function>, + <function>sd_peer_get_user_unit()</function>, + <function>sd_peer_get_owner_uid()</function>, + <function>sd_peer_get_machine_name()</function> and + <function>sd_peer_get_slice()</function> interfaces are + available as a shared library, which can be compiled + and linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + + <para>Note that the login session identifier as + returned by <function>sd_pid_get_session()</function> + is completely unrelated to the process session + identifier as returned by + <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml index 20c7b99daa..3c57ec9ea4 100644 --- a/man/sd_seat_get_active.xml +++ b/man/sd_seat_get_active.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,161 +23,153 @@ <refentry id="sd_seat_get_active" conditional='HAVE_PAM'> - <refentryinfo> - <title>sd_seat_get_active</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_seat_get_active</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_seat_get_active</refname> - <refname>sd_seat_get_sessions</refname> - <refname>sd_seat_can_multi_session</refname> - <refname>sd_seat_can_tty</refname> - <refname>sd_seat_can_graphical</refname> - <refpurpose>Determine state of a specific seat</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_seat_get_active</function></funcdef> - <paramdef>const char *<parameter>seat</parameter></paramdef> - <paramdef>char **<parameter>session</parameter></paramdef> - <paramdef>uid_t *<parameter>uid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_seat_get_sessions</function></funcdef> - <paramdef>const char *<parameter>seat</parameter></paramdef> - <paramdef>char ***<parameter>sessions</parameter></paramdef> - <paramdef>uid_t **<parameter>uid</parameter></paramdef> - <paramdef>unsigned int *<parameter>n_uids</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_seat_can_multi_session</function></funcdef> - <paramdef>const char *<parameter>seat</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_seat_can_tty</function></funcdef> - <paramdef>const char *<parameter>seat</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_seat_can_graphical</function></funcdef> - <paramdef>const char *<parameter>seat</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_seat_get_active()</function> may be - used to determine which session is currently active on - a seat, if there is any. Returns the session - identifier and the user identifier of the Unix user - the session is belonging to. Either the session or the - user identifier parameter can be passed - <constant>NULL</constant>, in case only one of the - parameters shall be queried. The returned string needs - to be freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_seat_get_sessions()</function> may - be used to determine all sessions on the specified - seat. Returns two arrays, one (<constant>NULL</constant> terminated) with - the session identifiers of the sessions and one with - the user identifiers of the Unix users the sessions - belong to. An additional parameter may be used to - return the number of entries in the latter array. The - two arrays and the latter parameter may be passed as - <constant>NULL</constant> in case these values need not to be - determined. The arrays and the strings referenced by - them need to be freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use. Note that instead of an empty array - <constant>NULL</constant> may be returned and should be considered - equivalent to an empty array.</para> - - <para><function>sd_seat_can_multi_session()</function> - may be used to determine whether a specific seat is - capable of multi-session, i.e. allows multiple login - sessions in parallel (with only one being active at a - time).</para> - - <para><function>sd_seat_can_tty()</function> may be - used to determine whether a specific seat provides TTY - functionality, i.e. is useful as a text console.</para> - - <para><function>sd_seat_can_graphical()</function> may - be used to determine whether a specific seat provides - graphics functionality, i.e. is useful as a graphics - display.</para> - - <para>If the <varname>seat</varname> parameter of any - of these functions is passed as - <constant>NULL</constant>, the operation is executed - for the seat of the session of the calling process, if - there is any.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para> On success, - <function>sd_seat_get_active()</function> - returns 0 or a positive integer. On success, - <function>sd_seat_get_sessions()</function> returns - the number of entries in the session identifier - array. If the test succeeds, - <function>sd_seat_can_multi_session</function>, - <function>sd_seat_can_tty</function> and - <function>sd_seat_can_graphical</function> return a - positive integer, if it fails 0. On failure, these - calls return a negative errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_seat_get_active()</function>, - <function>sd_seat_get_sessions()</function>, - <function>sd_seat_can_multi_session()</function>, - <function>sd_seat_can_tty()</function> and - <function>sd_seat_can_grapical()</function> interfaces - are available as a shared library, which can be compiled - and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_seat_get_active</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_seat_get_active</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_seat_get_active</refname> + <refname>sd_seat_get_sessions</refname> + <refname>sd_seat_can_multi_session</refname> + <refname>sd_seat_can_tty</refname> + <refname>sd_seat_can_graphical</refname> + <refpurpose>Determine state of a specific seat</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_seat_get_active</function></funcdef> + <paramdef>const char *<parameter>seat</parameter></paramdef> + <paramdef>char **<parameter>session</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_seat_get_sessions</function></funcdef> + <paramdef>const char *<parameter>seat</parameter></paramdef> + <paramdef>char ***<parameter>sessions</parameter></paramdef> + <paramdef>uid_t **<parameter>uid</parameter></paramdef> + <paramdef>unsigned int *<parameter>n_uids</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_seat_can_multi_session</function></funcdef> + <paramdef>const char *<parameter>seat</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_seat_can_tty</function></funcdef> + <paramdef>const char *<parameter>seat</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_seat_can_graphical</function></funcdef> + <paramdef>const char *<parameter>seat</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_seat_get_active()</function> may be used to + determine which session is currently active on a seat, if there is + any. Returns the session identifier and the user identifier of the + Unix user the session is belonging to. Either the session or the + user identifier parameter can be passed <constant>NULL</constant>, + in case only one of the parameters shall be queried. The returned + string needs to be freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_seat_get_sessions()</function> may be used to + determine all sessions on the specified seat. Returns two arrays, + one (<constant>NULL</constant> terminated) with the session + identifiers of the sessions and one with the user identifiers of + the Unix users the sessions belong to. An additional parameter may + be used to return the number of entries in the latter array. The + two arrays and the latter parameter may be passed as + <constant>NULL</constant> in case these values need not to be + determined. The arrays and the strings referenced by them need to + be freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use. Note that instead of an empty array + <constant>NULL</constant> may be returned and should be considered + equivalent to an empty array.</para> + + <para><function>sd_seat_can_multi_session()</function> may be used + to determine whether a specific seat is capable of multi-session, + i.e. allows multiple login sessions in parallel (with only one + being active at a time).</para> + + <para><function>sd_seat_can_tty()</function> may be used to + determine whether a specific seat provides TTY functionality, i.e. + is useful as a text console.</para> + + <para><function>sd_seat_can_graphical()</function> may be used to + determine whether a specific seat provides graphics functionality, + i.e. is useful as a graphics display.</para> + + <para>If the <varname>seat</varname> parameter of any of these + functions is passed as <constant>NULL</constant>, the operation is + executed for the seat of the session of the calling process, if + there is any.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> On success, <function>sd_seat_get_active()</function> + returns 0 or a positive integer. On success, + <function>sd_seat_get_sessions()</function> returns the number of + entries in the session identifier array. If the test succeeds, + <function>sd_seat_can_multi_session</function>, + <function>sd_seat_can_tty</function> and + <function>sd_seat_can_graphical</function> return a positive + integer, if it fails 0. On failure, these calls return a negative + errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_seat_get_active()</function>, + <function>sd_seat_get_sessions()</function>, + <function>sd_seat_can_multi_session()</function>, + <function>sd_seat_can_tty()</function> and + <function>sd_seat_can_grapical()</function> interfaces are + available as a shared library, which can be compiled and linked to + with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_session_is_active.xml b/man/sd_session_is_active.xml index e9840669c2..4ca3a6c150 100644 --- a/man/sd_session_is_active.xml +++ b/man/sd_session_is_active.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,319 +23,300 @@ <refentry id="sd_session_is_active" conditional='HAVE_PAM'> - <refentryinfo> - <title>sd_session_is_active</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_session_is_active</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_session_is_active</refname> - <refname>sd_session_is_remote</refname> - <refname>sd_session_get_state</refname> - <refname>sd_session_get_uid</refname> - <refname>sd_session_get_seat</refname> - <refname>sd_session_get_service</refname> - <refname>sd_session_get_type</refname> - <refname>sd_session_get_class</refname> - <refname>sd_session_get_desktop</refname> - <refname>sd_session_get_display</refname> - <refname>sd_session_get_tty</refname> - <refname>sd_session_get_vt</refname> - <refname>sd_session_get_remote_host</refname> - <refname>sd_session_get_remote_user</refname> - <refpurpose>Determine state of a specific session</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_session_is_active</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_is_remote</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_state</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>state</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_uid</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>uid_t *<parameter>uid</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_seat</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>seat</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_service</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>service</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_type</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>type</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_class</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>class</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_desktop</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>desktop</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_display</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>display</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_remote_host</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>remote_host</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_remote_user</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>remote_user</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_tty</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>char **<parameter>tty</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_session_get_vt</function></funcdef> - <paramdef>const char *<parameter>session</parameter></paramdef> - <paramdef>unsigned int *<parameter>vt</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_session_is_active()</function> may - be used to determine whether the session identified by - the specified session identifier is currently active - (i.e. currently in the foreground and available for - user input) or not.</para> - - <para><function>sd_session_is_remote()</function> may - be used to determine whether the session identified by - the specified session identifier is a remote session - (i.e. its remote host is known) or not.</para> - - <para><function>sd_session_get_state()</function> may - be used to determine the state of the session - identified by the specified session identifier. The - following states are currently known: - <literal>online</literal> (session logged in, but - session not active, i.e. not in the foreground), - <literal>active</literal> (session logged in and - active, i.e. in the foreground), - <literal>closing</literal> (session nominally logged - out, but some processes belonging to it are still - around). In the future additional states might be - defined, client code should be written to be robust in - regards to additional state strings being - returned. This function is a more generic version of - <function>sd_session_is_active()</function>. The returned - string needs to be freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_uid()</function> may be - used to determine the user identifier of the Unix user the session - identified by the specified session identifier belongs - to.</para> - - <para><function>sd_session_get_seat()</function> may - be used to determine the seat identifier of the seat - the session identified by the specified session - identifier belongs to. Note that not all sessions are - attached to a seat, this call will fail for them. The - returned string needs to be freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_service()</function> - may be used to determine the name of the service (as - passed during PAM session setup) that registered the - session identified by the specified session - identifier. The returned string needs to be freed with - the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_type()</function> may - be used to determine the type of the session - identified by the specified session identifier. The - returned string is one of <literal>x11</literal>, - <literal>wayland</literal>, <literal>tty</literal>, - <literal>mir</literal> or <literal>unspecified</literal> and - needs to be freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_class()</function> may - be used to determine the class of the session - identified by the specified session identifier. The - returned string is one of <literal>user</literal>, - <literal>greeter</literal>, - <literal>lock-screen</literal>, or - <literal>background</literal> and needs to be freed - with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_desktop()</function> may - be used to determine the brand of the desktop running on - the session identified by the specified session identifier. - This field can be set freely by desktop environments and - does not follow any special formatting. However, desktops - are strongly recommended to use the same identifiers and - capitalization as for - <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by - the <ulink - url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop - Entry - Specification</ulink>. The returned string needs to be - freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_display()</function> - may be used to determine the X11 display of the - session identified by the specified session - identifier. The returned string needs to be - freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_remote_host()</function> - may be used to determine the remote hostname of the - session identified by the specified session - identifier. The returned string needs to be - freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_remote_user()</function> - may be used to determine the remote username of the - session identified by the specified session - identifier. The returned string needs to be - freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use. Note that this value is rarely known - to the system, and even then should not be relied on.</para> - - <para><function>sd_session_get_tty()</function> - may be used to determine the TTY device of the - session identified by the specified session - identifier. The returned string needs to be - freed with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_session_get_vt()</function> - may be used to determine the VT number of the - session identified by the specified session - identifier. This function will return an error if - the seat does not support VTs.</para> - - <para>If the <varname>session</varname> parameter of - any of these functions is passed as - <constant>NULL</constant>, the operation is executed - for the session the calling process is a member of, if - there is any.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>If the test succeeds, - <function>sd_session_is_active()</function> and - <function>sd_session_is_remote()</function> return a - positive integer; if it fails, 0. On success, - <function>sd_session_get_state()</function>, - <function>sd_session_get_uid()</function>, - <function>sd_session_get_seat()</function>, - <function>sd_session_get_service()</function>, - <function>sd_session_get_type()</function>, - <function>sd_session_get_class()</function>, - <function>sd_session_get_display()</function>, - <function>sd_session_get_remote_user()</function>, - <function>sd_session_get_remote_host()</function> and - <function>sd_session_get_tty()</function> return 0 or - a positive integer. On failure, these calls return a - negative errno-style error code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>The <function>sd_session_is_active()</function>, - <function>sd_session_get_state()</function>, - <function>sd_session_get_uid()</function>, - <function>sd_session_get_seat()</function>, - <function>sd_session_get_service()</function>, - <function>sd_session_get_type()</function>, - <function>sd_session_get_class()</function>, - <function>sd_session_get_display()</function>, - <function>sd_session_get_remote_host()</function>, - <function>sd_session_get_remote_user()</function> and - <function>sd_session_get_tty()</function> - interfaces are available as a shared library, which can - be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_session_is_active</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_session_is_active</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_session_is_active</refname> + <refname>sd_session_is_remote</refname> + <refname>sd_session_get_state</refname> + <refname>sd_session_get_uid</refname> + <refname>sd_session_get_seat</refname> + <refname>sd_session_get_service</refname> + <refname>sd_session_get_type</refname> + <refname>sd_session_get_class</refname> + <refname>sd_session_get_desktop</refname> + <refname>sd_session_get_display</refname> + <refname>sd_session_get_tty</refname> + <refname>sd_session_get_vt</refname> + <refname>sd_session_get_remote_host</refname> + <refname>sd_session_get_remote_user</refname> + <refpurpose>Determine state of a specific session</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_session_is_active</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_is_remote</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_state</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + <paramdef>char **<parameter>state</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_uid</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_seat</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + <paramdef>char **<parameter>seat</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_service</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + <paramdef>char **<parameter>service</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_type</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + <paramdef>char **<parameter>type</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_class</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + <paramdef>char **<parameter>class</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_desktop</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + <paramdef>char **<parameter>desktop</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_display</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + <paramdef>char **<parameter>display</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_remote_host</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + <paramdef>char **<parameter>remote_host</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_remote_user</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + <paramdef>char **<parameter>remote_user</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_tty</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + <paramdef>char **<parameter>tty</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_session_get_vt</function></funcdef> + <paramdef>const char *<parameter>session</parameter></paramdef> + <paramdef>unsigned int *<parameter>vt</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_session_is_active()</function> may be used to + determine whether the session identified by the specified session + identifier is currently active (i.e. currently in the foreground + and available for user input) or not.</para> + + <para><function>sd_session_is_remote()</function> may be used to + determine whether the session identified by the specified session + identifier is a remote session (i.e. its remote host is known) or + not.</para> + + <para><function>sd_session_get_state()</function> may be used to + determine the state of the session identified by the specified + session identifier. The following states are currently known: + <literal>online</literal> (session logged in, but session not + active, i.e. not in the foreground), <literal>active</literal> + (session logged in and active, i.e. in the foreground), + <literal>closing</literal> (session nominally logged out, but some + processes belonging to it are still around). In the future + additional states might be defined, client code should be written + to be robust in regards to additional state strings being + returned. This function is a more generic version of + <function>sd_session_is_active()</function>. The returned string + needs to be freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_uid()</function> may be used to + determine the user identifier of the Unix user the session + identified by the specified session identifier belongs to.</para> + + <para><function>sd_session_get_seat()</function> may be used to + determine the seat identifier of the seat the session identified + by the specified session identifier belongs to. Note that not all + sessions are attached to a seat, this call will fail for them. The + returned string needs to be freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_service()</function> may be used to + determine the name of the service (as passed during PAM session + setup) that registered the session identified by the specified + session identifier. The returned string needs to be freed with the + libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_type()</function> may be used to + determine the type of the session identified by the specified + session identifier. The returned string is one of + <literal>x11</literal>, <literal>wayland</literal>, + <literal>tty</literal>, <literal>mir</literal> or + <literal>unspecified</literal> and needs to be freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_class()</function> may be used to + determine the class of the session identified by the specified + session identifier. The returned string is one of + <literal>user</literal>, <literal>greeter</literal>, + <literal>lock-screen</literal>, or <literal>background</literal> + and needs to be freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_desktop()</function> may be used to + determine the brand of the desktop running on the session + identified by the specified session identifier. This field can be + set freely by desktop environments and does not follow any special + formatting. However, desktops are strongly recommended to use the + same identifiers and capitalization as for + <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the <ulink + url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop + Entry Specification</ulink>. The returned string needs to be freed + with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_display()</function> may be used to + determine the X11 display of the session identified by the + specified session identifier. The returned string needs to be + freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_remote_host()</function> may be + used to determine the remote hostname of the session identified by + the specified session identifier. The returned string needs to be + freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_remote_user()</function> may be + used to determine the remote username of the session identified by + the specified session identifier. The returned string needs to be + freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use. Note that this value is rarely known to the + system, and even then should not be relied on.</para> + + <para><function>sd_session_get_tty()</function> may be used to + determine the TTY device of the session identified by the + specified session identifier. The returned string needs to be + freed with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_session_get_vt()</function> may be used to + determine the VT number of the session identified by the specified + session identifier. This function will return an error if the seat + does not support VTs.</para> + + <para>If the <varname>session</varname> parameter of any of these + functions is passed as <constant>NULL</constant>, the operation is + executed for the session the calling process is a member of, if + there is any.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>If the test succeeds, + <function>sd_session_is_active()</function> and + <function>sd_session_is_remote()</function> return a + positive integer; if it fails, 0. On success, + <function>sd_session_get_state()</function>, + <function>sd_session_get_uid()</function>, + <function>sd_session_get_seat()</function>, + <function>sd_session_get_service()</function>, + <function>sd_session_get_type()</function>, + <function>sd_session_get_class()</function>, + <function>sd_session_get_display()</function>, + <function>sd_session_get_remote_user()</function>, + <function>sd_session_get_remote_host()</function> and + <function>sd_session_get_tty()</function> return 0 or + a positive integer. On failure, these calls return a + negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_session_is_active()</function>, + <function>sd_session_get_state()</function>, + <function>sd_session_get_uid()</function>, + <function>sd_session_get_seat()</function>, + <function>sd_session_get_service()</function>, + <function>sd_session_get_type()</function>, + <function>sd_session_get_class()</function>, + <function>sd_session_get_display()</function>, + <function>sd_session_get_remote_host()</function>, + <function>sd_session_get_remote_user()</function> and + <function>sd_session_get_tty()</function> + interfaces are available as a shared library, which can + be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml index e1b345c277..b158f3528c 100644 --- a/man/sd_uid_get_state.xml +++ b/man/sd_uid_get_state.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,193 +23,182 @@ <refentry id="sd_uid_get_state" conditional='HAVE_PAM'> - <refentryinfo> - <title>sd_uid_get_state</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_uid_get_state</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_uid_get_state</refname> - <refname>sd_uid_is_on_seat</refname> - <refname>sd_uid_get_sessions</refname> - <refname>sd_uid_get_seats</refname> - <refname>sd_uid_get_display</refname> - <refpurpose>Determine login state of a specific Unix user ID</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_uid_get_state</function></funcdef> - <paramdef>uid_t <parameter>uid</parameter></paramdef> - <paramdef>char **<parameter>state</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_uid_is_on_seat</function></funcdef> - <paramdef>uid_t <parameter>uid</parameter></paramdef> - <paramdef>int <parameter>require_active</parameter></paramdef> - <paramdef>const char *<parameter>seat</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_uid_get_sessions</function></funcdef> - <paramdef>uid_t <parameter>uid</parameter></paramdef> - <paramdef>int <parameter>require_active</parameter></paramdef> - <paramdef>char ***<parameter>sessions</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_uid_get_seats</function></funcdef> - <paramdef>uid_t <parameter>uid</parameter></paramdef> - <paramdef>int <parameter>require_active</parameter></paramdef> - <paramdef>char ***<parameter>seats</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_uid_get_display</function></funcdef> - <paramdef>uid_t <parameter>uid</parameter></paramdef> - <paramdef>char **<parameter>session</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_uid_get_state()</function> may be - used to determine the login state of a specific Unix - user identifier. The following states are currently - known: <literal>offline</literal> (user not logged in - at all), <literal>lingering</literal> (user not logged - in, but some user services running), - <literal>online</literal> (user logged in, but not - active, i.e. has no session in the foreground), - <literal>active</literal> (user logged in, and has at - least one active session, i.e. one session in the - foreground), <literal>closing</literal> (user not - logged in, and not lingering, but some processes are - still around). In the future additional states might - be defined, client code should be written to be robust - in regards to additional state strings being - returned. The returned string needs to be freed with - the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use.</para> - - <para><function>sd_uid_is_on_seat()</function> may be - used to determine whether a specific user is logged in - or active on a specific seat. Accepts a Unix user - identifier and a seat identifier string as - parameters. The <parameter>require_active</parameter> - parameter is a boolean value. If non-zero (true), this - function will test if the user is active (i.e. has a - session that is in the foreground and accepting user - input) on the specified seat, otherwise (false) only - if the user is logged in (and possibly inactive) on - the specified seat.</para> - - <para><function>sd_uid_get_sessions()</function> may - be used to determine the current sessions of the - specified user. Accepts a Unix user identifier as - parameter. The <parameter>require_active</parameter> - parameter controls whether the returned list shall - consist of only those sessions where the user is - currently active (> 0), where the user is currently - online but possibly inactive (= 0), or - logged in at all but possibly closing the session (< 0). The call returns a - <constant>NULL</constant> terminated string array of session identifiers in - <parameter>sessions</parameter> which needs to be - freed by the caller with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use, including all the strings - referenced. If the string array parameter is passed as - <constant>NULL</constant>, the array will not be filled in, but the return - code still indicates the number of current - sessions. Note that instead of an empty array <constant>NULL</constant> may - be returned and should be considered equivalent to an - empty array.</para> - - <para>Similarly, <function>sd_uid_get_seats()</function> - may be used to determine the list of seats on which - the user currently has sessions. Similar semantics - apply, however note that the user may have - multiple sessions on the same seat as well as sessions - with no attached seat and hence the number of entries - in the returned array may differ from the one returned - by <function>sd_uid_get_sessions()</function>.</para> - - <para><function>sd_uid_get_display()</function> - returns the name of the "primary" session of a user. - If the user has graphical sessions, it will be the - oldest graphical session. Otherwise, it will be the - oldest open session.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>sd_uid_get_state()</function> returns 0 or a - positive integer. If the test succeeds, - <function>sd_uid_is_on_seat()</function> returns a - positive integer; if it fails, - 0. <function>sd_uid_get_sessions()</function> and - <function>sd_uid_get_seats()</function> return the - number of entries in the returned arrays. - <function>sd_uid_get_display()</function> returns - a non-negative code on success. On failure, - these calls return a negative errno-style error - code.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>Functions described here are available as a - shared library, and can be compiled and linked to - using the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - entry.</para> - </refsect1> - - <refsect1> - <title>History</title> - - <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><function>sd_uid_get_display()</function> was - added in systemd-213.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>sd_uid_get_state</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_uid_get_state</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_uid_get_state</refname> + <refname>sd_uid_is_on_seat</refname> + <refname>sd_uid_get_sessions</refname> + <refname>sd_uid_get_seats</refname> + <refname>sd_uid_get_display</refname> + <refpurpose>Determine login state of a specific Unix user ID</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_uid_get_state</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>char **<parameter>state</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_is_on_seat</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>int <parameter>require_active</parameter></paramdef> + <paramdef>const char *<parameter>seat</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_get_sessions</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>int <parameter>require_active</parameter></paramdef> + <paramdef>char ***<parameter>sessions</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_get_seats</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>int <parameter>require_active</parameter></paramdef> + <paramdef>char ***<parameter>seats</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_get_display</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>char **<parameter>session</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_uid_get_state()</function> may be used to + determine the login state of a specific Unix user identifier. The + following states are currently known: <literal>offline</literal> + (user not logged in at all), <literal>lingering</literal> (user + not logged in, but some user services running), + <literal>online</literal> (user logged in, but not active, i.e. + has no session in the foreground), <literal>active</literal> (user + logged in, and has at least one active session, i.e. one session + in the foreground), <literal>closing</literal> (user not logged + in, and not lingering, but some processes are still around). In + the future additional states might be defined, client code should + be written to be robust in regards to additional state strings + being returned. The returned string needs to be freed with the + libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_uid_is_on_seat()</function> may be used to + determine whether a specific user is logged in or active on a + specific seat. Accepts a Unix user identifier and a seat + identifier string as parameters. The + <parameter>require_active</parameter> parameter is a boolean + value. If non-zero (true), this function will test if the user is + active (i.e. has a session that is in the foreground and accepting + user input) on the specified seat, otherwise (false) only if the + user is logged in (and possibly inactive) on the specified + seat.</para> + + <para><function>sd_uid_get_sessions()</function> may be used to + determine the current sessions of the specified user. Accepts a + Unix user identifier as parameter. The + <parameter>require_active</parameter> parameter controls whether + the returned list shall consist of only those sessions where the + user is currently active (> 0), where the user is currently + online but possibly inactive (= 0), or logged in at all but + possibly closing the session (< 0). The call returns a + <constant>NULL</constant> terminated string array of session + identifiers in <parameter>sessions</parameter> which needs to be + freed by the caller with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use, including all the strings referenced. If the + string array parameter is passed as <constant>NULL</constant>, the + array will not be filled in, but the return code still indicates + the number of current sessions. Note that instead of an empty + array <constant>NULL</constant> may be returned and should be + considered equivalent to an empty array.</para> + + <para>Similarly, <function>sd_uid_get_seats()</function> may be + used to determine the list of seats on which the user currently + has sessions. Similar semantics apply, however note that the user + may have multiple sessions on the same seat as well as sessions + with no attached seat and hence the number of entries in the + returned array may differ from the one returned by + <function>sd_uid_get_sessions()</function>.</para> + + <para><function>sd_uid_get_display()</function> returns the name + of the "primary" session of a user. If the user has graphical + sessions, it will be the oldest graphical session. Otherwise, it + will be the oldest open session.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_uid_get_state()</function> returns + 0 or a positive integer. If the test succeeds, + <function>sd_uid_is_on_seat()</function> returns a positive + integer; if it fails, 0. + <function>sd_uid_get_sessions()</function> and + <function>sd_uid_get_seats()</function> return the number of + entries in the returned arrays. + <function>sd_uid_get_display()</function> returns a non-negative + code on success. On failure, these calls return a negative + errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>Functions described here are available as a shared library, + and can be compiled and linked to using the + <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + entry.</para> + </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> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sd_watchdog_enabled.xml b/man/sd_watchdog_enabled.xml index 297878d814..991431f33b 100644 --- a/man/sd_watchdog_enabled.xml +++ b/man/sd_watchdog_enabled.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,168 +22,154 @@ --> <refentry id="sd_watchdog_enabled" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd_watchdog_enabled</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_watchdog_enabled</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_watchdog_enabled</refname> - <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_watchdog_enabled</function></funcdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>uint64_t *<parameter>usec</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - <para><function>sd_watchdog_enabled()</function> may - be called by a service to detect whether the service - manager expects regular keep-alive watchdog - notification events from it, and the timeout after - which the manager will act on the service if it did - not get such a notification.</para> - - <para>If the <varname>$WATCHDOG_USEC</varname> - environment variable is set, and the - <varname>$WATCHDOG_PID</varname> variable is unset or - set to the PID of the current process, the service - manager expects notifications from this process. The - manager will usually terminate a service when it does - not get a notification message within the specified - time after startup and after each previous message. It - is recommended that a daemon sends a keep-alive - notification message to the service manager every half - of the time returned here. Notification messages may - be sent with - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - with a message string of - <literal>WATCHDOG=1</literal>.</para> - - <para>If the <parameter>unset_environment</parameter> - parameter is non-zero, - <function>sd_watchdog_enabled()</function> will unset - the <varname>$WATCHDOG_USEC</varname> and - <varname>$WATCHDOG_PID</varname> environment variables - before returning (regardless of whether the function - call itself succeeded or not). Those variables are no - longer inherited by child processes. Further calls to - <function>sd_watchdog_enabled()</function> will also - return with zero.</para> - - <para>If the <parameter>usec</parameter> parameter is - non-NULL, <function>sd_watchdog_enabled()</function> - will write the timeout in µs for the watchdog - logic to it.</para> - - <para>To enable service supervision with the watchdog - logic, use <varname>WatchdogSec=</varname> in service - files. See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On failure, this call returns a negative - errno-style error code. If the service manager expects - watchdog keep-alive notification messages to be sent, - > 0 is returned, otherwise 0 is returned. Only if - the return value is > 0, the - <parameter>usec</parameter> parameter is valid after - the call.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> - - <para>Internally, this functions parses the - <varname>$WATCHDOG_PID</varname> and - <varname>$WATCHDOG_USEC</varname> environment - variable. The call will ignore these variables if - <varname>$WATCHDOG_PID</varname> does not contain the PID - of the current process, under the assumption that in - that case, the variables were set for a different - process further up the process tree.</para> - </refsect1> - - <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$WATCHDOG_PID</varname></term> - - <listitem><para>Set by the system - manager for supervised process for - which watchdog support is enabled, and - contains the PID of that process. See - above for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$WATCHDOG_USEC</varname></term> - - <listitem><para>Set by the system - manager for supervised process for - which watchdog support is enabled, and - contains the watchdog timeout in µs - See above for - details.</para></listitem> - </varlistentry> - </variablelist> - </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>, - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_watchdog_enabled</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_watchdog_enabled</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_watchdog_enabled</refname> + <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_watchdog_enabled</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para><function>sd_watchdog_enabled()</function> may be called by + a service to detect whether the service manager expects regular + keep-alive watchdog notification events from it, and the timeout + after which the manager will act on the service if it did not get + such a notification.</para> + + <para>If the <varname>$WATCHDOG_USEC</varname> environment + variable is set, and the <varname>$WATCHDOG_PID</varname> variable + is unset or set to the PID of the current process, the service + manager expects notifications from this process. The manager will + usually terminate a service when it does not get a notification + message within the specified time after startup and after each + previous message. It is recommended that a daemon sends a + keep-alive notification message to the service manager every half + of the time returned here. Notification messages may be sent with + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with a message string of <literal>WATCHDOG=1</literal>.</para> + + <para>If the <parameter>unset_environment</parameter> parameter is + non-zero, <function>sd_watchdog_enabled()</function> will unset + the <varname>$WATCHDOG_USEC</varname> and + <varname>$WATCHDOG_PID</varname> environment variables before + returning (regardless of whether the function call itself + succeeded or not). Those variables are no longer inherited by + child processes. Further calls to + <function>sd_watchdog_enabled()</function> will also return with + zero.</para> + + <para>If the <parameter>usec</parameter> parameter is non-NULL, + <function>sd_watchdog_enabled()</function> will write the timeout + in µs for the watchdog logic to it.</para> + + <para>To enable service supervision with the watchdog logic, use + <varname>WatchdogSec=</varname> in service files. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, this call returns a negative errno-style error + code. If the service manager expects watchdog keep-alive + notification messages to be sent, > 0 is returned, otherwise 0 + is returned. Only if the return value is > 0, the + <parameter>usec</parameter> parameter is valid after the + call.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + + <para>Internally, this functions parses the + <varname>$WATCHDOG_PID</varname> and + <varname>$WATCHDOG_USEC</varname> environment variable. The call + will ignore these variables if <varname>$WATCHDOG_PID</varname> + does not contain the PID of the current process, under the + assumption that in that case, the variables were set for a + different process further up the process tree.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$WATCHDOG_PID</varname></term> + + <listitem><para>Set by the system manager for supervised + process for which watchdog support is enabled, and contains + the PID of that process. See above for + details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$WATCHDOG_USEC</varname></term> + + <listitem><para>Set by the system manager for supervised + process for which watchdog support is enabled, and contains + the watchdog timeout in µs See above for + details.</para></listitem> + </varlistentry> + </variablelist> + </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>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/shutdown.xml b/man/shutdown.xml index 6a4c1844a4..a8af387c67 100644 --- a/man/shutdown.xml +++ b/man/shutdown.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,160 +22,154 @@ --> <refentry id="shutdown" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>shutdown</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>shutdown</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>shutdown</refname> - <refpurpose>Halt, power-off or reboot the machine</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>shutdown <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">TIME</arg> <arg choice="opt" rep="repeat">WALL</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>shutdown</command> may be used to halt, - power-off or reboot the machine.</para> - - <para>The first argument may be a time string (which - is usually <literal>now</literal>). Optionally, this - may be followed by a wall message to be sent to all - logged-in users before going down.</para> - - <para>The time string may either be in the format - <literal>hh:mm</literal> for hour/minutes specifying - the time to execute the shutdown at, specified in 24h - clock format. Alternatively it may be in the syntax - <literal>+m</literal> referring to the specified - number of minutes m from now. <literal>now</literal> - is an alias for <literal>+0</literal>, i.e. for - triggering an immediate shutdown. If no time argument - is specified, <literal>+1</literal> is - implied.</para> - - <para>Note that to specify a wall message you must - specify a time argument, too.</para> - - <para>If the time argument is used, 5 minutes - before the system goes down the - <filename>/run/nologin</filename> file is created to - ensure that further logins shall not be - allowed.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--help</option></term> - - <xi:include href="standard-options.xml" xpointer="help-text" /> - </varlistentry> - - <varlistentry> - <term><option>-H</option></term> - <term><option>--halt</option></term> - - <listitem><para>Halt the machine.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-P</option></term> - <term><option>--poweroff</option></term> - - <listitem><para>Power-off the - machine (the default).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-r</option></term> - <term><option>--reboot</option></term> - - <listitem><para>Reboot the - machine.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-h</option></term> - - <listitem><para>Equivalent to - <option>--poweroff</option>, unless - <option>--halt</option> is - specified.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-k</option></term> - - <listitem><para>Do not halt, power-off, - reboot, just write wall - message.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-wall</option></term> - - <listitem><para>Do not send wall - message before - halt, power-off, reboot.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option></term> - - <listitem><para>Cancel a pending - shutdown. This may be used cancel the - effect of an invocation of - <command>shutdown</command> with a - time argument that is not - <literal>+0</literal> or - <literal>now</literal>.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>halt</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>shutdown</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>shutdown</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>shutdown</refname> + <refpurpose>Halt, power-off or reboot the machine</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>shutdown</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt">TIME</arg> + <arg choice="opt" rep="repeat">WALL</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>shutdown</command> may be used to halt, power-off + or reboot the machine.</para> + + <para>The first argument may be a time string (which is usually + <literal>now</literal>). Optionally, this may be followed by a + wall message to be sent to all logged-in users before going + down.</para> + + <para>The time string may either be in the format + <literal>hh:mm</literal> for hour/minutes specifying the time to + execute the shutdown at, specified in 24h clock format. + Alternatively it may be in the syntax <literal>+m</literal> + referring to the specified number of minutes m from now. + <literal>now</literal> is an alias for <literal>+0</literal>, i.e. + for triggering an immediate shutdown. If no time argument is + specified, <literal>+1</literal> is implied.</para> + + <para>Note that to specify a wall message you must specify a time + argument, too.</para> + + <para>If the time argument is used, 5 minutes before the system + goes down the <filename>/run/nologin</filename> file is created to + ensure that further logins shall not be allowed.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + + <xi:include href="standard-options.xml" xpointer="help-text" /> + </varlistentry> + + <varlistentry> + <term><option>-H</option></term> + <term><option>--halt</option></term> + + <listitem><para>Halt the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-P</option></term> + <term><option>--poweroff</option></term> + + <listitem><para>Power-off the machine (the + default).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-r</option></term> + <term><option>--reboot</option></term> + + <listitem><para>Reboot the + machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-h</option></term> + + <listitem><para>Equivalent to <option>--poweroff</option>, + unless <option>--halt</option> is specified.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-k</option></term> + + <listitem><para>Do not halt, power-off, reboot, just write + wall message.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-wall</option></term> + + <listitem><para>Do not send wall + message before + halt, power-off, reboot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-c</option></term> + + <listitem><para>Cancel a pending shutdown. This may be used + cancel the effect of an invocation of + <command>shutdown</command> with a time argument that is not + <literal>+0</literal> or + <literal>now</literal>.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>halt</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sysctl.d.xml b/man/sysctl.d.xml index c67a199fb5..5a35cfe2c8 100644 --- a/man/sysctl.d.xml +++ b/man/sysctl.d.xml @@ -19,158 +19,153 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> <refentry id="sysctl.d" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sysctl.d</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>sysctl.d</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>sysctl.d</refname> - <refpurpose>Configure kernel parameters at boot</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/sysctl.d/*.conf</filename></para> - <para><filename>/run/sysctl.d/*.conf</filename></para> - <para><filename>/usr/lib/sysctl.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>At boot, - <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - reads configuration files from the above directories - to configure - <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - kernel parameters.</para> - </refsect1> - - <refsect1> - <title>Configuration Format</title> - - <para>The configuration files contain a list of - variable assignments, separated by newlines. Empty - lines and lines whose first non-whitespace character - is <literal>#</literal> or <literal>;</literal> are - ignored.</para> - - <para>Note that either <literal>/</literal> or - <literal>.</literal> may be used as separators within - sysctl variable names. If the first separator is a - slash, remaining slashes and dots are left intact. If - the first separator is a dot, dots and slashes are - interchanged. <literal>kernel.domainname=foo</literal> - and <literal>kernel/domainname=foo</literal> are - equivalent and will cause <literal>foo</literal> to - be written to - <filename>/proc/sys/kernel/domainname</filename>. - Either - <literal>net.ipv4.conf.enp3s0/200.forwarding</literal> - or - <literal>net/ipv4/conf/enp3s0.200/forwarding</literal> - may be used to refer to - <filename>/proc/sys/net/ipv4/conf/enp3s0.200/forwarding</filename>. - </para> - - <para>The settings configured with - <filename>sysctl.d</filename> files will be applied - early on boot. The network interface-specific options - will also be applied individually for each network - interface as it shows up in the system. (More - specifically, - <filename>net.ipv4.conf.*</filename>, - <filename>net.ipv6.conf.*</filename>, - <filename>net.ipv4.neigh.*</filename> and <filename>net.ipv6.neigh.*</filename>).</para> - - <para>Many sysctl parameters only become available - when certain kernel modules are loaded. Modules are - usually loaded on demand, e.g. when certain hardware - is plugged in or network brought up. This means that - <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> which runs - during early boot will not configure such parameters - if they become available after it has run. To - set such parameters, it is recommended to add - an <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> rule to set those parameters when they become - available. Alternatively, a slightly simpler and - less efficient option is to add the module to - <citerefentry><refentrytitle>modules-load.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, causing it to be loaded statically - before sysctl settings are applied (see - example below).</para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - - <refsect1> - <title>Examples</title> - <example> - <title>Set kernel YP domain name</title> - <para><filename>/etc/sysctl.d/domain-name.conf</filename>: - </para> - - <programlisting>kernel.domainname=example.com</programlisting> - </example> - - <example> - <title>Disable packet filter on bridged packets (method one)</title> - <para><filename>/etc/udev/rules.d/99-bridge.rules</filename>: - </para> - - <programlisting>ACTION=="add", SUBSYSTEM=="module", KERNEL=="bridge", RUN+="/usr/lib/systemd/systemd-sysctl --prefix=/net/bridge" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sysctl.d</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>sysctl.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>sysctl.d</refname> + <refpurpose>Configure kernel parameters at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/sysctl.d/*.conf</filename></para> + <para><filename>/run/sysctl.d/*.conf</filename></para> + <para><filename>/usr/lib/sysctl.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>At boot, + <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + reads configuration files from the above directories to configure + <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + kernel parameters.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>The configuration files contain a list of variable + assignments, separated by newlines. Empty lines and lines whose + first non-whitespace character is <literal>#</literal> or + <literal>;</literal> are ignored.</para> + + <para>Note that either <literal>/</literal> or + <literal>.</literal> may be used as separators within sysctl + variable names. If the first separator is a slash, remaining + slashes and dots are left intact. If the first separator is a dot, + dots and slashes are interchanged. + <literal>kernel.domainname=foo</literal> and + <literal>kernel/domainname=foo</literal> are equivalent and will + cause <literal>foo</literal> to be written to + <filename>/proc/sys/kernel/domainname</filename>. Either + <literal>net.ipv4.conf.enp3s0/200.forwarding</literal> or + <literal>net/ipv4/conf/enp3s0.200/forwarding</literal> may be used + to refer to + <filename>/proc/sys/net/ipv4/conf/enp3s0.200/forwarding</filename>. + </para> + + <para>The settings configured with <filename>sysctl.d</filename> + files will be applied early on boot. The network + interface-specific options will also be applied individually for + each network interface as it shows up in the system. (More + specifically, <filename>net.ipv4.conf.*</filename>, + <filename>net.ipv6.conf.*</filename>, + <filename>net.ipv4.neigh.*</filename> and + <filename>net.ipv6.neigh.*</filename>).</para> + + <para>Many sysctl parameters only become available when certain + kernel modules are loaded. Modules are usually loaded on demand, + e.g. when certain hardware is plugged in or network brought up. + This means that + <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + which runs during early boot will not configure such parameters if + they become available after it has run. To set such parameters, it + is recommended to add an + <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> + rule to set those parameters when they become available. + Alternatively, a slightly simpler and less efficient option is to + add the module to + <citerefentry><refentrytitle>modules-load.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + causing it to be loaded statically before sysctl settings are + applied (see example below).</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + + <refsect1> + <title>Examples</title> + <example> + <title>Set kernel YP domain name</title> + <para><filename>/etc/sysctl.d/domain-name.conf</filename>: + </para> + + <programlisting>kernel.domainname=example.com</programlisting> + </example> + + <example> + <title>Disable packet filter on bridged packets (method one)</title> + <para><filename>/etc/udev/rules.d/99-bridge.rules</filename>: + </para> + + <programlisting>ACTION=="add", SUBSYSTEM=="module", KERNEL=="bridge", RUN+="/usr/lib/systemd/systemd-sysctl --prefix=/net/bridge" </programlisting> - <para><filename>/etc/sysctl.d/bridge.conf</filename>: - </para> + <para><filename>/etc/sysctl.d/bridge.conf</filename>: + </para> - <programlisting>net.bridge.bridge-nf-call-ip6tables = 0 + <programlisting>net.bridge.bridge-nf-call-ip6tables = 0 net.bridge.bridge-nf-call-iptables = 0 net.bridge.bridge-nf-call-arptables = 0 </programlisting> - </example> + </example> - <example> - <title>Disable packet filter on bridged packets (method two)</title> - <para><filename>/etc/modules-load.d/bridge.conf</filename>: - </para> + <example> + <title>Disable packet filter on bridged packets (method two)</title> + <para><filename>/etc/modules-load.d/bridge.conf</filename>: + </para> - <programlisting>bridge</programlisting> + <programlisting>bridge</programlisting> - <para><filename>/etc/sysctl.d/bridge.conf</filename>: - </para> + <para><filename>/etc/sysctl.d/bridge.conf</filename>: + </para> - <programlisting>net.bridge.bridge-nf-call-ip6tables = 0 + <programlisting>net.bridge.bridge-nf-call-ip6tables = 0 net.bridge.bridge-nf-call-iptables = 0 net.bridge.bridge-nf-call-arptables = 0 </programlisting> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sysctl.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sysctl.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>modprobe</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml index ecfc7af2af..61315a0d89 100644 --- a/man/systemd-analyze.xml +++ b/man/systemd-analyze.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,328 +22,300 @@ --> <refentry id="systemd-analyze" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-analyze</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - <author> - <contrib>Developer</contrib> - <firstname>Harald</firstname> - <surname>Hoyer</surname> - <email>harald@redhat.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-analyze</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-analyze</refname> - <refpurpose>Analyze system boot-up performance</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg>time</arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">blame</arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">critical-chain</arg> - <arg choice="opt" rep="repeat"><replaceable>UNIT</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">plot</arg> - <arg choice="opt">> file.svg</arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">dot</arg> - <arg choice="opt" rep="repeat"><replaceable>PATTERN</replaceable></arg> - <arg choice="opt">> file.dot</arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">dump</arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">set-log-level</arg> - <arg choice="opt"><replaceable>LEVEL</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-analyze</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="plain">verify</arg> - <arg choice="opt" rep="repeat"><replaceable>FILES</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-analyze</command> may be used - to determine system boot-up performance statistics and - retrieve other state and tracing information from the - system and service manager, and to verify the - correctness of unit files.</para> - - <para><command>systemd-analyze time</command> - prints the time spent in the kernel before - userspace has been reached, the time spent in the - initial RAM disk (initrd) before normal system - userspace has been reached, and the time normal system - userspace took to initialize. Note that these - measurements simply measure the time passed up to the - point where all system services have been spawned, but - not necessarily until they fully finished - initialization or the disk is idle.</para> - - <para><command>systemd-analyze blame</command> prints - a list of all running units, ordered by the time they - took to initialize. This information may be used to - optimize boot-up times. Note that the output might be - misleading as the initialization of one service might - be slow simply because it waits for the initialization - of another service to complete.</para> - - <para><command>systemd-analyze critical-chain [<replaceable>UNIT...</replaceable>]</command> - prints a tree of the time-critical chain of units - (for each of the specified <replaceable>UNIT</replaceable>s - or for the default target otherwise). - The time after the unit is active or started is printed - after the "@" character. The time the unit takes to - start is printed after the "+" character. - Note that the output might be misleading as the - initialization of one service might depend on socket - activation and because of the parallel execution - of units.</para> - - <para><command>systemd-analyze plot</command> prints - an SVG graphic detailing which system services have - been started at what time, highlighting the time they - spent on initialization.</para> - - <para><command>systemd-analyze dot</command> generates - textual dependency graph description in dot format for - further processing with the GraphViz - <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool. Use a command line like <command>systemd-analyze - dot | dot -Tsvg > systemd.svg</command> to generate a - graphical dependency tree. Unless - <option>--order</option> or <option>--require</option> - is passed, the generated graph will show both ordering - and requirement dependencies. Optional pattern - globbing style specifications - (e.g. <filename>*.target</filename>) may be given at - the end. A unit dependency is included in the graph if - any of these patterns match either the origin or - destination node.</para> - - <para><command>systemd-analyze dump</command> outputs - a (usually very long) human-readable serialization of - the complete server state. Its format is subject to - change without notice and should not be parsed by - applications.</para> - - <para><command>systemd-analyze set-log-level - <replaceable>LEVEL</replaceable></command> changes the - current log level of the <command>systemd</command> - daemon to <replaceable>LEVEL</replaceable> (accepts - the same values as <option>--log-level=</option> - described in - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> - - <para><command>systemd-analyze verify</command> will - load unit files and print warnings if any errors are - detected. Files specified on the command line will be - loaded, but also any other units referenced by - them. This command works by prepending the directories - for all command line arguments at the beginning of the - unit load path, which means that all units files found - in those directories will be used in preference to the - unit files found in the standard locations, even if - not listed explicitly.</para> - - <para>If no command is passed, <command>systemd-analyze - time</command> is implied.</para> - - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--user</option></term> - - <listitem><para>Operates on the user - systemd instance.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--system</option></term> - - <listitem><para>Operates on the system - systemd instance. This is the implied - default.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--order</option></term> - <term><option>--require</option></term> - - <listitem><para>When used in - conjunction with the - <command>dot</command> command (see - above), selects which dependencies are - shown in the dependency graph. If - <option>--order</option> is passed, - only dependencies of type - <varname>After=</varname> or - <varname>Before=</varname> are - shown. If <option>--require</option> - is passed, only dependencies of type - <varname>Requires=</varname>, - <varname>RequiresOverridable=</varname>, - <varname>Requisite=</varname>, - <varname>RequisiteOverridable=</varname>, - <varname>Wants=</varname> and - <varname>Conflicts=</varname> are - shown. If neither is passed, this shows - dependencies of all these - types.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--from-pattern=</option></term> - <term><option>--to-pattern=</option></term> - - <listitem><para>When used in - conjunction with the - <command>dot</command> command (see - above), this selects which relationships - are shown in the dependency graph. - They both require - <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> - patterns as arguments, which are - matched against left-hand and - right-hand, respectively, nodes of a - relationship. Each of these can be - used more than once, which means a - unit name must match one of the given - values.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--fuzz=</option><replaceable>timespan</replaceable></term> - - <listitem><para>When used in conjunction - with the <command>critical-chain</command> - command (see above), also show units, which - finished <replaceable>timespan</replaceable> earlier, than the - latest unit in the same level. The unit of - <replaceable>timespan</replaceable> is seconds - unless specified with a different unit, - e.g. "50ms".</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-man</option></term> - - <listitem><para>Do not invoke man to verify the existence - of man pages listen in <varname>Documentation=</varname>. - </para></listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>Examples for <command>dot</command></title> - - <example> - <title>Plots all dependencies of any unit whose - name starts with <literal>avahi-daemon</literal></title> - - <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg - $ eog avahi.svg</programlisting> - </example> - - <example> - <title>Plots the dependencies between all known target units</title> - - <programlisting>systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-analyze</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + <author> + <contrib>Developer</contrib> + <firstname>Harald</firstname> + <surname>Hoyer</surname> + <email>harald@redhat.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-analyze</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-analyze</refname> + <refpurpose>Analyze system boot-up performance</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg>time</arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">blame</arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">critical-chain</arg> + <arg choice="opt" rep="repeat"><replaceable>UNIT</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">plot</arg> + <arg choice="opt">> file.svg</arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">dot</arg> + <arg choice="opt" rep="repeat"><replaceable>PATTERN</replaceable></arg> + <arg choice="opt">> file.dot</arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">dump</arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">set-log-level</arg> + <arg choice="opt"><replaceable>LEVEL</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-analyze</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">verify</arg> + <arg choice="opt" rep="repeat"><replaceable>FILES</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-analyze</command> may be used to determine + system boot-up performance statistics and retrieve other state and + tracing information from the system and service manager, and to + verify the correctness of unit files.</para> + + <para><command>systemd-analyze time</command> prints the time + spent in the kernel before userspace has been reached, the time + spent in the initial RAM disk (initrd) before normal system + userspace has been reached, and the time normal system userspace + took to initialize. Note that these measurements simply measure + the time passed up to the point where all system services have + been spawned, but not necessarily until they fully finished + initialization or the disk is idle.</para> + + <para><command>systemd-analyze blame</command> prints a list of + all running units, ordered by the time they took to initialize. + This information may be used to optimize boot-up times. Note that + the output might be misleading as the initialization of one + service might be slow simply because it waits for the + initialization of another service to complete.</para> + + <para><command>systemd-analyze critical-chain + [<replaceable>UNIT...</replaceable>]</command> prints a tree of + the time-critical chain of units (for each of the specified + <replaceable>UNIT</replaceable>s or for the default target + otherwise). The time after the unit is active or started is + printed after the "@" character. The time the unit takes to start + is printed after the "+" character. Note that the output might be + misleading as the initialization of one service might depend on + socket activation and because of the parallel execution of + units.</para> + + <para><command>systemd-analyze plot</command> prints an SVG + graphic detailing which system services have been started at what + time, highlighting the time they spent on initialization.</para> + + <para><command>systemd-analyze dot</command> generates textual + dependency graph description in dot format for further processing + with the GraphViz + <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool. Use a command line like <command>systemd-analyze dot | dot + -Tsvg > systemd.svg</command> to generate a graphical dependency + tree. Unless <option>--order</option> or + <option>--require</option> is passed, the generated graph will + show both ordering and requirement dependencies. Optional pattern + globbing style specifications (e.g. <filename>*.target</filename>) + may be given at the end. A unit dependency is included in the + graph if any of these patterns match either the origin or + destination node.</para> + + <para><command>systemd-analyze dump</command> outputs a (usually + very long) human-readable serialization of the complete server + state. Its format is subject to change without notice and should + not be parsed by applications.</para> + + <para><command>systemd-analyze set-log-level + <replaceable>LEVEL</replaceable></command> changes the current log + level of the <command>systemd</command> daemon to + <replaceable>LEVEL</replaceable> (accepts the same values as + <option>--log-level=</option> described in + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> + + <para><command>systemd-analyze verify</command> will load unit + files and print warnings if any errors are detected. Files + specified on the command line will be loaded, but also any other + units referenced by them. This command works by prepending the + directories for all command line arguments at the beginning of the + unit load path, which means that all units files found in those + directories will be used in preference to the unit files found in + the standard locations, even if not listed explicitly.</para> + + <para>If no command is passed, <command>systemd-analyze + time</command> is implied.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--user</option></term> + + <listitem><para>Operates on the user systemd + instance.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--system</option></term> + + <listitem><para>Operates on the system systemd instance. This + is the implied default.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--order</option></term> + <term><option>--require</option></term> + + <listitem><para>When used in conjunction with the + <command>dot</command> command (see above), selects which + dependencies are shown in the dependency graph. If + <option>--order</option> is passed, only dependencies of type + <varname>After=</varname> or <varname>Before=</varname> are + shown. If <option>--require</option> is passed, only + dependencies of type <varname>Requires=</varname>, + <varname>RequiresOverridable=</varname>, + <varname>Requisite=</varname>, + <varname>RequisiteOverridable=</varname>, + <varname>Wants=</varname> and <varname>Conflicts=</varname> + are shown. If neither is passed, this shows dependencies of + all these types.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--from-pattern=</option></term> + <term><option>--to-pattern=</option></term> + + <listitem><para>When used in conjunction with the + <command>dot</command> command (see above), this selects which + relationships are shown in the dependency graph. They both + require + <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> + patterns as arguments, which are matched against left-hand and + right-hand, respectively, nodes of a relationship. Each of + these can be used more than once, which means a unit name must + match one of the given values.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--fuzz=</option><replaceable>timespan</replaceable></term> + + <listitem><para>When used in conjunction with the + <command>critical-chain</command> command (see above), also + show units, which finished <replaceable>timespan</replaceable> + earlier, than the latest unit in the same level. The unit of + <replaceable>timespan</replaceable> is seconds unless + specified with a different unit, e.g. + "50ms".</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-man</option></term> + + <listitem><para>Do not invoke man to verify the existence of + man pages listen in <varname>Documentation=</varname>. + </para></listitem> + </varlistentry> + + <xi:include href="user-system-options.xml" xpointer="host" /> + <xi:include href="user-system-options.xml" xpointer="machine" /> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + <xi:include href="standard-options.xml" xpointer="no-pager" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>Examples for <command>dot</command></title> + + <example> + <title>Plots all dependencies of any unit whose name starts with + <literal>avahi-daemon</literal></title> + + <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg + $ eog avahi.svg</programlisting> + </example> + + <example> + <title>Plots the dependencies between all known target units</title> + + <programlisting>systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg $ eog targets.svg</programlisting> - </example> - </refsect1> + </example> + </refsect1> - <refsect1> - <title>Examples for <command>verify</command></title> + <refsect1> + <title>Examples for <command>verify</command></title> - <para>The following errors are currently detected:</para> - <itemizedlist> - <listitem><para>unknown sections and - directives, </para></listitem> + <para>The following errors are currently detected:</para> + <itemizedlist> + <listitem><para>unknown sections and directives, + </para></listitem> - <listitem><para>missing dependencies which are - required to start the given unit, - </para></listitem> + <listitem><para>missing dependencies which are required to start + the given unit, </para></listitem> - <listitem><para>man pages listed in - <varname>Documentation=</varname> which are - not found in the system,</para></listitem> + <listitem><para>man pages listed in + <varname>Documentation=</varname> which are not found in the + system,</para></listitem> - <listitem><para>commands listed in - <varname>ExecStart=</varname> and similar - which are not found in the system or not - executable.</para></listitem> - </itemizedlist> + <listitem><para>commands listed in <varname>ExecStart=</varname> + and similar which are not found in the system or not + executable.</para></listitem> + </itemizedlist> - <example> - <title>Misspelt directives</title> + <example> + <title>Misspelt directives</title> - <programlisting>$ cat ./user.slice + <programlisting>$ cat ./user.slice [Unit] WhatIsThis=11 Documentation=man:nosuchfile(1) @@ -356,17 +328,17 @@ $ systemd-analyze verify ./user.slice [./user.slice:9] Unknown lvalue 'WhatIsThis' in section 'Unit' [./user.slice:13] Unknown section 'Service'. Ignoring. Error: org.freedesktop.systemd1.LoadFailed: - Unit different.service failed to load: - No such file or directory. + Unit different.service failed to load: + No such file or directory. Failed to create user.slice/start: Invalid argument user.slice: man nosuchfile(1) command failed with code 16 - </programlisting> - </example> + </programlisting> + </example> - <example> - <title>Missing service units</title> + <example> + <title>Missing service units</title> - <programlisting>$ tail ./a.socket ./b.socket + <programlisting>$ tail ./a.socket ./b.socket ==> ./a.socket <== [Socket] ListenStream=100 @@ -379,18 +351,18 @@ Accept=yes $ systemd-analyze verify ./a.socket ./b.socket Service a.service not loaded, a.socket cannot be started. Service b@0.service not loaded, b.socket cannot be started. - </programlisting> - </example> - </refsect1> - - <xi:include href="less-variables.xml" /> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + </programlisting> + </example> + </refsect1> + + <xi:include href="less-variables.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-ask-password-console.service.xml b/man/systemd-ask-password-console.service.xml index 536dad9c67..479e5f2e5b 100644 --- a/man/systemd-ask-password-console.service.xml +++ b/man/systemd-ask-password-console.service.xml @@ -21,76 +21,73 @@ --> <refentry id="systemd-ask-password-console.service"> - <refentryinfo> - <title>systemd-ask-password-console.service</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-ask-password-console.service</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-ask-password-console.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-ask-password-console.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-ask-password-console.service</refname> - <refname>systemd-ask-password-console.path</refname> - <refname>systemd-ask-password-wall.service</refname> - <refname>systemd-ask-password-wall.path</refname> - <refpurpose>Query the user for system passwords on the - console and via wall</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-ask-password-console.service</refname> + <refname>systemd-ask-password-console.path</refname> + <refname>systemd-ask-password-wall.service</refname> + <refname>systemd-ask-password-wall.path</refname> + <refpurpose>Query the user for system passwords on the + console and via wall</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>systemd-ask-password-console.service</filename></para> - <para><filename>systemd-ask-password-console.path</filename></para> - <para><filename>systemd-ask-password-wall.service</filename></para> - <para><filename>systemd-ask-password-wall.path</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>systemd-ask-password-console.service</filename></para> + <para><filename>systemd-ask-password-console.path</filename></para> + <para><filename>systemd-ask-password-wall.service</filename></para> + <para><filename>systemd-ask-password-wall.path</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-ask-password-console.service</filename> - is a system service that queries the user for system - passwords (such as hard disk encryption keys and SSL - certificate passphrases) on the console. It is - intended to be used during boot to ensure proper - handling of passwords necessary for - boot. <filename>systemd-ask-password-wall.service</filename> - is a system service that informs all logged in users - for system passwords via - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>. It - is intended to be used after boot to ensure that users - are properly notified.</para> + <para><filename>systemd-ask-password-console.service</filename> is + a system service that queries the user for system passwords (such + as hard disk encryption keys and SSL certificate passphrases) on + the console. It is intended to be used during boot to ensure + proper handling of passwords necessary for boot. + <filename>systemd-ask-password-wall.service</filename> is a system + service that informs all logged in users for system passwords via + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + It is intended to be used after boot to ensure that users are + properly notified.</para> - <para>See the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents"> - developer documentation</ulink> for more information - about the system password logic.</para> + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents"> + developer documentation</ulink> for more information about the + system password logic.</para> - <para>Note that these services invoke - <citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry> - with either the <command>--watch --console</command> - or <command>--watch --wall</command> command line - parameters.</para> - </refsect1> + <para>Note that these services invoke + <citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry> + with either the <command>--watch --console</command> or + <command>--watch --wall</command> command line parameters.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-tty-ask-password-agent</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-ask-password.xml b/man/systemd-ask-password.xml index 448df62100..877c71af53 100644 --- a/man/systemd-ask-password.xml +++ b/man/systemd-ask-password.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,169 +22,153 @@ --> <refentry id="systemd-ask-password" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-ask-password</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-ask-password</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-ask-password</refname> - <refpurpose>Query the user for a system password</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-ask-password</command> may be - used to query a system password or passphrase from the - user, using a question message specified on the - command line. When run from a TTY it will query a - password on the TTY and print it to standard output. When run - with no TTY or with <option>--no-tty</option> it will - query the password system-wide and allow active users - to respond via several agents. The latter is - only available to privileged processes.</para> - - <para>The purpose of this tool is to query system-wide - passwords -- 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> - - <para>Existing agents are: a boot-time password agent - asking the user for passwords using Plymouth; a - boot-time password agent querying the user directly on - the console; an agent requesting password input via a - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - message; an agent suitable for running in a GNOME - session; a command line agent which can be started - temporarily to process queued password requests; a TTY - agent that is temporarily spawned during - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - invocations.</para> - - <para>Additional password agents may be implemented - according to the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd - Password Agent Specification</ulink>.</para> - - <para>If a password is queried on a TTY, the user may - press TAB to hide the asterisks normally shown for - each character typed. Pressing Backspace as first key - achieves the same effect.</para> - - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--icon=</option></term> - - <listitem><para>Specify an icon name - alongside the password query, which may - be used in all agents supporting - graphical display. The icon name - should follow the <ulink - url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG - Icon Naming - Specification</ulink>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--timeout=</option></term> - - <listitem><para>Specify the query - timeout in seconds. Defaults to - 90s. A timeout of 0 waits indefinitely. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--echo</option></term> - - <listitem><para>Echo the user input - instead of masking it. This is useful - when using - <filename>systemd-ask-password</filename> - to query for usernames. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--no-tty</option></term> - - <listitem><para>Never ask for password - on current TTY even if one is - available. Always use agent - system.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--accept-cached</option></term> - - <listitem><para>If passed, accept - cached passwords, i.e. passwords - previously typed in.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--multiple</option></term> - - <listitem><para>When used in - conjunction with - <option>--accept-cached</option> - accept multiple passwords. This will - output one password per - line.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-ask-password</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-ask-password</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-ask-password</refname> + <refpurpose>Query the user for a system password</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-ask-password <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">MESSAGE</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-ask-password</command> may be used to query + a system password or passphrase from the user, using a question + message specified on the command line. When run from a TTY it will + query a password on the TTY and print it to standard output. When + run with no TTY or with <option>--no-tty</option> it will query + the password system-wide and allow active users to respond via + several agents. The latter is only available to privileged + processes.</para> + + <para>The purpose of this tool is to query system-wide passwords + -- 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> + + <para>Existing agents are: a boot-time password agent asking the + user for passwords using Plymouth; a boot-time password agent + querying the user directly on the console; an agent requesting + password input via a + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + message; an agent suitable for running in a GNOME session; a + command line agent which can be started temporarily to process + queued password requests; a TTY agent that is temporarily spawned + during + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + invocations.</para> + + <para>Additional password agents may be implemented according to + the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd + Password Agent Specification</ulink>.</para> + + <para>If a password is queried on a TTY, the user may press TAB to + hide the asterisks normally shown for each character typed. + Pressing Backspace as first key achieves the same effect.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--icon=</option></term> + + <listitem><para>Specify an icon name alongside the password + query, which may be used in all agents supporting graphical + display. The icon name should follow the <ulink + url="http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html">XDG + Icon Naming Specification</ulink>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--timeout=</option></term> + + <listitem><para>Specify the query timeout in seconds. Defaults + to 90s. A timeout of 0 waits indefinitely. </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--echo</option></term> + + <listitem><para>Echo the user input instead of masking it. + This is useful when using + <filename>systemd-ask-password</filename> to query for + usernames. </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-tty</option></term> + + <listitem><para>Never ask for password on current TTY even if + one is available. Always use agent system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--accept-cached</option></term> + + <listitem><para>If passed, accept cached passwords, i.e. + passwords previously typed in.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--multiple</option></term> + + <listitem><para>When used in conjunction with + <option>--accept-cached</option> accept multiple passwords. + This will output one password per line.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-backlight@.service.xml b/man/systemd-backlight@.service.xml index 21c6437efa..a259f5d583 100644 --- a/man/systemd-backlight@.service.xml +++ b/man/systemd-backlight@.service.xml @@ -21,79 +21,74 @@ --> <refentry id="systemd-backlight@.service" conditional='ENABLE_BACKLIGHT'> - <refentryinfo> - <title>systemd-backlight@.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-backlight@.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-backlight@.service</refname> - <refname>systemd-backlight</refname> - <refpurpose>Load and save the display backlight brightness at boot and shutdown</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-backlight@.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-backlight</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-backlight@.service</filename> - is a service that restores the display backlight - brightness at early boot and saves it at shutdown. On - disk, the backlight brightness is stored in - <filename>/var/lib/systemd/backlight/</filename>. During - loading, if udev property - <option>ID_BACKLIGHT_CLAMP</option> is not set to - false value, the brightness is clamped to a value of - at least 1 or 5% of maximum brightness, whichever is - greater. This restriction will be removed when the - kernel allows user space to reliably set a brightness - value which does not turn off the display.</para> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-backlight</filename> understands - the following kernel command line parameter:</para> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>systemd.restore_state=</varname></term> - - <listitem><para>Takes a boolean - argument. Defaults to - <literal>1</literal>. If - <literal>0</literal>, does not restore - the backlight settings on boot. However, - settings will still be stored on shutdown. - </para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-backlight@.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-backlight@.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-backlight@.service</refname> + <refname>systemd-backlight</refname> + <refpurpose>Load and save the display backlight brightness at boot and shutdown</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-backlight@.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-backlight</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-backlight@.service</filename> is a service + that restores the display backlight brightness at early boot and + saves it at shutdown. On disk, the backlight brightness is stored + in <filename>/var/lib/systemd/backlight/</filename>. During + loading, if udev property <option>ID_BACKLIGHT_CLAMP</option> is + not set to false value, the brightness is clamped to a value of at + least 1 or 5% of maximum brightness, whichever is greater. This + restriction will be removed when the kernel allows user space to + reliably set a brightness value which does not turn off the + display.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-backlight</filename> understands the + following kernel command line parameter:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>systemd.restore_state=</varname></term> + + <listitem><para>Takes a boolean argument. Defaults to + <literal>1</literal>. If <literal>0</literal>, does not + restore the backlight settings on boot. However, settings will + still be stored on shutdown. </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-binfmt.service.xml b/man/systemd-binfmt.service.xml index cb96048369..66d264389e 100644 --- a/man/systemd-binfmt.service.xml +++ b/man/systemd-binfmt.service.xml @@ -21,56 +21,55 @@ --> <refentry id="systemd-binfmt.service" conditional='ENABLE_BINFMT'> - <refentryinfo> - <title>systemd-binfmt.service</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-binfmt.service</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-binfmt.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-binfmt.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-binfmt.service</refname> - <refname>systemd-binfmt</refname> - <refpurpose>Configure additional binary formats for executables at boot</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-binfmt.service</refname> + <refname>systemd-binfmt</refname> + <refpurpose>Configure additional binary formats for executables at boot</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>systemd-binfmt.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-binfmt</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>systemd-binfmt.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-binfmt</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-binfmt.service</filename> is - an early-boot service that registers additional binary - formats for executables in the kernel.</para> + <para><filename>systemd-binfmt.service</filename> is an early-boot + service that registers additional binary formats for executables + in the kernel.</para> - <para>See - <citerefentry><refentrytitle>binfmt.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about the configuration of this - service.</para> - </refsect1> + <para>See + <citerefentry><refentrytitle>binfmt.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the configuration of this service.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>binfmt.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>wine</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>binfmt.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>wine</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-bootchart.xml b/man/systemd-bootchart.xml index ff86be2ad8..ab883c262d 100644 --- a/man/systemd-bootchart.xml +++ b/man/systemd-bootchart.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -27,311 +27,298 @@ --> <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> + 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-cat.xml b/man/systemd-cat.xml index e5a867be22..38ddf66d27 100644 --- a/man/systemd-cat.xml +++ b/man/systemd-cat.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,173 +22,157 @@ --> <refentry id="systemd-cat" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-cat</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-cat</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-cat</refname> - <refpurpose>Connect a pipeline or program's output with the journal</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-cat <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-cat <arg choice="opt" rep="repeat">OPTIONS</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-cat</command> may be used to - connect the standard input and output of a process to the - journal, or as a filter tool in a shell pipeline to - pass the output the previous pipeline element - generates to the journal.</para> - - <para>If no parameter is passed, - <command>systemd-cat</command> will write - everything it reads from standard input (stdin) to the journal.</para> - - <para>If parameters are passed, they are executed as - command line with standard output (stdout) and standard - error output (stderr) connected to the journal, so - that all it writes is stored in the journal.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <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>-t</option></term> - <term><option>--identifier=</option></term> - - <listitem><para>Specify a short string - that is used to identify the logging - tool. If not specified, no identification - string is written to the journal.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-p</option></term> - <term><option>--priority=</option></term> - - <listitem><para>Specify the default - priority level for the logged - messages. Pass one of - <literal>emerg</literal>, - <literal>alert</literal>, - <literal>crit</literal>, - <literal>err</literal>, - <literal>warning</literal>, - <literal>notice</literal>, - <literal>info</literal>, - <literal>debug</literal>, or a - value between 0 and 7 (corresponding - to the same named levels). These - priority values are the same as - defined by - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Defaults - to <literal>info</literal>. Note that - this simply controls the default, - individual lines may be logged with - different levels if they are prefixed - accordingly. For details see - <option>--level-prefix=</option> - below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--level-prefix=</option></term> - - <listitem><para>Controls whether lines - read are parsed for syslog priority - level prefixes. If enabled (the - default), a line prefixed with a - priority prefix such as - <literal><5></literal> is logged - at priority 5 - (<literal>notice</literal>), and - similar for the other priority - levels. Takes a boolean - argument.</para></listitem> - </varlistentry> - - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Invoke a program</title> - - <para>This calls <filename noindex='true'>/bin/ls</filename> - with standard output and error connected to the - journal:</para> - - <programlisting># systemd-cat ls</programlisting> - </example> - - <example> - <title>Usage in a shell pipeline</title> - - <para>This builds a shell pipeline also - invoking <filename>/bin/ls</filename> and - writes the output it generates to the - journal:</para> - - <programlisting># ls | systemd-cat</programlisting> - </example> - - <para>Even though the two examples have very similar - effects the first is preferable since only one process - is running at a time, and both stdout and stderr are - captured while in the second example, only stdout is - captured.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>logger</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-cat</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-cat</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-cat</refname> + <refpurpose>Connect a pipeline or program's output with the journal</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-cat <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-cat <arg choice="opt" rep="repeat">OPTIONS</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-cat</command> may be used to connect the + standard input and output of a process to the journal, or as a + filter tool in a shell pipeline to pass the output the previous + pipeline element generates to the journal.</para> + + <para>If no parameter is passed, <command>systemd-cat</command> + will write everything it reads from standard input (stdin) to the + journal.</para> + + <para>If parameters are passed, they are executed as command line + with standard output (stdout) and standard error output (stderr) + connected to the journal, so that all it writes is stored in the + journal.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <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>-t</option></term> + <term><option>--identifier=</option></term> + + <listitem><para>Specify a short string that is used to + identify the logging tool. If not specified, no identification + string is written to the journal.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-p</option></term> + <term><option>--priority=</option></term> + + <listitem><para>Specify the default priority level for the + logged messages. Pass one of + <literal>emerg</literal>, + <literal>alert</literal>, + <literal>crit</literal>, + <literal>err</literal>, + <literal>warning</literal>, + <literal>notice</literal>, + <literal>info</literal>, + <literal>debug</literal>, or a + value between 0 and 7 (corresponding to the same named + levels). These priority values are the same as defined by + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Defaults to <literal>info</literal>. Note that this simply + controls the default, individual lines may be logged with + different levels if they are prefixed accordingly. For details + see <option>--level-prefix=</option> below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--level-prefix=</option></term> + + <listitem><para>Controls whether lines read are parsed for + syslog priority level prefixes. If enabled (the default), a + line prefixed with a priority prefix such as + <literal><5></literal> is logged at priority 5 + (<literal>notice</literal>), and similar for the other + priority levels. Takes a boolean argument.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Invoke a program</title> + + <para>This calls <filename noindex='true'>/bin/ls</filename> + with standard output and error connected to the journal:</para> + + <programlisting># systemd-cat ls</programlisting> + </example> + + <example> + <title>Usage in a shell pipeline</title> + + <para>This builds a shell pipeline also invoking + <filename>/bin/ls</filename> and writes the output it generates + to the journal:</para> + + <programlisting># ls | systemd-cat</programlisting> + </example> + + <para>Even though the two examples have very similar effects the + first is preferable since only one process is running at a time, + and both stdout and stderr are captured while in the second + example, only stdout is captured.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logger</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-cgls.xml b/man/systemd-cgls.xml index d8dbe6862e..e8f0368f48 100644 --- a/man/systemd-cgls.xml +++ b/man/systemd-cgls.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,124 +22,118 @@ --> <refentry id="systemd-cgls" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-cgls</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-cgls</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-cgls</refname> - <refpurpose>Recursively show control group contents</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-cgls</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat">CGROUP</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-cgls</command> recursively - shows the contents of the selected Linux control group - hierarchy in a tree. If arguments are specified, shows - all member processes of the specified control groups - plus all their subgroups and their members. The - control groups may either be specified by their full - file paths or are assumed in the systemd control group - hierarchy. If no argument is specified and the current - working directory is beneath the control group mount - point <filename>/sys/fs/cgroup</filename>, shows the contents - of the control group the working directory refers - to. Otherwise, the full systemd control group hierarchy - is shown.</para> - - <para>By default, empty control groups are not - shown.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--all</option></term> - - <listitem><para>Do not hide empty - control groups in the - output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-l</option></term> - <term><option>--full</option></term> - - <listitem><para>Do not ellipsize - process tree members.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-k</option></term> - - <listitem><para>Include kernel - threads in output.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-M <replaceable>MACHINE</replaceable></option></term> - <term><option>--machine=<replaceable>MACHINE</replaceable></option></term> - - <listitem><para>Limit control groups shown to - the part corresponding to the - container <replaceable>MACHINE</replaceable>. - </para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-cgtop</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-cgls</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-cgls</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-cgls</refname> + <refpurpose>Recursively show control group contents</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-cgls</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt" rep="repeat">CGROUP</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-cgls</command> recursively shows the + contents of the selected Linux control group hierarchy in a tree. + If arguments are specified, shows all member processes of the + specified control groups plus all their subgroups and their + members. The control groups may either be specified by their full + file paths or are assumed in the systemd control group hierarchy. + If no argument is specified and the current working directory is + beneath the control group mount point + <filename>/sys/fs/cgroup</filename>, shows the contents of the + control group the working directory refers to. Otherwise, the full + systemd control group hierarchy is shown.</para> + + <para>By default, empty control groups are not shown.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--all</option></term> + + <listitem><para>Do not hide empty control groups in the + output.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-l</option></term> + <term><option>--full</option></term> + + <listitem><para>Do not ellipsize process tree members.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-k</option></term> + + <listitem><para>Include kernel threads in output. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-M <replaceable>MACHINE</replaceable></option></term> + <term><option>--machine=<replaceable>MACHINE</replaceable></option></term> + + <listitem><para>Limit control groups shown to the part + corresponding to the container + <replaceable>MACHINE</replaceable>.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + <xi:include href="standard-options.xml" xpointer="no-pager" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cgtop</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-cgtop.xml b/man/systemd-cgtop.xml index 8ee552a012..f1ff218c39 100644 --- a/man/systemd-cgtop.xml +++ b/man/systemd-cgtop.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,249 +22,232 @@ --> <refentry id="systemd-cgtop" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-cgtop</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-cgtop</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-cgtop</refname> - <refpurpose>Show top control groups by their resource usage</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-cgtop</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-cgtop</command> shows the top - control groups of the local Linux control group - hierarchy, ordered by their CPU, memory, or disk I/O load. The - display is refreshed in regular intervals (by default - every 1s), similar in style to - <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - If <command>systemd-cgtop</command> is not connected - to a tty, only one iteration is performed and no - columns headers are printed. This mode is suitable for - scripting.</para> - - <para>Resource usage is only accounted for control - groups in the relevant hierarchy, i.e. CPU usage is - only accounted for control groups in the - <literal>cpuacct</literal> hierarchy, memory usage - only for those in <literal>memory</literal> and disk - I/O usage for those in <literal>blkio</literal>. If - resource monitoring for these resources is required, - it is recommended to add the - <varname>CPUAccounting=1</varname>, - <varname>MemoryAccounting=1</varname> and - <varname>BlockIOAccounting=1</varname> settings in the - unit files in question. See - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - - <para>To emphasize this: unless - <literal>CPUAccounting=1</literal>, - <literal>MemoryAccounting=1</literal> and - <literal>BlockIOAccounting=1</literal> are enabled for - the services in question, no resource accounting will - be available for system services and the data shown by - <command>systemd-cgtop</command> will be - incomplete.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>-p</option></term> - - <listitem><para>Order by control group - path name.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-t</option></term> - - <listitem><para>Order by number of - tasks in control - group (i.e. threads and processes).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-c</option></term> - - <listitem><para>Order by CPU load.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-m</option></term> - - <listitem><para>Order by memory usage.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-i</option></term> - - <listitem><para>Order by disk I/O load.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-b</option></term> - <term><option>--batch</option></term> - - <listitem><para>Run in "batch" mode: - do not accept input and run until the - iteration limit set with - <option>--iterations</option> is - exhausted or until killed. This mode - could be useful for sending output - from <command>systemd-cgtop</command> - to other programs or to a - file.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-n</option></term> - <term><option>--iterations=</option></term> - - <listitem><para>Perform only this many - iterations.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-d</option></term> - <term><option>--delay=</option></term> - - <listitem><para>Specify refresh delay - in seconds (or if one of - <literal>ms</literal>, - <literal>us</literal>, - <literal>min</literal> is specified as - unit in this time - unit).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--depth=</option></term> - - <listitem><para>Maximum control group - tree traversal depth. Specifies how - deep <command>systemd-cgtop</command> - shall traverse the control group - hierarchies. If 0 is specified, only - the root group is monitored. For 1, - only the first level of control groups - is monitored, and so on. Defaults to - 3.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - - <refsect1> - <title>Keys</title> - - <para><command>systemd-cgtop</command> is an - interactive tool and may be controlled via user input - using the following keys:</para> - - <variablelist> - <varlistentry> - <term>h</term> - - <listitem><para>Shows a short help text.</para></listitem> - </varlistentry> - - <varlistentry> - <term>SPACE</term> - - <listitem><para>Immediately refresh output.</para></listitem> - </varlistentry> - - <varlistentry> - <term>q</term> - - <listitem><para>Terminate the program.</para></listitem> - </varlistentry> - - - <varlistentry> - <term>p</term> - <term>t</term> - <term>c</term> - <term>m</term> - <term>i</term> - - <listitem><para>Sort the control groups - by path, number of tasks, CPU load, - memory usage, or IO - load, respectively.</para></listitem> - </varlistentry> - - <varlistentry> - <term>%</term> - - <listitem><para>Toggle between showing CPU time as - time or percentage.</para></listitem> - </varlistentry> - - <varlistentry> - <term>+</term> - <term>-</term> - - <listitem><para>Increase - or decrease refresh - delay, respectively.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-cgtop</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-cgtop</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-cgtop</refname> + <refpurpose>Show top control groups by their resource usage</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-cgtop</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-cgtop</command> shows the top control + groups of the local Linux control group hierarchy, ordered by + their CPU, memory, or disk I/O load. The display is refreshed in + regular intervals (by default every 1s), similar in style to + <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + If <command>systemd-cgtop</command> is not connected to a tty, + only one iteration is performed and no columns headers are + printed. This mode is suitable for scripting.</para> + + <para>Resource usage is only accounted for control groups in the + relevant hierarchy, i.e. CPU usage is only accounted for control + groups in the <literal>cpuacct</literal> hierarchy, memory usage + only for those in <literal>memory</literal> and disk I/O usage for + those in <literal>blkio</literal>. If resource monitoring for + these resources is required, it is recommended to add the + <varname>CPUAccounting=1</varname>, + <varname>MemoryAccounting=1</varname> and + <varname>BlockIOAccounting=1</varname> settings in the unit files + in question. See + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + + <para>To emphasize this: unless + <literal>CPUAccounting=1</literal>, + <literal>MemoryAccounting=1</literal> and + <literal>BlockIOAccounting=1</literal> are enabled for the + services in question, no resource accounting will be available for + system services and the data shown by + <command>systemd-cgtop</command> will be incomplete.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>-p</option></term> + + <listitem><para>Order by control group + path name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-t</option></term> + + <listitem><para>Order by number of tasks in control group + (i.e. threads and processes).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-c</option></term> + + <listitem><para>Order by CPU load.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-m</option></term> + + <listitem><para>Order by memory usage.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-i</option></term> + + <listitem><para>Order by disk I/O load.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-b</option></term> + <term><option>--batch</option></term> + + <listitem><para>Run in "batch" mode: do not accept input and + run until the iteration limit set with + <option>--iterations</option> is exhausted or until killed. + This mode could be useful for sending output from + <command>systemd-cgtop</command> to other programs or to a + file.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-n</option></term> + <term><option>--iterations=</option></term> + + <listitem><para>Perform only this many iterations. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-d</option></term> + <term><option>--delay=</option></term> + + <listitem><para>Specify refresh delay in seconds (or if one of + <literal>ms</literal>, + <literal>us</literal>, + <literal>min</literal> is specified as unit in this time + unit).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--depth=</option></term> + + <listitem><para>Maximum control group tree traversal depth. + Specifies how deep <command>systemd-cgtop</command> shall + traverse the control group hierarchies. If 0 is specified, + only the root group is monitored. For 1, only the first level + of control groups is monitored, and so on. Defaults to + 3.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + + <refsect1> + <title>Keys</title> + + <para><command>systemd-cgtop</command> is an interactive tool and + may be controlled via user input using the following keys:</para> + + <variablelist> + <varlistentry> + <term>h</term> + + <listitem><para>Shows a short help text.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SPACE</term> + + <listitem><para>Immediately refresh output.</para></listitem> + </varlistentry> + + <varlistentry> + <term>q</term> + + <listitem><para>Terminate the program.</para></listitem> + </varlistentry> + + + <varlistentry> + <term>p</term> + <term>t</term> + <term>c</term> + <term>m</term> + <term>i</term> + + <listitem><para>Sort the control groups by path, number of + tasks, CPU load, memory usage, or IO load, respectively. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>%</term> + + <listitem><para>Toggle between showing CPU time as time or + percentage.</para></listitem> + </varlistentry> + + <varlistentry> + <term>+</term> + <term>-</term> + + <listitem><para>Increase or decrease refresh delay, + respectively.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-cryptsetup-generator.xml b/man/systemd-cryptsetup-generator.xml index c8753cef37..0e48e79346 100644 --- a/man/systemd-cryptsetup-generator.xml +++ b/man/systemd-cryptsetup-generator.xml @@ -21,199 +21,175 @@ --> <refentry id="systemd-cryptsetup-generator" conditional='HAVE_LIBCRYPTSETUP'> - <refentryinfo> - <title>systemd-cryptsetup-generator</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-cryptsetup-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-cryptsetup-generator</refname> - <refpurpose>Unit generator for <filename>/etc/crypttab</filename></refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-cryptsetup-generator</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-cryptsetup-generator</filename> - is a generator that translates - <filename>/etc/crypttab</filename> into native systemd - units early at boot and when configuration of the - system manager is reloaded. This will create - <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - units as necessary.</para> - - <para><filename>systemd-cryptsetup-generator</filename> - implements the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator - specification</ulink>.</para> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-cryptsetup-generator</filename> understands - the following kernel command line parameters:</para> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>luks=</varname></term> - <term><varname>rd.luks=</varname></term> - - <listitem><para>Takes a boolean - argument. Defaults to - <literal>yes</literal>. If - <literal>no</literal>, disables the - generator - entirely. <varname>rd.luks=</varname> - is honored only by initial RAM disk - (initrd) while - <varname>luks=</varname> is honored - by both the main system and the - initrd. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>luks.crypttab=</varname></term> - <term><varname>rd.luks.crypttab=</varname></term> - - <listitem><para>Takes a boolean - argument. Defaults to - <literal>yes</literal>. If - <literal>no</literal>, causes the - generator to ignore any devices - configured in - <filename>/etc/crypttab</filename> - (<varname>luks.uuid=</varname> will - still work - however). <varname>rd.luks.crypttab=</varname> - is honored only by initial RAM disk - (initrd) while - <varname>luks.crypttab=</varname> is - honored by both the main system and - the initrd. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>luks.uuid=</varname></term> - <term><varname>rd.luks.uuid=</varname></term> - - <listitem><para>Takes a LUKS superblock - UUID as argument. This will - activate the specified device as part - of the boot process as if it was - listed in - <filename>/etc/crypttab</filename>. This - option may be specified more than once - in order to set up multiple - devices. <varname>rd.luks.uuid=</varname> - is honored only by initial RAM disk - (initrd) while - <varname>luks.uuid=</varname> is - honored by both the main system and - the initrd.</para> - <para>If /etc/crypttab contains entries with - the same UUID, then the name, keyfile and options - specified there will be used. Otherwise the device - will have the name <literal>luks-UUID</literal>.</para> - <para>If /etc/crypttab exists, only those UUIDs - specified on the kernel command line - will be activated in the initrd or the real root.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>luks.name=</varname></term> - <term><varname>rd.luks.name=</varname></term> - - <listitem><para>Takes a LUKS super - block UUID followed by an '=' and a name. This implies - <varname>rd.luks.uuid=</varname> or <varname>luks.uuid=</varname> - and will additionally make the LUKS device given by - the UUID appear under the provided name.</para> - - <para><varname>rd.luks.name=</varname> - is honored only by initial RAM disk - (initrd) while - <varname>luks.name=</varname> is - honored by both the main system and - the initrd.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>luks.options=</varname></term> - <term><varname>rd.luks.options=</varname></term> - - <listitem><para>Takes a LUKS super - block UUID followed by an '=' and a string - of options separated by commas as argument. - This will override the options for the given - UUID.</para> - <para>If only a list of options, without an - UUID, is specified, they apply to any UUIDs not - specified elsewhere, and without an entry in - /etc/crypttab.</para><para> - <varname>rd.luks.options=</varname> - is honored only by initial RAM disk - (initrd) while - <varname>luks.options=</varname> is - honored by both the main system and - the initrd.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>luks.key=</varname></term> - <term><varname>rd.luks.key=</varname></term> - - <listitem><para>Takes a password file name as argument or - a LUKS super block UUID followed by a '=' and a password - file name.</para> - - <para>For those entries specified with - <varname>rd.luks.uuid=</varname> or <varname>luks.uuid=</varname>, - the password file will be set to the one specified by - <varname>rd.luks.key=</varname> or <varname>luks.key=</varname> - of the corresponding UUID, or the password file that was specified - without a UUID.</para> - <para><varname>rd.luks.key=</varname> - is honored only by initial RAM disk - (initrd) while - <varname>luks.key=</varname> is - honored by both the main system and - the initrd.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-cryptsetup-generator</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-cryptsetup-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-cryptsetup-generator</refname> + <refpurpose>Unit generator for <filename>/etc/crypttab</filename></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-cryptsetup-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-cryptsetup-generator</filename> is a + generator that translates <filename>/etc/crypttab</filename> into + native systemd units early at boot and when configuration of the + system manager is reloaded. This will create + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + units as necessary.</para> + + <para><filename>systemd-cryptsetup-generator</filename> + implements the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator + specification</ulink>.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-cryptsetup-generator</filename> + understands the following kernel command line parameters:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>luks=</varname></term> + <term><varname>rd.luks=</varname></term> + + <listitem><para>Takes a boolean argument. Defaults to + <literal>yes</literal>. If <literal>no</literal>, disables the + generator entirely. <varname>rd.luks=</varname> is honored + only by initial RAM disk (initrd) while + <varname>luks=</varname> is honored by both the main system + and the initrd. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks.crypttab=</varname></term> + <term><varname>rd.luks.crypttab=</varname></term> + + <listitem><para>Takes a boolean argument. Defaults to + <literal>yes</literal>. If <literal>no</literal>, causes the + generator to ignore any devices configured in + <filename>/etc/crypttab</filename> + (<varname>luks.uuid=</varname> will still work however). + <varname>rd.luks.crypttab=</varname> is honored only by + initial RAM disk (initrd) while + <varname>luks.crypttab=</varname> is honored by both the main + system and the initrd. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks.uuid=</varname></term> + <term><varname>rd.luks.uuid=</varname></term> + + <listitem><para>Takes a LUKS superblock UUID as argument. This + will activate the specified device as part of the boot process + as if it was listed in <filename>/etc/crypttab</filename>. + This option may be specified more than once in order to set up + multiple devices. <varname>rd.luks.uuid=</varname> is honored + only by initial RAM disk (initrd) while + <varname>luks.uuid=</varname> is honored by both the main + system and the initrd.</para> + <para>If /etc/crypttab contains entries with the same UUID, + then the name, keyfile and options specified there will be + used. Otherwise the device will have the name + <literal>luks-UUID</literal>.</para> + <para>If /etc/crypttab exists, only those UUIDs + specified on the kernel command line + will be activated in the initrd or the real root.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks.name=</varname></term> + <term><varname>rd.luks.name=</varname></term> + + <listitem><para>Takes a LUKS super block UUID followed by an + <literal>=</literal> and a name. This implies + <varname>rd.luks.uuid=</varname> or + <varname>luks.uuid=</varname> and will additionally make the + LUKS device given by the UUID appear under the provided + name.</para> + + <para><varname>rd.luks.name=</varname> is honored only by + initial RAM disk (initrd) while <varname>luks.name=</varname> + is honored by both the main system and the initrd.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks.options=</varname></term> + <term><varname>rd.luks.options=</varname></term> + + <listitem><para>Takes a LUKS super block UUID followed by an + <literal>=</literal> and a string of options separated by + commas as argument. This will override the options for the + given UUID.</para> + <para>If only a list of options, without an UUID, is + specified, they apply to any UUIDs not specified elsewhere, + and without an entry in + <filename>/etc/crypttab</filename>.</para><para> + <varname>rd.luks.options=</varname> is honored only by initial + RAM disk (initrd) while <varname>luks.options=</varname> is + honored by both the main system and the initrd.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>luks.key=</varname></term> + <term><varname>rd.luks.key=</varname></term> + + <listitem><para>Takes a password file name as argument or a + LUKS super block UUID followed by a <literal>=</literal> and a + password file name.</para> + + <para>For those entries specified with + <varname>rd.luks.uuid=</varname> or + <varname>luks.uuid=</varname>, the password file will be set + to the one specified by <varname>rd.luks.key=</varname> or + <varname>luks.key=</varname> of the corresponding UUID, or the + password file that was specified without a UUID.</para> + <para><varname>rd.luks.key=</varname> + is honored only by initial RAM disk + (initrd) while + <varname>luks.key=</varname> is + honored by both the main system and + the initrd.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-cryptsetup@.service.xml b/man/systemd-cryptsetup@.service.xml index 6fa2e0cdd0..bd03637deb 100644 --- a/man/systemd-cryptsetup@.service.xml +++ b/man/systemd-cryptsetup@.service.xml @@ -21,67 +21,65 @@ --> <refentry id="systemd-cryptsetup@.service" conditional='HAVE_LIBCRYPTSETUP'> - <refentryinfo> - <title>systemd-cryptsetup@.service</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-cryptsetup@.service</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-cryptsetup@.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-cryptsetup@.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-cryptsetup@.service</refname> - <refname>systemd-cryptsetup</refname> - <refpurpose>Full disk decryption logic</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-cryptsetup@.service</refname> + <refname>systemd-cryptsetup</refname> + <refpurpose>Full disk decryption logic</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>systemd-cryptsetup@.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-cryptsetup</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>systemd-cryptsetup@.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-cryptsetup</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-cryptsetup@.service</filename> - is a service responsible for setting up encrypted - block devices. It is instantiated for each device that - requires decryption for access.</para> + <para><filename>systemd-cryptsetup@.service</filename> is a + service responsible for setting up encrypted block devices. It is + instantiated for each device that requires decryption for + access.</para> - <para><filename>systemd-cryptsetup@.service</filename> - will ask for hard disk passwords via the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents"> - password agent logic</ulink>, in order to query the - user for the password using the right mechanism at - boot and during runtime.</para> + <para><filename>systemd-cryptsetup@.service</filename> will ask + for hard disk passwords via the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents"> + password agent logic</ulink>, in order to query the user for the + password using the right mechanism at boot and during + runtime.</para> - <para>At early boot and when the system manager - configuration is reloaded this - <filename>/etc/crypttab</filename> is translated into - <filename>systemd-cryptsetup@.service</filename> units - by - <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </refsect1> + <para>At early boot and when the system manager configuration is + reloaded this <filename>/etc/crypttab</filename> is translated + into <filename>systemd-cryptsetup@.service</filename> units by + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-debug-generator.xml b/man/systemd-debug-generator.xml index a2bef5fe28..74c3b2620e 100644 --- a/man/systemd-debug-generator.xml +++ b/man/systemd-debug-generator.xml @@ -21,78 +21,77 @@ --> <refentry id="systemd-debug-generator"> - <refentryinfo> - <title>systemd-debug-generator</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-debug-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-debug-generator</refname> - <refpurpose>Generator for enabling a runtime debug shell and masking specific units at boot</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-debug-generator</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-debug-generator</filename> is - a generator that reads the kernel command line and - understands three options:</para> - - <para>If the <option>systemd.mask=</option> option is - specified and followed by a unit name, this unit is - masked for the runtime, similar to the effect of - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>mask</command> command. This is useful to - boot with certain units removed from the initial boot - transaction for debugging system startup. May be - specified more than once.</para> - - <para>If the <option>systemd.wants=</option> option is - specified and followed by a unit name, a start job for - this unit is added to the initial transaction. This is - useful to start one or more additional units at - boot. May be specified more than once.</para> - - <para>If the <option>systemd.debug-shell</option> - option is specified, the debug shell service - <literal>debug-shell.service</literal> is pulled into - the boot transaction. It will spawn a debug shell on - tty9 during early system startup. Note that the shell - may also be turned on persistently by enabling it with - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>enable</command> command.</para> - - <para><filename>systemd-debug-generator</filename> - implements the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator - specification</ulink>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-debug-generator</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-debug-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-debug-generator</refname> + <refpurpose>Generator for enabling a runtime debug shell and + masking specific units at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-debug-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-debug-generator</filename> is a generator + that reads the kernel command line and understands three + options:</para> + + <para>If the <option>systemd.mask=</option> option is specified + and followed by a unit name, this unit is masked for the runtime, + similar to the effect of + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>mask</command> command. This is useful to boot with + certain units removed from the initial boot transaction for + debugging system startup. May be specified more than once.</para> + + <para>If the <option>systemd.wants=</option> option is specified + and followed by a unit name, a start job for this unit is added to + the initial transaction. This is useful to start one or more + additional units at boot. May be specified more than once.</para> + + <para>If the <option>systemd.debug-shell</option> option is + specified, the debug shell service + <literal>debug-shell.service</literal> is pulled into the boot + transaction. It will spawn a debug shell on tty9 during early + system startup. Note that the shell may also be turned on + persistently by enabling it with + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>enable</command> command.</para> + + <para><filename>systemd-debug-generator</filename> implements the + <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator + specification</ulink>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-delta.xml b/man/systemd-delta.xml index 2175f96550..fd81b2c907 100644 --- a/man/systemd-delta.xml +++ b/man/systemd-delta.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,195 +22,184 @@ --> <refentry id="systemd-delta" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-delta</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-delta</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-delta</refname> - <refpurpose>Find overridden configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-delta</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat"><replaceable>PREFIX</replaceable><optional>/<replaceable>SUFFIX</replaceable></optional>|<replaceable>SUFFIX</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-delta</command> may be used to - identify and compare configuration files that override - other configuration files. Files in - <filename>/etc</filename> have highest priority, files - in <filename>/run</filename> have the second highest - priority, ..., files in <filename>/lib</filename> have - lowest priority. Files in a directory with higher - priority override files with the same name in - directories of lower priority. In addition, certain - configuration files can have <literal>.d</literal> - directories which contain "drop-in" files with - configuration snippets which augment the main - configuration file. "Drop-in" files can be overriden - in the same way by placing files with the same name in - a directory of higher priority (except that in case of - "drop-in" files, both the "drop-in" file name and the - name of the containing directory, which corresponds to - the name of the main configuration file, must match). - For a fuller explanation, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para>The command line argument will be split into a - prefix and a suffix. Either is optional. The prefix - must be one of the directories containing - configuration files (<filename>/etc</filename>, - <filename>/run</filename>, - <filename>/usr/lib</filename>, ...). If it is given, - only overriding files contained in this directory will - be shown. Otherwise, all overriding files will be - shown. The suffix must be a name of a subdirectory - containing configuration files like - <filename>tmpfiles.d</filename>, - <filename>sysctl.d</filename> or - <filename>systemd/system</filename>. If it is given, - only configuration files in this subdirectory (across - all configuration paths) will be analyzed. Otherwise, - all configuration files will be analyzed. If the - command line argument is not given at all, all - configuration files will be analyzed. See below for - some examples.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>-t</option></term> - <term><option>--type=</option></term> - - <listitem><para>When listing the - differences, only list those that are - asked for. The list itself is a - comma-separated list of desired - difference types.</para> - - <para>Recognized types are: - - <variablelist> - <varlistentry> - <term><varname>masked</varname></term> - - <listitem><para>Show masked files</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>equivalent</varname></term> - - <listitem><para>Show overridden - files that while overridden, do - not differ in content.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>redirected</varname></term> - - <listitem><para>Show files that - are redirected to another.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>overridden</varname></term> - - <listitem><para>Show overridden, - and changed files.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>extended</varname></term> - - <listitem><para>Show *.conf files in drop-in - directories for units.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>unchanged</varname></term> - - <listitem><para>Show unmodified - files too.</para></listitem> - </varlistentry> - </variablelist> - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--diff=</option></term> - - <listitem><para>When showing modified - files, when a file is overridden show a - diff as well. This option takes a - boolean argument. If omitted, it defaults - to <option>true</option>.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>To see all local configuration:</para> - <programlisting>systemd-delta</programlisting> - - <para>To see all runtime configuration:</para> - <programlisting>systemd-delta /run</programlisting> - - <para>To see all system unit configuration changes:</para> - <programlisting>systemd-delta systemd/system</programlisting> - - <para>To see all runtime "drop-in" changes for system units:</para> - <programlisting>systemd-delta --type=extended /run/systemd/system</programlisting> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-delta</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-delta</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-delta</refname> + <refpurpose>Find overridden configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-delta</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt" rep="repeat"><replaceable>PREFIX</replaceable><optional>/<replaceable>SUFFIX</replaceable></optional>|<replaceable>SUFFIX</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-delta</command> may be used to identify and + compare configuration files that override other configuration + files. Files in <filename>/etc</filename> have highest priority, + files in <filename>/run</filename> have the second highest + priority, ..., files in <filename>/lib</filename> have lowest + priority. Files in a directory with higher priority override files + with the same name in directories of lower priority. In addition, + certain configuration files can have <literal>.d</literal> + directories which contain "drop-in" files with configuration + snippets which augment the main configuration file. "Drop-in" + files can be overriden in the same way by placing files with the + same name in a directory of higher priority (except that in case + of "drop-in" files, both the "drop-in" file name and the name of + the containing directory, which corresponds to the name of the + main configuration file, must match). For a fuller explanation, + see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>The command line argument will be split into a prefix and a + suffix. Either is optional. The prefix must be one of the + directories containing configuration files + (<filename>/etc</filename>, <filename>/run</filename>, + <filename>/usr/lib</filename>, ...). If it is given, only + overriding files contained in this directory will be shown. + Otherwise, all overriding files will be shown. The suffix must be + a name of a subdirectory containing configuration files like + <filename>tmpfiles.d</filename>, <filename>sysctl.d</filename> or + <filename>systemd/system</filename>. If it is given, only + configuration files in this subdirectory (across all configuration + paths) will be analyzed. Otherwise, all configuration files will + be analyzed. If the command line argument is not given at all, all + configuration files will be analyzed. See below for some + examples.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>-t</option></term> + <term><option>--type=</option></term> + + <listitem><para>When listing the differences, only list those + that are asked for. The list itself is a comma-separated list + of desired difference types.</para> + + <para>Recognized types are: + + <variablelist> + <varlistentry> + <term><varname>masked</varname></term> + + <listitem><para>Show masked files</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>equivalent</varname></term> + + <listitem><para>Show overridden files that while + overridden, do not differ in content.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>redirected</varname></term> + + <listitem><para>Show files that are redirected to + another.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>overridden</varname></term> + + <listitem><para>Show overridden, and changed + files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>extended</varname></term> + + <listitem><para>Show <filename>*.conf</filename> files + in drop-in directories for units.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>unchanged</varname></term> + + <listitem><para>Show unmodified files + too.</para></listitem> + </varlistentry> + </variablelist> + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--diff=</option></term> + + <listitem><para>When showing modified files, when a file is + overridden show a diff as well. This option takes a boolean + argument. If omitted, it defaults to + <option>true</option>.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + <xi:include href="standard-options.xml" xpointer="no-pager" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>To see all local configuration:</para> + <programlisting>systemd-delta</programlisting> + + <para>To see all runtime configuration:</para> + <programlisting>systemd-delta /run</programlisting> + + <para>To see all system unit configuration changes:</para> + <programlisting>systemd-delta systemd/system</programlisting> + + <para>To see all runtime "drop-in" changes for system units:</para> + <programlisting>systemd-delta --type=extended /run/systemd/system</programlisting> + </refsect1> - <refsect1> - <title>Exit status</title> + <refsect1> + <title>Exit status</title> - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-detect-virt.xml b/man/systemd-detect-virt.xml index d8e881cf2e..40755a24d0 100644 --- a/man/systemd-detect-virt.xml +++ b/man/systemd-detect-virt.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,210 +22,202 @@ --> <refentry id="systemd-detect-virt" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-detect-virt</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-detect-virt</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-detect-virt</refname> - <refpurpose>Detect execution in a virtualized environment</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-detect-virt <arg choice="opt" rep="repeat">OPTIONS</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-detect-virt</command> detects - execution in a virtualized environment. It identifies - the virtualization technology and can distinguish full - VM virtualization from container - virtualization. <filename>systemd-detect-virt</filename> - exits with a return value of 0 (success) if a - virtualization technology is detected, and non-zero - (error) otherwise. By default any type of - virtualization is detected, and the options - <option>--container</option> and <option>--vm</option> - can be used to limit what types of virtualization are - detected.</para> - - <para>When executed without <option>--quiet</option> - will print a short identifier for the detected - virtualization technology. The following technologies - are currently identified:</para> - - <table> - <title>Known virtualization technologies (both - VM, i.e. full hardware virtualization, - and container, i.e. shared kernel virtualization)</title> - <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <colspec colname="type" /> - <colspec colname="id" /> - <colspec colname="product" /> - <thead> - <row> - <entry>Type</entry> - <entry>ID</entry> - <entry>Product</entry> - </row> - </thead> - <tbody> - <row> - <entry morerows="8">VM</entry> - <entry><varname>qemu</varname></entry> - <entry>QEMU software virtualization</entry> - </row> - - <row> - <entry><varname>kvm</varname></entry> - <entry>Linux KVM kernel virtual machine</entry> - </row> - - <row> - <entry><varname>zvm</varname></entry> - <entry>s390 z/VM</entry> - </row> - - <row> - <entry><varname>vmware</varname></entry> - <entry>VMware Workstation or Server, and related products</entry> - </row> - - <row> - <entry><varname>microsoft</varname></entry> - <entry>Hyper-V, also known as Viridian or Windows Server Virtualization</entry> - </row> - - <row> - <entry><varname>oracle</varname></entry> - <entry>Oracle VM VirtualBox (historically marketed by innotek and Sun Microsystems)</entry> - </row> - - <row> - <entry><varname>xen</varname></entry> - <entry>Xen hypervisor (only domU, not dom0)</entry> - </row> - - <row> - <entry><varname>bochs</varname></entry> - <entry>Bochs Emulator</entry> - </row> - - <row> - <entry><varname>uml</varname></entry> - <entry>User-mode Linux</entry> - </row> - - <row> - <entry morerows="5">container</entry> - <entry><varname>openvz</varname></entry> - <entry>OpenVZ/Virtuozzo</entry> - </row> - - <row> - <entry><varname>lxc</varname></entry> - <entry>Linux container implementation by LXC</entry> - </row> - - <row> - <entry><varname>lxc-libvirt</varname></entry> - <entry>Linux container implementation by libvirt</entry> - </row> - - <row> - <entry><varname>systemd-nspawn</varname></entry> - <entry>systemd's minimal container implementation, see <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry> - </row> - - <row> - <entry><varname>docker</varname></entry> - <entry>Docker container manager</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>If multiple virtualization solutions are used, - only the "innermost" is detected and identified. That - means if both VM virtualization and container - virtualization are used in conjunction, only the latter - will be identified (unless <option>--vm</option> is - passed).</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>-c</option></term> - <term><option>--container</option></term> - - <listitem><para>Only detects container - virtualization (i.e. shared kernel - virtualization).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-v</option></term> - <term><option>--vm</option></term> - - <listitem><para>Only detects VM - virtualization (i.e. full hardware - virtualization).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-q</option></term> - <term><option>--quiet</option></term> - - <listitem><para>Suppress output of the - virtualization technology - identifier.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>If a virtualization technology is detected, 0 is - returned, a non-zero code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-detect-virt</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-detect-virt</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-detect-virt</refname> + <refpurpose>Detect execution in a virtualized environment</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-detect-virt <arg choice="opt" rep="repeat">OPTIONS</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-detect-virt</command> detects execution in + a virtualized environment. It identifies the virtualization + technology and can distinguish full VM virtualization from + container virtualization. <filename>systemd-detect-virt</filename> + exits with a return value of 0 (success) if a virtualization + technology is detected, and non-zero (error) otherwise. By default + any type of virtualization is detected, and the options + <option>--container</option> and <option>--vm</option> can be used + to limit what types of virtualization are detected.</para> + + <para>When executed without <option>--quiet</option> will print a + short identifier for the detected virtualization technology. The + following technologies are currently identified:</para> + + <table> + <title>Known virtualization technologies (both + VM, i.e. full hardware virtualization, + and container, i.e. shared kernel virtualization)</title> + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname="type" /> + <colspec colname="id" /> + <colspec colname="product" /> + <thead> + <row> + <entry>Type</entry> + <entry>ID</entry> + <entry>Product</entry> + </row> + </thead> + <tbody> + <row> + <entry morerows="8">VM</entry> + <entry><varname>qemu</varname></entry> + <entry>QEMU software virtualization</entry> + </row> + + <row> + <entry><varname>kvm</varname></entry> + <entry>Linux KVM kernel virtual machine</entry> + </row> + + <row> + <entry><varname>zvm</varname></entry> + <entry>s390 z/VM</entry> + </row> + + <row> + <entry><varname>vmware</varname></entry> + <entry>VMware Workstation or Server, and related products</entry> + </row> + + <row> + <entry><varname>microsoft</varname></entry> + <entry>Hyper-V, also known as Viridian or Windows Server Virtualization</entry> + </row> + + <row> + <entry><varname>oracle</varname></entry> + <entry>Oracle VM VirtualBox (historically marketed by innotek and Sun Microsystems)</entry> + </row> + + <row> + <entry><varname>xen</varname></entry> + <entry>Xen hypervisor (only domU, not dom0)</entry> + </row> + + <row> + <entry><varname>bochs</varname></entry> + <entry>Bochs Emulator</entry> + </row> + + <row> + <entry><varname>uml</varname></entry> + <entry>User-mode Linux</entry> + </row> + + <row> + <entry morerows="5">container</entry> + <entry><varname>openvz</varname></entry> + <entry>OpenVZ/Virtuozzo</entry> + </row> + + <row> + <entry><varname>lxc</varname></entry> + <entry>Linux container implementation by LXC</entry> + </row> + + <row> + <entry><varname>lxc-libvirt</varname></entry> + <entry>Linux container implementation by libvirt</entry> + </row> + + <row> + <entry><varname>systemd-nspawn</varname></entry> + <entry>systemd's minimal container implementation, see <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></entry> + </row> + + <row> + <entry><varname>docker</varname></entry> + <entry>Docker container manager</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>If multiple virtualization solutions are used, only the + "innermost" is detected and identified. That means if both VM + virtualization and container virtualization are used in + conjunction, only the latter will be identified (unless + <option>--vm</option> is passed).</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>-c</option></term> + <term><option>--container</option></term> + + <listitem><para>Only detects container virtualization (i.e. + shared kernel virtualization).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-v</option></term> + <term><option>--vm</option></term> + + <listitem><para>Only detects VM virtualization (i.e. full + hardware virtualization).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-q</option></term> + <term><option>--quiet</option></term> + + <listitem><para>Suppress output of the virtualization + technology identifier.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>If a virtualization technology is detected, 0 is returned, a + non-zero code otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-efi-boot-generator.xml b/man/systemd-efi-boot-generator.xml index 3a79dfb8df..b2d8d65e3d 100644 --- a/man/systemd-efi-boot-generator.xml +++ b/man/systemd-efi-boot-generator.xml @@ -21,68 +21,68 @@ --> <refentry id="systemd-efi-boot-generator"> - <refentryinfo> - <title>systemd-efi-boot-generator</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-efi-boot-generator</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-efi-boot-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-efi-boot-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-efi-boot-generator</refname> - <refpurpose>Generator for automatically mounting the - EFI System Partition used by the current boot to - <filename>/boot</filename></refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-efi-boot-generator</refname> + <refpurpose>Generator for automatically mounting the + EFI System Partition used by the current boot to + <filename>/boot</filename></refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-efi-boot-generator</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-efi-boot-generator</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-efi-boot-generator</filename> - is a generator that automatically creates mount and - automount units for the EFI System Partition (ESP), - mounting it to <filename>/boot</filename>. Note that - this generator will execute no operation on non-EFI - systems, on systems where the boot loader does not - communicate the used ESP to the OS, on systems where - <filename>/boot</filename> is an explicitly configured - mount (for example, listed in <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>) or where the <filename>/boot</filename> mount - point is non-empty. Since this generator creates an - automount unit, the mount will only be activated - on-demand, when accessed.</para> + <para><filename>systemd-efi-boot-generator</filename> is a + generator that automatically creates mount and automount units for + the EFI System Partition (ESP), mounting it to + <filename>/boot</filename>. Note that this generator will execute + no operation on non-EFI systems, on systems where the boot loader + does not communicate the used ESP to the OS, on systems where + <filename>/boot</filename> is an explicitly configured mount (for + example, listed in + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>) + or where the <filename>/boot</filename> mount point is non-empty. + Since this generator creates an automount unit, the mount will + only be activated on-demand, when accessed.</para> - <para><filename>systemd-efi-boot-generator</filename> - implements the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator - specification</ulink>.</para> - </refsect1> + <para><filename>systemd-efi-boot-generator</filename> implements + the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator + specification</ulink>.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>gummiboot</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>gummiboot</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-escape.xml b/man/systemd-escape.xml index b2a4a9ce8c..0c3b230526 100644 --- a/man/systemd-escape.xml +++ b/man/systemd-escape.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,172 +22,157 @@ --> <refentry id="systemd-escape" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-escape</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-escape</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-escape</refname> - <refpurpose>Escape strings for usage in system unit names</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-escape <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">STRING</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-escape</command> may be used to - escape strings for inclusion in systemd unit - names. The command may be used to escape and to undo - escaping of strings.</para> - - <para>The command takes any number of strings on the - command line, and will process them individually, one - after the other. It will output them separated by - spaces to stdout.</para> - - <para>By default this command will escape the strings - passed, unless <option>--unescape</option> is passed - which results in the inverse operation being - applied. If <option>--mangle</option> a special mode - of escaping is applied instead, which assumes a string - to be already escaped but will escape everything that - appears obviously non-escaped.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--suffix=</option></term> - - <listitem><para>Appends the specified - unit type suffix to the escaped - string. Takes one of the unit types - supported by systemd, such as - <literal>.service</literal> or - <literal>.mount</literal>. May not be - used in conjunction with - <option>--template=</option>, - <option>--unescape</option> or - <option>--mangle</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--template=</option></term> - - <listitem><para>Inserts the escaped - strings in a unit name template. Takes - a unit name template such as - <filename>foobar@.service</filename> - May not be used in conjunction with - <option>--suffix=</option>, - <option>--unescape</option> or - <option>--mangle</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--path</option></term> - <term><option>-p</option></term> - - <listitem><para>When escaping or - unescaping a string, assume it refers - to a file system path. This enables - special processing of the initial - <literal>/</literal> of the - path.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--unescape</option></term> - - <listitem><para>Instead of escaping - the specified strings, undo the - escaping, reversing the operation. May - not be used in conjunction with - <option>--suffix=</option>, - <option>--template=</option> or - <option>--mangle</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--mangle</option></term> - - <listitem><para>Like - <option>--escape</option>, but only - escape characters that are obviously - not escaped yet, and possibly - automatically append an appropriate - unit type suffix to the string. May - not be used in conjunction with - <option>--suffix=</option>, - <option>--template=</option> or - <option>--unescape</option>.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Examples</title> - - <para>Escape a single string:</para> - <programlisting>$ systemd-escape 'Hallöchen, Meister' + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-escape</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-escape</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-escape</refname> + <refpurpose>Escape strings for usage in system unit names</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-escape</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt" rep="repeat">STRING</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-escape</command> may be used to escape + strings for inclusion in systemd unit names. The command may be + used to escape and to undo escaping of strings.</para> + + <para>The command takes any number of strings on the command line, + and will process them individually, one after the other. It will + output them separated by spaces to stdout.</para> + + <para>By default this command will escape the strings passed, + unless <option>--unescape</option> is passed which results in the + inverse operation being applied. If <option>--mangle</option> a + special mode of escaping is applied instead, which assumes a + string to be already escaped but will escape everything that + appears obviously non-escaped.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--suffix=</option></term> + + <listitem><para>Appends the specified unit type suffix to the + escaped string. Takes one of the unit types supported by + systemd, such as <literal>.service</literal> or + <literal>.mount</literal>. May not be used in conjunction with + <option>--template=</option>, <option>--unescape</option> or + <option>--mangle</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--template=</option></term> + + <listitem><para>Inserts the escaped strings in a unit name + template. Takes a unit name template such as + <filename>foobar@.service</filename> May not be used in + conjunction with <option>--suffix=</option>, + <option>--unescape</option> or + <option>--mangle</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--path</option></term> + <term><option>-p</option></term> + + <listitem><para>When escaping or unescaping a string, assume + it refers to a file system path. This enables special + processing of the initial <literal>/</literal> of the + path.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--unescape</option></term> + + <listitem><para>Instead of escaping the specified strings, + undo the escaping, reversing the operation. May not be used in + conjunction with <option>--suffix=</option>, + <option>--template=</option> or + <option>--mangle</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--mangle</option></term> + + <listitem><para>Like <option>--escape</option>, but only + escape characters that are obviously not escaped yet, and + possibly automatically append an appropriate unit type suffix + to the string. May not be used in conjunction with + <option>--suffix=</option>, <option>--template=</option> or + <option>--unescape</option>.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Escape a single string:</para> + <programlisting>$ systemd-escape 'Hallöchen, Meister' Hall\xc3\xb6chen\x2c\x20Meister</programlisting> - <para>To undo escaping on a single string:</para> - <programlisting>$ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister' + <para>To undo escaping on a single string:</para> + <programlisting>$ systemd-escape -u 'Hall\xc3\xb6chen\x2c\x20Meister' Hallöchen, Meister</programlisting> - <para>To generate the mount unit for a path:</para> - <programlisting>$ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/" + <para>To generate the mount unit for a path:</para> + <programlisting>$ systemd-escape -p --suffix=mount "/tmp//waldi/foobar/" tmp-waldi-foobar.mount</programlisting> - <para>To generate instance names of three strings</para> - <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III' + <para>To generate instance names of three strings</para> + <programlisting>$ systemd-escape --template=systemd-nspawn@.service 'My Container 1' 'containerb' 'container/III' systemd-nspawn@My\x20Container\x201.service systemd-nspawn@containerb.service systemd-nspawn@container-III.service</programlisting> - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-firstboot.xml b/man/systemd-firstboot.xml index 8d97302244..5f19aaf476 100644 --- a/man/systemd-firstboot.xml +++ b/man/systemd-firstboot.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,265 +22,238 @@ --> <refentry id="systemd-firstboot" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-firstboot</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-firstboot</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-firstboot</refname> - <refname>systemd-firstboot.service</refname> - <refpurpose>Initialize basic system settings on or before the first boot-up of a system</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-firstboot</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - </cmdsynopsis> - - <para><filename>systemd-firstboot.service</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-firstboot</command> initializes - the most basic system settings interactively on the - first boot, or optionally non-interactively when a - system image is created. The following settings may be - set up:</para> - - <itemizedlist> - <listitem><para>The system locale, more - specifically the two locale variables - <varname>LANG=</varname> and - <varname>LC_MESSAGES</varname></para></listitem> - - <listitem><para>The system time zone</para></listitem> - - <listitem><para>The system host name</para></listitem> - - <listitem><para>The machine ID of the system</para></listitem> - - <listitem><para>The root user's password</para></listitem> - </itemizedlist> - - <para>Each of the fields may either be queried - interactively from the users, set non-interactively on - the tool's command line, or be copied from a host - system that is used to set up the system image.</para> - - <para>If a setting is already initialized it will not - be overwritten and the user will not be prompted for - the setting.</para> - - <para>Note that this tool operates directly on the - file system and does not involve any running system - services, unlike - <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - or - <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This - allows <command>systemd-firstboot</command> to operate - on mounted but not booted disk images and in early - boot. It is not recommended to use - <command>systemd-firstboot</command> on the running - system while it is up.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path - as an argument. All paths will be - prefixed with the given alternate - <replaceable>root</replaceable> path, - including config search paths. This is - useful to operate on a system image - mounted to the specified directory - instead of the host system itself. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--locale=<replaceable>LOCALE</replaceable></option></term> - <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term> - - <listitem><para>Sets the system - locale, more specifically the - <varname>LANG=</varname> and - <varname>LC_MESSAGES</varname> - settings. The argument should be a - valid locale identifier, such as - <literal>de_DE.UTF-8</literal>. This - controls the - <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - configuration file.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term> - - <listitem><para>Sets the system time - zone. The argument should be a valid - time zone identifier, such as - <literal>Europe/Berlin</literal>. This - controls the - <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry> - symlink.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term> - - <listitem><para>Sets the system - hostname. The argument should be a - host name, compatible with DNS. This - controls the - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> - configuration file.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--machine-id=<replaceable>ID</replaceable></option></term> - - <listitem><para>Sets the system's machine ID. This - controls the - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - file.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term> - <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term> - - <listitem><para>Sets the password of - the system's root user. This creates a - <citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry> - file. This setting exists in two - forms: - <option>--root-password=</option> - accepts the password to set directly - on the command line, - <option>--root-password-file=</option> - reads it from a file. Note that - it is not recommended specifying - passwords on the command line as other - users might be able to see them - simply by invoking - <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--prompt-locale</option></term> - <term><option>--prompt-timezone</option></term> - <term><option>--prompt-hostname</option></term> - <term><option>--prompt-root-password</option></term> - - <para>Prompt the user interactively - for a specific basic setting. Note - that any explicit configuration - settings specified on the command line - take precedence, and the user is not - prompted for it.</para> - </varlistentry> - - <varlistentry> - <term><option>--prompt</option></term> - - <para>Query the user for locale, - timezone, hostname and root - password. This is equivalent to - specifying - <option>--prompt-locale</option>, - <option>--prompt-timezone</option>, - <option>--prompt-hostname</option>, - <option>--prompt-root-password</option> - in combination.</para> - </varlistentry> - - <varlistentry> - <term><option>--copy-locale</option></term> - <term><option>--copy-timezone</option></term> - <term><option>--copy-root-password</option></term> - - <para>Copy a specific basic setting - from the host. This only works in - combination with - <option>--root=</option> (see - above).</para> - </varlistentry> - - <varlistentry> - <term><option>--copy</option></term> - - <para>Copy locale, time zone and root - password from the host. This is - equivalent to specifying - <option>--copy-locale</option>, - <option>--copy-timezone</option>, - <option>--copy-root-password</option> - in combination.</para> - </varlistentry> - - <varlistentry> - <term><option>--setup-machine-id</option></term> - - <para>Initialize the system's machine - ID to a random ID. This only works in - combination with - <option>--root=</option>.</para> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-firstboot</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-firstboot</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-firstboot</refname> + <refname>systemd-firstboot.service</refname> + <refpurpose>Initialize basic system settings on or before the first boot-up of a system</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-firstboot</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + </cmdsynopsis> + + <para><filename>systemd-firstboot.service</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-firstboot</command> initializes the most + basic system settings interactively on the first boot, or + optionally non-interactively when a system image is created. The + following settings may be set up:</para> + + <itemizedlist> + <listitem><para>The system locale, more specifically the two + locale variables <varname>LANG=</varname> and + <varname>LC_MESSAGES</varname></para></listitem> + + <listitem><para>The system time zone</para></listitem> + + <listitem><para>The system host name</para></listitem> + + <listitem><para>The machine ID of the system</para></listitem> + + <listitem><para>The root user's password</para></listitem> + </itemizedlist> + + <para>Each of the fields may either be queried interactively from + the users, set non-interactively on the tool's command line, or be + copied from a host system that is used to set up the system + image.</para> + + <para>If a setting is already initialized it will not be + overwritten and the user will not be prompted for the + setting.</para> + + <para>Note that this tool operates directly on the file system and + does not involve any running system services, unlike + <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + or + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + This allows <command>systemd-firstboot</command> to operate on + mounted but not booted disk images and in early boot. It is not + recommended to use <command>systemd-firstboot</command> on the + running system while it is up.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--root=<replaceable>root</replaceable></option></term> + <listitem><para>Takes a directory path as an argument. All + paths will be prefixed with the given alternate + <replaceable>root</replaceable> path, including config search + paths. This is useful to operate on a system image mounted to + the specified directory instead of the host system itself. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--locale=<replaceable>LOCALE</replaceable></option></term> + <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term> + + <listitem><para>Sets the system locale, more specifically the + <varname>LANG=</varname> and <varname>LC_MESSAGES</varname> + settings. The argument should be a valid locale identifier, + such as <literal>de_DE.UTF-8</literal>. This controls the + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + configuration file.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term> + + <listitem><para>Sets the system time zone. The argument should + be a valid time zone identifier, such as + <literal>Europe/Berlin</literal>. This controls the + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry> + symlink.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term> + + <listitem><para>Sets the system hostname. The argument should + be a host name, compatible with DNS. This controls the + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> + configuration file.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--machine-id=<replaceable>ID</replaceable></option></term> + + <listitem><para>Sets the system's machine ID. This controls + the + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + file.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term> + <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term> + + <listitem><para>Sets the password of the system's root user. + This creates a + <citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry> + file. This setting exists in two forms: + <option>--root-password=</option> accepts the password to set + directly on the command line, + <option>--root-password-file=</option> reads it from a file. + Note that it is not recommended specifying passwords on the + command line as other users might be able to see them simply + by invoking + <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--prompt-locale</option></term> + <term><option>--prompt-timezone</option></term> + <term><option>--prompt-hostname</option></term> + <term><option>--prompt-root-password</option></term> + + <listitem><para>Prompt the user interactively for a specific + basic setting. Note that any explicit configuration settings + specified on the command line take precedence, and the user is + not prompted for it.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--prompt</option></term> + + <listitem><para>Query the user for locale, timezone, hostname + and root password. This is equivalent to specifying + <option>--prompt-locale</option>, + <option>--prompt-timezone</option>, + <option>--prompt-hostname</option>, + <option>--prompt-root-password</option> in combination.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--copy-locale</option></term> + <term><option>--copy-timezone</option></term> + <term><option>--copy-root-password</option></term> + + <listitem><para>Copy a specific basic setting from the host. + This only works in combination with <option>--root=</option> + (see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--copy</option></term> + + <listitem><para>Copy locale, time zone and root password from + the host. This is equivalent to specifying + <option>--copy-locale</option>, + <option>--copy-timezone</option>, + <option>--copy-root-password</option> in combination.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--setup-machine-id</option></term> + + <listitem><para>Initialize the system's machine ID to a random + ID. This only works in combination with + <option>--root=</option>.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-fsck@.service.xml b/man/systemd-fsck@.service.xml index ee66f3712d..88e11e89d4 100644 --- a/man/systemd-fsck@.service.xml +++ b/man/systemd-fsck@.service.xml @@ -21,137 +21,121 @@ --> <refentry id="systemd-fsck@.service"> - <refentryinfo> - <title>systemd-fsck@.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-fsck@.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-fsck@.service</refname> - <refname>systemd-fsck-root.service</refname> - <refname>systemd-fsck</refname> - <refpurpose>File system checker logic</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-fsck@.service</filename></para> - <para><filename>systemd-fsck-root.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-fsck</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-fsck@.service</filename> and - <filename>systemd-fsck-root.service</filename> are - services responsible for file system checks. They are - instantiated for each device that is configured for - file system checking. - <filename>systemd-fsck-root.service</filename> is - responsible for file system checks on the root file - system, but in only if the root filesystem wasn't - checked in the initramfs. - <filename>systemd-fsck@.service</filename> is used for - all other file systems and for the root file system in - the initramfs.</para> - - <para>Those services are started at boot if - <option>passno</option> in - <filename>/etc/fstab</filename> for the file system is - set to a value greater than zero. The file system - check for root is performed before the other file - systems. Other file systems may be checked in - parallel, except when they are one the same rotating - disk.</para> - - <para><filename>systemd-fsck</filename> does not know - any details about specific filesystems, and simply - executes file system checkers specific to each - filesystem type (<filename>/sbin/fsck.*</filename>). - This helper will decide if the filesystem should - actually be checked based on the time since last - check, number of mounts, unclean unmount, etc.</para> - - <para><filename>systemd-fsck</filename> will forward - file system checking progress to the console. If a - file system check fails for a service without - <option>nofail</option>, emergency mode is activated, - by isolating to - <filename>emergency.target</filename>.</para> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-fsck</filename> understands - one kernel command line parameter:</para> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>fsck.mode=</varname></term> - - <listitem><para>One of - <literal>auto</literal>, - <literal>force</literal>, - <literal>skip</literal>. Controls the - mode of operation. The default is - <literal>auto</literal>, and ensures - that file system checks are done when - the file system checker deems them - necessary. <literal>force</literal> - unconditionally results in full file - system checks. <literal>skip</literal> - skips any file system - checks.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>fsck.repair=</varname></term> - - <listitem><para>One of - <literal>preen</literal>, - <literal>yes</literal>, - <literal>no</literal>. Controls the - mode of operation. The default is <literal> - preen</literal>, and will automatically repair - problems that can be safely fixed. <literal>yes - </literal> will answer yes to all questions by - fsck and <literal>no</literal> will answer no to - all questions. - </para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fsck.btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fsck.cramfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fsck.ext4</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fsck.fat</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fsck.hfsplus</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fsck.minix</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fsck.ntfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fsck.xfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-fsck@.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-fsck@.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-fsck@.service</refname> + <refname>systemd-fsck-root.service</refname> + <refname>systemd-fsck</refname> + <refpurpose>File system checker logic</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-fsck@.service</filename></para> + <para><filename>systemd-fsck-root.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-fsck</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-fsck@.service</filename> and + <filename>systemd-fsck-root.service</filename> are services + responsible for file system checks. They are instantiated for each + device that is configured for file system checking. + <filename>systemd-fsck-root.service</filename> is responsible for + file system checks on the root file system, but in only if the + root filesystem wasn't checked in the initramfs. + <filename>systemd-fsck@.service</filename> is used for all other + file systems and for the root file system in the initramfs.</para> + + <para>Those services are started at boot if + <option>passno</option> in <filename>/etc/fstab</filename> for the + file system is set to a value greater than zero. The file system + check for root is performed before the other file systems. Other + file systems may be checked in parallel, except when they are one + the same rotating disk.</para> + + <para><filename>systemd-fsck</filename> does not know any details + about specific filesystems, and simply executes file system + checkers specific to each filesystem type + (<filename>/sbin/fsck.*</filename>). This helper will decide if + the filesystem should actually be checked based on the time since + last check, number of mounts, unclean unmount, etc.</para> + + <para><filename>systemd-fsck</filename> will forward file system + checking progress to the console. If a file system check fails for + a service without <option>nofail</option>, emergency mode is + activated, by isolating to + <filename>emergency.target</filename>.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-fsck</filename> understands one kernel + command line parameter:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>fsck.mode=</varname></term> + + <listitem><para>One of <literal>auto</literal>, + <literal>force</literal>, <literal>skip</literal>. Controls + the mode of operation. The default is <literal>auto</literal>, + and ensures that file system checks are done when the file + system checker deems them necessary. <literal>force</literal> + unconditionally results in full file system checks. + <literal>skip</literal> skips any file system + checks.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>fsck.repair=</varname></term> + + <listitem><para>One of <literal>preen</literal>, + <literal>yes</literal>, <literal>no</literal>. Controls the + mode of operation. The default is <literal> preen</literal>, + and will automatically repair problems that can be safely + fixed. <literal>yes </literal> will answer yes to all + questions by fsck and <literal>no</literal> will answer no to + all questions. </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-quotacheck.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fsck.btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fsck.cramfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fsck.ext4</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fsck.fat</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fsck.hfsplus</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fsck.minix</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fsck.ntfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fsck.xfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-fstab-generator.xml b/man/systemd-fstab-generator.xml index 65b48eea07..8f82e33304 100644 --- a/man/systemd-fstab-generator.xml +++ b/man/systemd-fstab-generator.xml @@ -21,178 +21,165 @@ --> <refentry id="systemd-fstab-generator"> - <refentryinfo> - <title>systemd-fstab-generator</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-fstab-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-fstab-generator</refname> - <refpurpose>Unit generator for /etc/fstab</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-fstab-generator</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-fstab-generator</filename> is - a generator that translates - <filename>/etc/fstab</filename> (see - <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details) into native systemd units early at boot - and when configuration of the system manager is - reloaded. This will instantiate mount and swap units - as necessary.</para> - - <para>The <varname>passno</varname> field is treated - like a simple boolean, and the ordering information is - discarded. However, if the root file system is - checked, it is checked before all the other - file systems.</para> - - <para>See - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about special - <filename>/etc/fstab</filename> mount options this - generator understands.</para> - - <para><filename>systemd-fstab-generator</filename> - implements the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator - specification</ulink>.</para> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-fstab-generator</filename> understands - the following kernel command line parameters:</para> - - <variablelist class='kernel-commandline-options'> - - <varlistentry> - <term><varname>fstab=</varname></term> - <term><varname>rd.fstab=</varname></term> - - <listitem><para>Takes a boolean - argument. Defaults to - <literal>yes</literal>. If - <literal>no</literal>, causes the - generator to ignore any mounts or swaps - configured in - <filename>/etc/fstab</filename>. <varname>rd.fstab=</varname> - is honored only by initial RAM disk - (initrd) while - <varname>fstab=</varname> is - honored by both the main system and - the initrd.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>root=</varname></term> - - <listitem><para>Takes the root filesystem to mount - in the initrd. - <varname>root=</varname> is - honored by the initrd.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>rootfstype=</varname></term> - - <listitem><para>Takes the root filesystem type that - will be passed to the mount command. - <varname>rootfstype=</varname> is - honored by the initrd.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>rootflags=</varname></term> - - <listitem><para>Takes the root filesystem mount options - to use. <varname>rootflags=</varname> is - honored by the initrd.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>mount.usr=</varname></term> - - <listitem><para>Takes the <filename>/usr</filename> - filesystem to be mounted by the initrd. If - <varname>mount.usrfstype=</varname> or - <varname>mount.usrflags=</varname> is set, then - <varname>mount.usr=</varname> will default to the value set in - <varname>root=</varname>.</para> - - <para>Otherwise this parameter defaults to the - <filename>/usr</filename> entry - found in <filename>/etc/fstab</filename> on the root - filesystem.</para> - - <para><varname>mount.usr=</varname> is honored by the initrd. - </para></listitem> - </varlistentry> - <varlistentry> - <term><varname>mount.usrfstype=</varname></term> - - <listitem><para>Takes the <filename>/usr</filename> - filesystem type that will be passed to the mount - command. If <varname>mount.usr=</varname> or - <varname>mount.usrflags=</varname> is set, then - <varname>mount.usrfstype=</varname> will default to the value set in - <varname>rootfstype=</varname>.</para> - - <para>Otherwise this value will be read from the - <filename>/usr</filename> entry in - <filename>/etc/fstab</filename> on the root filesystem.</para> - - <para><varname>mount.usrfstype=</varname> is - honored by the initrd.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>mount.usrflags=</varname></term> - - <listitem><para>Takes the <filename>/usr</filename> - filesystem mount options to use. If - <varname>mount.usr=</varname> or - <varname>mount.usrfstype=</varname> is set, then - <varname>mount.usrflages=</varname> will default to the value set in - <varname>rootflags=</varname>.</para> - - <para>Otherwise this value will be read from the - <filename>/usr</filename> entry in - <filename>/etc/fstab</filename> on the root filesystem.</para> - - <para><varname>mount.usrflags=</varname> is - honored by the initrd.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-fstab-generator</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-fstab-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-fstab-generator</refname> + <refpurpose>Unit generator for /etc/fstab</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-fstab-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-fstab-generator</filename> is a generator + that translates <filename>/etc/fstab</filename> (see + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) into native systemd units early at boot and when + configuration of the system manager is reloaded. This will + instantiate mount and swap units as necessary.</para> + + <para>The <varname>passno</varname> field is treated like a simple + boolean, and the ordering information is discarded. However, if + the root file system is checked, it is checked before all the + other file systems.</para> + + <para>See + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information about special <filename>/etc/fstab</filename> + mount options this generator understands.</para> + + <para><filename>systemd-fstab-generator</filename> implements the + <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator + specification</ulink>.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-fstab-generator</filename> understands the + following kernel command line parameters:</para> + + <variablelist class='kernel-commandline-options'> + + <varlistentry> + <term><varname>fstab=</varname></term> + <term><varname>rd.fstab=</varname></term> + + <listitem><para>Takes a boolean argument. Defaults to + <literal>yes</literal>. If <literal>no</literal>, causes the + generator to ignore any mounts or swaps configured in + <filename>/etc/fstab</filename>. <varname>rd.fstab=</varname> + is honored only by initial RAM disk (initrd) while + <varname>fstab=</varname> is honored by both the main system + and the initrd.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>root=</varname></term> + + <listitem><para>Takes the root filesystem to mount in the + initrd. <varname>root=</varname> is honored by the + initrd.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>rootfstype=</varname></term> + + <listitem><para>Takes the root filesystem type that will be + passed to the mount command. <varname>rootfstype=</varname> is + honored by the initrd.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>rootflags=</varname></term> + + <listitem><para>Takes the root filesystem mount options to + use. <varname>rootflags=</varname> is honored by the + initrd.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>mount.usr=</varname></term> + + <listitem><para>Takes the <filename>/usr</filename> filesystem + to be mounted by the initrd. If + <varname>mount.usrfstype=</varname> or + <varname>mount.usrflags=</varname> is set, then + <varname>mount.usr=</varname> will default to the value set in + <varname>root=</varname>.</para> + + <para>Otherwise this parameter defaults to the + <filename>/usr</filename> entry found in + <filename>/etc/fstab</filename> on the root filesystem.</para> + + <para><varname>mount.usr=</varname> is honored by the initrd. + </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>mount.usrfstype=</varname></term> + + <listitem><para>Takes the <filename>/usr</filename> filesystem + type that will be passed to the mount command. If + <varname>mount.usr=</varname> or + <varname>mount.usrflags=</varname> is set, then + <varname>mount.usrfstype=</varname> will default to the value + set in <varname>rootfstype=</varname>.</para> + + <para>Otherwise this value will be read from the + <filename>/usr</filename> entry in + <filename>/etc/fstab</filename> on the root filesystem.</para> + + <para><varname>mount.usrfstype=</varname> is honored by the + initrd.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>mount.usrflags=</varname></term> + + <listitem><para>Takes the <filename>/usr</filename> filesystem + mount options to use. If <varname>mount.usr=</varname> or + <varname>mount.usrfstype=</varname> is set, then + <varname>mount.usrflages=</varname> will default to the value + set in <varname>rootflags=</varname>.</para> + + <para>Otherwise this value will be read from the + <filename>/usr</filename> entry in + <filename>/etc/fstab</filename> on the root filesystem.</para> + + <para><varname>mount.usrflags=</varname> is honored by the + initrd.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-getty-generator.xml b/man/systemd-getty-generator.xml index f6a66896df..0b5b2f2a71 100644 --- a/man/systemd-getty-generator.xml +++ b/man/systemd-getty-generator.xml @@ -21,81 +21,77 @@ --> <refentry id="systemd-getty-generator"> - <refentryinfo> - <title>systemd-getty-generator</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-getty-generator</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-getty-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-getty-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-getty-generator</refname> - <refpurpose>Generator for enabling getty instances on - the console</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-getty-generator</refname> + <refpurpose>Generator for enabling getty instances on the + console</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-getty-generator</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-getty-generator</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-getty-generator</filename> is - a generator that automatically instantiates - <filename>serial-getty@.service</filename> on the - kernel console <filename>/dev/console</filename> if - that is not directed to the virtual console - subsystem. It will also instantiate - <filename>serial-getty@.service</filename> instances - for virtualizer consoles, if execution in a - virtualized environment is detected. Finally, it will - instantiate - <filename>container-getty@.service</filename> - instances for additional container pseudo TTYs as - requested by the container manager (see <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface/"><filename>Container Interface</filename></ulink>). This - should ensure that the user is shown a login prompt at - the right place, regardless of which environment the - system is started in. For example, it is sufficient to - redirect the kernel console with a kernel command line - argument such as <varname>console=</varname> to get - both kernel messages and a getty prompt on a serial - TTY. See <ulink - url="https://www.kernel.org/doc/Documentation/kernel-parameters.txt"><filename>kernel-parameters.txt</filename></ulink> - for more information on the - <varname>console=</varname> kernel parameter.</para> + <para><filename>systemd-getty-generator</filename> is a generator + that automatically instantiates + <filename>serial-getty@.service</filename> on the kernel console + <filename>/dev/console</filename> if that is not directed to the + virtual console subsystem. It will also instantiate + <filename>serial-getty@.service</filename> instances for + virtualizer consoles, if execution in a virtualized environment is + detected. Finally, it will instantiate + <filename>container-getty@.service</filename> instances for + additional container pseudo TTYs as requested by the container + manager (see <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface/"><filename>Container + Interface</filename></ulink>). This should ensure that the user is + shown a login prompt at the right place, regardless of which + environment the system is started in. For example, it is + sufficient to redirect the kernel console with a kernel command + line argument such as <varname>console=</varname> to get both + kernel messages and a getty prompt on a serial TTY. See <ulink + url="https://www.kernel.org/doc/Documentation/kernel-parameters.txt"><filename>kernel-parameters.txt</filename></ulink> + for more information on the <varname>console=</varname> kernel + parameter.</para> - <para><filename>systemd-getty-generator</filename> - implements the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator - specification</ulink>.</para> + <para><filename>systemd-getty-generator</filename> implements the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator + specification</ulink>.</para> - <para>Further information about configuration of - gettys you may find in <ulink - url="http://0pointer.de/blog/projects/serial-console.html">systemd - for Administrators, Part XVI: Gettys on Serial - Consoles (and Elsewhere)</ulink>.</para> - </refsect1> + <para>Further information about configuration of gettys you may + find in + <ulink url="http://0pointer.de/blog/projects/serial-console.html">systemd + for Administrators, Part XVI: Gettys on Serial Consoles (and + Elsewhere)</ulink>.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>agetty</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>agetty</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-gpt-auto-generator.xml b/man/systemd-gpt-auto-generator.xml index 68fe2705fa..9c706df246 100644 --- a/man/systemd-gpt-auto-generator.xml +++ b/man/systemd-gpt-auto-generator.xml @@ -21,166 +21,160 @@ --> <refentry id="systemd-gpt-auto-generator"> - <refentryinfo> - <title>systemd-gpt-auto-generator</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-gpt-auto-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-gpt-auto-generator</refname> - <refpurpose>Generator for automatically discovering - and mounting root, <filename>/home</filename> and - <filename>/srv</filename> partitions, as well as - discovering and enabling swap partitions, based on GPT - partition type GUIDs.</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-gpt-auto-generator</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-gpt-auto-generator</filename> - is a unit generator that automatically discovers root, - <filename>/home</filename>, <filename>/srv</filename> - and swap partitions and creates mount and swap units - for them, based on the partition type GUIDs of - GUID partition tables (GPT). It implements the <ulink - url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable - Partitions Specification</ulink>. Note that this - generator has no effect on non-GPT systems, on systems - where the units are explicitly configured (for - example, listed in - <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>), - or where the mount points are non-empty.</para> - - <para>This generator will only look for root - partitions on the same physical disk the EFI System - Partition (ESP) is located on. It will only look for - the other partitions on the same physical disk the - root file system is located on. These partitions will - not be searched on systems where the root file system is - distributed on multiple disks, for example via btrfs - RAID.</para> - - <para><filename>systemd-gpt-auto-generator</filename> - is useful for centralizing file system configuration - in the partition table and making manual configuration - in <filename>/etc/fstab</filename> or suchlike - unnecessary.</para> - - <para>This generator looks for the partitions based on - their partition type GUID. The following partition - type GUIDs are identified:</para> - - <table> - <title>Partition Type GUIDs</title> - <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <colspec colname="guid" /> - <colspec colname="name" /> - <colspec colname="explanation" /> - <thead> - <row> - <entry>Partition Type GUID</entry> - <entry>Name</entry> - <entry>Explanation</entry> - </row> - </thead> - <tbody> - <row> - <entry>44479540-f297-41b2-9af7-d131d5f0458a</entry> - <entry><filename>Root Partition (x86)</filename></entry> - <entry>On 32-bit x86 systems, the first x86 root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry> - </row> - <row> - <entry>4f68bce3-e8cd-4db1-96e7-fbcaf984b709</entry> - <entry><filename>Root Partition (x86-64)</filename></entry> - <entry>On 64-bit x86 systems, the first x86-64 root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry> - </row> - <row> - <entry>69dad710-2ce4-4e3c-b16c-21a1d49abed3</entry> - <entry><filename>Root Partition (32-bit ARM)</filename></entry> - <entry>On 32-bit ARM systems, the first ARM root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry> - </row> - <row> - <entry>b921b045-1df0-41c3-af44-4c6f280d3fae</entry> - <entry><filename>Root Partition (64-bit ARM)</filename></entry> - <entry>On 64-bit ARM systems, the first ARM root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry> - </row> - <row> - <entry>933ac7e1-2eb4-4f13-b844-0e14e2aef915</entry> - <entry>Home Partition</entry> - <entry>The first home partition on the disk the root partition is located on is mounted to <filename>/home</filename>.</entry> - </row> - <row> - <entry>3b8f8425-20e0-4f3b-907f-1a25a76f98e8</entry> - <entry>Server Data Partition</entry> - <entry>The first server data partition on the disk the root partition is located on is mounted to <filename>/srv</filename>.</entry> - </row> - <row> - <entry>0657fd6d-a4ab-43c4-84e5-0933c84b4f4f</entry> - <entry>Swap</entry> - <entry>All swap partitions located on the disk the root partition is located on are enabled.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>The <filename>/home</filename> and - <filename>/srv</filename> partitions may be encrypted - in LUKS format. In this case a device mapper device is - set up under the names - <filename>/dev/mapper/home</filename> and - <filename>/dev/mapper/srv</filename>. Note that this - might create conflicts if the same partition is listed - in <filename>/etc/crypttab</filename> with a different - device mapper device name.</para> - - <para>Also note that - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - will mount the EFI System Partition (ESP) to - <filename>/boot</filename> if not otherwise mounted.</para> - - <para>When using this generator in conjunction with - btrfs file systems, make sure to set the correct - default subvolumes on them, using <command>btrfs - subvolume set-default</command>.</para> - - <para><filename>systemd-gpt-auto-generator</filename> - implements the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/Generators">Generator - Specification</ulink>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-gpt-auto-generator</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-gpt-auto-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-gpt-auto-generator</refname> + <refpurpose>Generator for automatically discovering + and mounting root, <filename>/home</filename> and + <filename>/srv</filename> partitions, as well as + discovering and enabling swap partitions, based on GPT + partition type GUIDs.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-gpt-auto-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-gpt-auto-generator</filename> is a unit + generator that automatically discovers root, + <filename>/home</filename>, <filename>/srv</filename> and swap + partitions and creates mount and swap units for them, based on the + partition type GUIDs of GUID partition tables (GPT). It implements + the + <ulink url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable + Partitions Specification</ulink>. Note that this generator has no + effect on non-GPT systems, on systems where the units are + explicitly configured (for example, listed in + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>), + or where the mount points are non-empty.</para> + + <para>This generator will only look for root partitions on the + same physical disk the EFI System Partition (ESP) is located on. + It will only look for the other partitions on the same physical + disk the root file system is located on. These partitions will not + be searched on systems where the root file system is distributed + on multiple disks, for example via btrfs RAID.</para> + + <para><filename>systemd-gpt-auto-generator</filename> is useful + for centralizing file system configuration in the partition table + and making manual configuration in <filename>/etc/fstab</filename> + or suchlike unnecessary.</para> + + <para>This generator looks for the partitions based on their + partition type GUID. The following partition type GUIDs are + identified:</para> + + <table> + <title>Partition Type GUIDs</title> + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname="guid" /> + <colspec colname="name" /> + <colspec colname="explanation" /> + <thead> + <row> + <entry>Partition Type GUID</entry> + <entry>Name</entry> + <entry>Explanation</entry> + </row> + </thead> + <tbody> + <row> + <entry>44479540-f297-41b2-9af7-d131d5f0458a</entry> + <entry><filename>Root Partition (x86)</filename></entry> + <entry>On 32-bit x86 systems, the first x86 root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry> + </row> + <row> + <entry>4f68bce3-e8cd-4db1-96e7-fbcaf984b709</entry> + <entry><filename>Root Partition (x86-64)</filename></entry> + <entry>On 64-bit x86 systems, the first x86-64 root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry> + </row> + <row> + <entry>69dad710-2ce4-4e3c-b16c-21a1d49abed3</entry> + <entry><filename>Root Partition (32-bit ARM)</filename></entry> + <entry>On 32-bit ARM systems, the first ARM root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry> + </row> + <row> + <entry>b921b045-1df0-41c3-af44-4c6f280d3fae</entry> + <entry><filename>Root Partition (64-bit ARM)</filename></entry> + <entry>On 64-bit ARM systems, the first ARM root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry> + </row> + <row> + <entry>933ac7e1-2eb4-4f13-b844-0e14e2aef915</entry> + <entry>Home Partition</entry> + <entry>The first home partition on the disk the root partition is located on is mounted to <filename>/home</filename>.</entry> + </row> + <row> + <entry>3b8f8425-20e0-4f3b-907f-1a25a76f98e8</entry> + <entry>Server Data Partition</entry> + <entry>The first server data partition on the disk the root partition is located on is mounted to <filename>/srv</filename>.</entry> + </row> + <row> + <entry>0657fd6d-a4ab-43c4-84e5-0933c84b4f4f</entry> + <entry>Swap</entry> + <entry>All swap partitions located on the disk the root partition is located on are enabled.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>The <filename>/home</filename> and <filename>/srv</filename> + partitions may be encrypted in LUKS format. In this case a device + mapper device is set up under the names + <filename>/dev/mapper/home</filename> and + <filename>/dev/mapper/srv</filename>. Note that this might create + conflicts if the same partition is listed in + <filename>/etc/crypttab</filename> with a different device mapper + device name.</para> + + <para>Also note that + <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + will mount the EFI System Partition (ESP) to + <filename>/boot</filename> if not otherwise mounted.</para> + + <para>When using this generator in conjunction with btrfs file + systems, make sure to set the correct default subvolumes on them, + using <command>btrfs subvolume set-default</command>.</para> + + <para><filename>systemd-gpt-auto-generator</filename> implements + the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/Generators">Generator + Specification</ulink>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-halt.service.xml b/man/systemd-halt.service.xml index 552dbdf687..c94e2a1820 100644 --- a/man/systemd-halt.service.xml +++ b/man/systemd-halt.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,103 +23,96 @@ <refentry id="systemd-halt.service"> - <refentryinfo> - <title>systemd-halt.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-halt.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-halt.service</refname> - <refname>systemd-poweroff.service</refname> - <refname>systemd-reboot.service</refname> - <refname>systemd-kexec.service</refname> - <refname>systemd-shutdown</refname> - <refpurpose>System shutdown logic</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-halt.service</filename></para> - <para><filename>systemd-poweroff.service</filename></para> - <para><filename>systemd-reboot.service</filename></para> - <para><filename>systemd-kexec.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-shutdown</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-halt.service</filename> is a - system service that is pulled in by - <filename>halt.target</filename> and is responsible - for the actual system halt. Similarly, - <filename>systemd-poweroff.service</filename> is - pulled in by <filename>poweroff.target</filename>, - <filename>systemd-reboot.service</filename> by - <filename>reboot.target</filename> and - <filename>systemd-kexec.service</filename> by - <filename>kexec.target</filename> to execute the - respective actions.</para> - - <para>When these services are run, they ensure that PID - 1 is replaced by the - <filename>/usr/lib/systemd/systemd-shutdown</filename> - tool which is then responsible for the actual - shutdown. Before shutting down, this binary will try to - unmount all remaining file systems, disable all - remaining swap devices, detach all remaining storage - devices and kill all remaining processes.</para> - - <para>It is necessary to have this code in a separate binary - because otherwise rebooting after an upgrade might be broken — - the running PID 1 could still depend on libraries which are not - available any more, thus keeping the file system busy, which - then cannot be re-mounted read-only.</para> - - <para>Immediately before executing the actual system - halt/poweroff/reboot/kexec - <filename>systemd-shutdown</filename> will run all - executables in - <filename>/usr/lib/systemd/system-shutdown/</filename> - and pass one arguments to them: either - <literal>halt</literal>, - <literal>poweroff</literal>, - <literal>reboot</literal> or - <literal>kexec</literal>, depending on the chosen - action. All executables in this directory are executed - in parallel, and execution of the action is not - continued before all executables finished.</para> - - <para>Note that - <filename>systemd-halt.service</filename> (and the - related units) should never be executed - directly. Instead, trigger system shutdown with a - command such as <literal>systemctl halt</literal> or - suchlike.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-halt.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-halt.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-halt.service</refname> + <refname>systemd-poweroff.service</refname> + <refname>systemd-reboot.service</refname> + <refname>systemd-kexec.service</refname> + <refname>systemd-shutdown</refname> + <refpurpose>System shutdown logic</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-halt.service</filename></para> + <para><filename>systemd-poweroff.service</filename></para> + <para><filename>systemd-reboot.service</filename></para> + <para><filename>systemd-kexec.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-shutdown</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-halt.service</filename> is a system + service that is pulled in by <filename>halt.target</filename> and + is responsible for the actual system halt. Similarly, + <filename>systemd-poweroff.service</filename> is pulled in by + <filename>poweroff.target</filename>, + <filename>systemd-reboot.service</filename> by + <filename>reboot.target</filename> and + <filename>systemd-kexec.service</filename> by + <filename>kexec.target</filename> to execute the respective + actions.</para> + + <para>When these services are run, they ensure that PID 1 is + replaced by the + <filename>/usr/lib/systemd/systemd-shutdown</filename> tool which + is then responsible for the actual shutdown. Before shutting down, + this binary will try to unmount all remaining file systems, + disable all remaining swap devices, detach all remaining storage + devices and kill all remaining processes.</para> + + <para>It is necessary to have this code in a separate binary + because otherwise rebooting after an upgrade might be broken — the + running PID 1 could still depend on libraries which are not + available any more, thus keeping the file system busy, which then + cannot be re-mounted read-only.</para> + + <para>Immediately before executing the actual system + halt/poweroff/reboot/kexec <filename>systemd-shutdown</filename> + will run all executables in + <filename>/usr/lib/systemd/system-shutdown/</filename> and pass + one arguments to them: either <literal>halt</literal>, + <literal>poweroff</literal>, <literal>reboot</literal> or + <literal>kexec</literal>, depending on the chosen action. All + executables in this directory are executed in parallel, and + execution of the action is not continued before all executables + finished.</para> + + <para>Note that <filename>systemd-halt.service</filename> (and the + related units) should never be executed directly. Instead, trigger + system shutdown with a command such as <literal>systemctl + halt</literal> or suchlike.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-hibernate-resume-generator.xml b/man/systemd-hibernate-resume-generator.xml index e010c23df4..a21782cbf9 100644 --- a/man/systemd-hibernate-resume-generator.xml +++ b/man/systemd-hibernate-resume-generator.xml @@ -21,73 +21,73 @@ --> <refentry id="systemd-hibernate-resume-generator"> - <refentryinfo> - <title>systemd-hibernate-resume-generator</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Ivan</firstname> - <surname>Shapovalov</surname> - <email>intelfx100@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-hibernate-resume-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-hibernate-resume-generator</refname> - <refpurpose>Unit generator for resume= kernel parameter</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-hibernate-resume-generator</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-hibernate-resume-generator</filename> is - a generator that instantiates - <citerefentry><refentrytitle>systemd-hibernate-resume@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - unit according to the value of <option>resume=</option> - parameter specified on the kernel command line.</para> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-hibernate-resume-generator</filename> understands - the following kernel command line parameters:</para> - - <variablelist class='kernel-commandline-options'> - - <varlistentry> - <term><varname>resume=</varname></term> - - <listitem><para>Takes a path to the resume - device. Both persistent block device paths like - <filename>/dev/disk/by-foo/bar</filename> and - <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>-style - specifiers like <literal>FOO=bar</literal> - are supported.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hibernate-resume@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-hibernate-resume-generator</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Ivan</firstname> + <surname>Shapovalov</surname> + <email>intelfx100@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-hibernate-resume-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-hibernate-resume-generator</refname> + <refpurpose>Unit generator for resume= kernel parameter</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-hibernate-resume-generator</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-hibernate-resume-generator</filename> is a + generator that instantiates + <citerefentry><refentrytitle>systemd-hibernate-resume@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + unit according to the value of <option>resume=</option> parameter + specified on the kernel command line.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-hibernate-resume-generator</filename> + understands the following kernel command line parameters:</para> + + <variablelist class='kernel-commandline-options'> + + <varlistentry> + <term><varname>resume=</varname></term> + + <listitem><para>Takes a path to the resume device. Both + persistent block device paths like + <filename>/dev/disk/by-foo/bar</filename> and + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>-style + specifiers like <literal>FOO=bar</literal> are + supported.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hibernate-resume@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-hibernate-resume@.service.xml b/man/systemd-hibernate-resume@.service.xml index 30bfd88101..7d00827447 100644 --- a/man/systemd-hibernate-resume@.service.xml +++ b/man/systemd-hibernate-resume@.service.xml @@ -21,62 +21,61 @@ --> <refentry id="systemd-hibernate-resume@.service"> - <refentryinfo> - <title>systemd-hibernate-resume@.service</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-hibernate-resume@.service</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Ivan</firstname> - <surname>Shapovalov</surname> - <email>intelfx100@gmail.com</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Ivan</firstname> + <surname>Shapovalov</surname> + <email>intelfx100@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-hibernate-resume@.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-hibernate-resume@.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-hibernate-resume@.service</refname> - <refname>systemd-hibernate-resume</refname> - <refpurpose>Resume from hibernation</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-hibernate-resume@.service</refname> + <refname>systemd-hibernate-resume</refname> + <refpurpose>Resume from hibernation</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>systemd-hibernate-resume@.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-hibernate-resume</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>systemd-hibernate-resume@.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-hibernate-resume</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-hibernate-resume@.service</filename> - initiates the resume from hibernation. It is - instantiated with the device to resume from as the - template argument.</para> + <para><filename>systemd-hibernate-resume@.service</filename> + initiates the resume from hibernation. It is instantiated with the + device to resume from as the template argument.</para> - <para><filename>systemd-hibernate-resume</filename> only supports - the in-kernel hibernation implementation, known as - <ulink url="https://www.kernel.org/doc/Documentation/power/swsusp.txt">swsusp</ulink>. - Internally, it works by writing the major:minor of specified - device node to <filename>/sys/power/resume</filename>.</para> + <para><filename>systemd-hibernate-resume</filename> only supports + the in-kernel hibernation implementation, known as + <ulink url="https://www.kernel.org/doc/Documentation/power/swsusp.txt">swsusp</ulink>. + Internally, it works by writing the major:minor of specified + device node to <filename>/sys/power/resume</filename>.</para> - <para>Failing to initiate a resume is not an error condition. - It may mean that there was no resume image (e. g. if the - system has been simply powered off and not hibernated). In - such case, the boot is ordinarily continued.</para> - </refsect1> + <para>Failing to initiate a resume is not an error condition. It + may mean that there was no resume image (e. g. if the system has + been simply powered off and not hibernated). In such case, the + boot is ordinarily continued.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-hibernate-resume-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-hostnamed.service.xml b/man/systemd-hostnamed.service.xml index 7952d8a6cb..6990d41b02 100644 --- a/man/systemd-hostnamed.service.xml +++ b/man/systemd-hostnamed.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,65 +23,63 @@ <refentry id="systemd-hostnamed.service" conditional='ENABLE_HOSTNAMED'> - <refentryinfo> - <title>systemd-hostnamed.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-hostnamed.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-hostnamed.service</refname> - <refname>systemd-hostnamed</refname> - <refpurpose>Host name bus mechanism</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-hostnamed.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-hostnamed</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-hostnamed</filename> is a system - service that may be used as a mechanism to change the - system's hostname. <filename>systemd-hostnamed</filename> is - automatically activated on request and terminates - itself when it is unused.</para> - - <para>The tool - <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - is a command line client to this service.</para> - - <para>See the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/hostnamed"> - developer documentation</ulink> for information about - the APIs <filename>systemd-hostnamed</filename> - provides.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-hostnamed.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-hostnamed.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-hostnamed.service</refname> + <refname>systemd-hostnamed</refname> + <refpurpose>Host name bus mechanism</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-hostnamed.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-hostnamed</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-hostnamed</filename> is a system service + that may be used as a mechanism to change the system's hostname. + <filename>systemd-hostnamed</filename> is automatically activated + on request and terminates itself when it is unused.</para> + + <para>The tool + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + is a command line client to this service.</para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/hostnamed"> + developer documentation</ulink> for information about the APIs + <filename>systemd-hostnamed</filename> provides.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-inhibit.xml b/man/systemd-inhibit.xml index c694744fb9..9d85908f97 100644 --- a/man/systemd-inhibit.xml +++ b/man/systemd-inhibit.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,173 +22,156 @@ --> <refentry id="systemd-inhibit" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-inhibit</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-inhibit</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-inhibit</refname> - <refpurpose>Execute a program with an inhibition lock taken</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> --list</command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-inhibit</command> may be used - to execute a program with a shutdown, sleep or idle - inhibitor lock taken. The lock will be acquired before - the specified command line is executed and released - afterwards.</para> - - <para>Inhibitor locks may be used to block or delay - system sleep and shutdown requests from the user, as well - as automatic idle handling of the OS. This is useful - to avoid system suspends while an optical disc is - being recorded, or similar operations that should not - be interrupted.</para> - - <para>For more information see the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor - Lock Developer Documentation</ulink>.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--what=</option></term> - - <listitem><para>Takes a colon-separated - list of one or more - operations to inhibit: - <literal>shutdown</literal>, - <literal>sleep</literal>, - <literal>idle</literal>, - <literal>handle-power-key</literal>, - <literal>handle-suspend-key</literal>, - <literal>handle-hibernate-key</literal>, - <literal>handle-lid-switch</literal>, - for inhibiting - reboot/power-off/halt/kexec, - suspending/hibernating, the automatic - idle detection, or the low-level - handling of the power/sleep key and - the lid switch, respectively. If omitted, - defaults to - <literal>idle:sleep:shutdown</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--who=</option></term> - - <listitem><para>Takes a short, - human-readable descriptive string for the - program taking the lock. If not passed, - defaults to the command line - string.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--why=</option></term> - - <listitem><para>Takes a short, - human-readable descriptive string for the - reason for taking the lock. Defaults - to "Unknown reason".</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--mode=</option></term> - - <listitem><para>Takes either - <literal>block</literal> or - <literal>delay</literal> and describes - how the lock is applied. If - <literal>block</literal> is used (the - default), the lock prohibits any of - the requested operations without time - limit, and only privileged users may - override it. If - <literal>delay</literal> is used, the - lock can only delay the requested - operations for a limited time. If the - time elapses, the lock is ignored and - the operation executed. The time limit - may be specified in - <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note - that <literal>delay</literal> is only - available for <literal>sleep</literal> - and - <literal>shutdown</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--list</option></term> - - <listitem><para>Lists all active - inhibition locks instead of acquiring - one.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>Returns the exit status of the executed program.</para> - </refsect1> - - <refsect1> - <title>Example</title> - - <programlisting># systemd-inhibit wodim foobar.iso</programlisting> - - <para>This burns the ISO image - <filename>foobar.iso</filename> on a CD using - <citerefentry project='man-pages'><refentrytitle>wodim</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - and inhibits system sleeping, shutdown and idle while - doing so.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-inhibit</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-inhibit</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-inhibit</refname> + <refpurpose>Execute a program with an inhibition lock taken</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> --list</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-inhibit</command> may be used to execute a + program with a shutdown, sleep or idle inhibitor lock taken. The + lock will be acquired before the specified command line is + executed and released afterwards.</para> + + <para>Inhibitor locks may be used to block or delay system sleep + and shutdown requests from the user, as well as automatic idle + handling of the OS. This is useful to avoid system suspends while + an optical disc is being recorded, or similar operations that + should not be interrupted.</para> + + <para>For more information see the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor + Lock Developer Documentation</ulink>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--what=</option></term> + + <listitem><para>Takes a colon-separated list of one or more + operations to inhibit: + <literal>shutdown</literal>, + <literal>sleep</literal>, + <literal>idle</literal>, + <literal>handle-power-key</literal>, + <literal>handle-suspend-key</literal>, + <literal>handle-hibernate-key</literal>, + <literal>handle-lid-switch</literal>, + for inhibiting reboot/power-off/halt/kexec, + suspending/hibernating, the automatic idle detection, or the + low-level handling of the power/sleep key and the lid switch, + respectively. If omitted, defaults to + <literal>idle:sleep:shutdown</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--who=</option></term> + + <listitem><para>Takes a short, human-readable descriptive + string for the program taking the lock. If not passed, + defaults to the command line string.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--why=</option></term> + + <listitem><para>Takes a short, human-readable descriptive + string for the reason for taking the lock. Defaults to + "Unknown reason".</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--mode=</option></term> + + <listitem><para>Takes either <literal>block</literal> or + <literal>delay</literal> and describes how the lock is + applied. If <literal>block</literal> is used (the default), + the lock prohibits any of the requested operations without + time limit, and only privileged users may override it. If + <literal>delay</literal> is used, the lock can only delay the + requested operations for a limited time. If the time elapses, + the lock is ignored and the operation executed. The time limit + may be specified in + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Note that <literal>delay</literal> is only available for + <literal>sleep</literal> and + <literal>shutdown</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--list</option></term> + + <listitem><para>Lists all active inhibition locks instead of + acquiring one.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>Returns the exit status of the executed program.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting># systemd-inhibit wodim foobar.iso</programlisting> + + <para>This burns the ISO image + <filename>foobar.iso</filename> on a CD using + <citerefentry project='man-pages'><refentrytitle>wodim</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + and inhibits system sleeping, shutdown and idle while + doing so.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-initctl.service.xml b/man/systemd-initctl.service.xml index eda6459b50..5c7f9a4a16 100644 --- a/man/systemd-initctl.service.xml +++ b/man/systemd-initctl.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,54 +23,54 @@ <refentry id="systemd-initctl.service"> - <refentryinfo> - <title>systemd-initctl.service</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-initctl.service</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-initctl.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-initctl.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-initctl.service</refname> - <refname>systemd-initctl.socket</refname> - <refname>systemd-initctl</refname> - <refpurpose>/dev/initctl compatibility</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-initctl.service</refname> + <refname>systemd-initctl.socket</refname> + <refname>systemd-initctl</refname> + <refpurpose>/dev/initctl compatibility</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>systemd-initctl.service</filename></para> - <para><filename>systemd-initctl.socket</filename></para> - <para><filename>/usr/lib/systemd/systemd-initctl</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>systemd-initctl.service</filename></para> + <para><filename>systemd-initctl.socket</filename></para> + <para><filename>/usr/lib/systemd/systemd-initctl</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-initctl</filename> is a system - service that implements compatibility with the - <filename>/dev/initctl</filename> FIFO file system - object, as implemented by the SysV init system. <filename>systemd-initctl</filename> is - automatically activated on request and terminates - itself when it is unused.</para> - </refsect1> + <para><filename>systemd-initctl</filename> is a system service + that implements compatibility with the + <filename>/dev/initctl</filename> FIFO file system object, as + implemented by the SysV init system. + <filename>systemd-initctl</filename> is automatically activated on + request and terminates itself when it is unused.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-journald.service.xml b/man/systemd-journald.service.xml index fa6e97edf0..6b250b65e6 100644 --- a/man/systemd-journald.service.xml +++ b/man/systemd-journald.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,253 +23,228 @@ <refentry id="systemd-journald.service"> - <refentryinfo> - <title>systemd-journald.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-journald.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-journald.service</refname> - <refname>systemd-journald.socket</refname> - <refname>systemd-journald-dev-log.socket</refname> - <refname>systemd-journald</refname> - <refpurpose>Journal service</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-journald.service</filename></para> - <para><filename>systemd-journald.socket</filename></para> - <para><filename>systemd-journald-dev-log.socket</filename></para> - <para><filename>/usr/lib/systemd/systemd-journald</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-journald</filename> is a - system service that collects and stores logging data. - It creates and maintains structured, indexed journals - based on logging information that is received from a - variety of sources:</para> - - <itemizedlist> - <listitem><para>Kernel log messages, via kmsg</para></listitem> - - <listitem><para>Simple system log messages, via the - libc <citerefentry - project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call</para></listitem> - - <listitem><para>Structured system log messages via the - native Journal API, see - <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry></para></listitem> - - <listitem><para>Standard output and - standard error of system - services</para></listitem> - - <listitem><para>Audit records, via the audit subsystem</para></listitem> - </itemizedlist> - - <para>The daemon will implicitly collect numerous - metadata fields for each log messages in a secure and - unfakeable way. See - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for more information about the collected metadata. - </para> - - <para>Log data collected by the journal is primarily - text-based but can also include binary data where - necessary. All objects stored in the journal can be up - to 2^64-1 bytes in size.</para> - - <para>By default, the journal stores log data in - <filename>/run/log/journal/</filename>. Since - <filename>/run/</filename> is volatile, log data is - lost at reboot. To make the data persistent, it - is sufficient to create - <filename>/var/log/journal/</filename> where - <filename>systemd-journald</filename> will then store - the data.</para> - - <para><filename>systemd-journald</filename> will - forward all received log messages to the <constant>AF_UNIX</constant>/<constant>SOCK_DGRAM</constant> socket - <filename>/run/systemd/journal/syslog</filename>, if it exists, which - may be used by Unix syslog daemons to process the data - further.</para> - - <para>See - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about the configuration of this - service.</para> - </refsect1> - - <refsect1> - <title>Signals</title> - - <variablelist> - <varlistentry> - <term>SIGUSR1</term> - - <listitem><para>Request that journal - data from <filename>/run/</filename> - is flushed to - <filename>/var/</filename> in order to - make it persistent (if this is - enabled). This must be used after - <filename>/var/</filename> is mounted, - as otherwise log data from - <filename>/run</filename> is never - flushed to <filename>/var</filename> - regardless of the - configuration.</para></listitem> - </varlistentry> - - <varlistentry> - <term>SIGUSR2</term> - - <listitem><para>Request immediate - rotation of the journal - files.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para>A few configuration parameters from - <filename>journald.conf</filename> may be overridden on - the kernel command line:</para> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>systemd.journald.forward_to_syslog=</varname></term> - <term><varname>systemd.journald.forward_to_kmsg=</varname></term> - <term><varname>systemd.journald.forward_to_console=</varname></term> - <term><varname>systemd.journald.forward_to_wall=</varname></term> - - <listitem><para>Enables/disables - forwarding of collected log messages - to syslog, the kernel log buffer, the - system console or wall. - </para> - - <para>See - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about these settings.</para> - </listitem> - - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Access Control</title> - - <para>Journal files are, by default, owned and readable - by the <literal>systemd-journal</literal> system group - but are not writable. Adding a user to this group thus - enables her/him to read the journal files.</para> - - <para>By default, each logged in user will get her/his - own set of journal files in - <filename>/var/log/journal/</filename>. These files - will not be owned by the user, however, in order to - avoid that the user can write to them - directly. Instead, file system ACLs are used to ensure - the user gets read access only.</para> - - <para>Additional users and groups may be granted - access to journal files via file system access control - lists (ACL). Distributions and administrators may - choose to grant read access to all members of the - <literal>wheel</literal> and <literal>adm</literal> - system groups with a command such as the - following:</para> - - <programlisting># setfacl -Rnm g:wheel:rx,d:g:wheel:rx,g:adm:rx,d:g:adm:rx /var/log/journal/</programlisting> - - <para>Note that this command will update the ACLs both - for existing journal files and for future journal - files created in the - <filename>/var/log/journal/</filename> - directory.</para> - </refsect1> - - <refsect1> - <title>Files</title> - - <variablelist> - <varlistentry> - <term><filename>/etc/systemd/journald.conf</filename></term> - - <listitem><para>Configure - <command>systemd-journald</command> - behaviour. See - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/run/log/journal/<replaceable>machine-id</replaceable>/*.journal</filename></term> - <term><filename>/run/log/journal/<replaceable>machine-id</replaceable>/*.journal~</filename></term> - <term><filename>/var/log/journal/<replaceable>machine-id</replaceable>/*.journal</filename></term> - <term><filename>/var/log/journal/<replaceable>machine-id</replaceable>/*.journal~</filename></term> - - <listitem><para><command>systemd-journald</command> - writes entries to files in - <filename>/run/log/journal/<replaceable>machine-id</replaceable>/</filename> - or - <filename>/var/log/journal/<replaceable>machine-id</replaceable>/</filename> - with the <literal>.journal</literal> - suffix. If the daemon is stopped - uncleanly, or if the files are found - to be corrupted, they are renamed - using the <literal>.journal~</literal> - suffix, and - <command>systemd-journald</command> - starts writing to a new - file. <filename>/run</filename> is - used when - <filename>/var/log/journal</filename> - is not available, or when - <option>Storage=volatile</option> is - set in the - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - configuration file. - </para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry>, - <command>pydoc systemd.journal</command>. - </para> - </refsect1> + <refentryinfo> + <title>systemd-journald.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-journald.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-journald.service</refname> + <refname>systemd-journald.socket</refname> + <refname>systemd-journald-dev-log.socket</refname> + <refname>systemd-journald</refname> + <refpurpose>Journal service</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-journald.service</filename></para> + <para><filename>systemd-journald.socket</filename></para> + <para><filename>systemd-journald-dev-log.socket</filename></para> + <para><filename>/usr/lib/systemd/systemd-journald</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-journald</filename> is a system service + that collects and stores logging data. It creates and maintains + structured, indexed journals based on logging information that is + received from a variety of sources:</para> + + <itemizedlist> + <listitem><para>Kernel log messages, via kmsg</para></listitem> + + <listitem><para>Simple system log messages, via the libc + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call</para></listitem> + + <listitem><para>Structured system log messages via the native + Journal API, see + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry></para></listitem> + + <listitem><para>Standard output and standard error of system + services</para></listitem> + + <listitem><para>Audit records, via the audit + subsystem</para></listitem> + </itemizedlist> + + <para>The daemon will implicitly collect numerous metadata fields + for each log messages in a secure and unfakeable way. See + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for more information about the collected metadata. + </para> + + <para>Log data collected by the journal is primarily text-based + but can also include binary data where necessary. All objects + stored in the journal can be up to 2^64-1 bytes in size.</para> + + <para>By default, the journal stores log data in + <filename>/run/log/journal/</filename>. Since + <filename>/run/</filename> is volatile, log data is lost at + reboot. To make the data persistent, it is sufficient to create + <filename>/var/log/journal/</filename> where + <filename>systemd-journald</filename> will then store the + data.</para> + + <para><filename>systemd-journald</filename> will forward all + received log messages to the + <constant>AF_UNIX</constant>/<constant>SOCK_DGRAM</constant> + socket <filename>/run/systemd/journal/syslog</filename>, if it + exists, which may be used by Unix syslog daemons to process the + data further.</para> + + <para>See + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the configuration of this service.</para> + </refsect1> + + <refsect1> + <title>Signals</title> + + <variablelist> + <varlistentry> + <term>SIGUSR1</term> + + <listitem><para>Request that journal data from + <filename>/run/</filename> is flushed to + <filename>/var/</filename> in order to make it persistent (if + this is enabled). This must be used after + <filename>/var/</filename> is mounted, as otherwise log data + from <filename>/run</filename> is never flushed to + <filename>/var</filename> regardless of the + configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGUSR2</term> + + <listitem><para>Request immediate rotation of the journal + files.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para>A few configuration parameters from + <filename>journald.conf</filename> may be overridden on the kernel + command line:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>systemd.journald.forward_to_syslog=</varname></term> + <term><varname>systemd.journald.forward_to_kmsg=</varname></term> + <term><varname>systemd.journald.forward_to_console=</varname></term> + <term><varname>systemd.journald.forward_to_wall=</varname></term> + + <listitem><para>Enables/disables forwarding of collected log + messages to syslog, the kernel log buffer, the system console + or wall. + </para> + + <para>See + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about these settings.</para> + </listitem> + + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Access Control</title> + + <para>Journal files are, by default, owned and readable by the + <literal>systemd-journal</literal> system group but are not + writable. Adding a user to this group thus enables her/him to read + the journal files.</para> + + <para>By default, each logged in user will get her/his own set of + journal files in <filename>/var/log/journal/</filename>. These + files will not be owned by the user, however, in order to avoid + that the user can write to them directly. Instead, file system + ACLs are used to ensure the user gets read access only.</para> + + <para>Additional users and groups may be granted access to journal + files via file system access control lists (ACL). Distributions + and administrators may choose to grant read access to all members + of the <literal>wheel</literal> and <literal>adm</literal> system + groups with a command such as the following:</para> + + <programlisting># setfacl -Rnm g:wheel:rx,d:g:wheel:rx,g:adm:rx,d:g:adm:rx /var/log/journal/</programlisting> + + <para>Note that this command will update the ACLs both for + existing journal files and for future journal files created in the + <filename>/var/log/journal/</filename> directory.</para> + </refsect1> + + <refsect1> + <title>Files</title> + + <variablelist> + <varlistentry> + <term><filename>/etc/systemd/journald.conf</filename></term> + + <listitem><para>Configure + <command>systemd-journald</command> + behaviour. See + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/run/log/journal/<replaceable>machine-id</replaceable>/*.journal</filename></term> + <term><filename>/run/log/journal/<replaceable>machine-id</replaceable>/*.journal~</filename></term> + <term><filename>/var/log/journal/<replaceable>machine-id</replaceable>/*.journal</filename></term> + <term><filename>/var/log/journal/<replaceable>machine-id</replaceable>/*.journal~</filename></term> + + <listitem><para><command>systemd-journald</command> writes + entries to files in + <filename>/run/log/journal/<replaceable>machine-id</replaceable>/</filename> + or + <filename>/var/log/journal/<replaceable>machine-id</replaceable>/</filename> + with the <literal>.journal</literal> suffix. If the daemon is + stopped uncleanly, or if the files are found to be corrupted, + they are renamed using the <literal>.journal~</literal> + suffix, and <command>systemd-journald</command> starts writing + to a new file. <filename>/run</filename> is used when + <filename>/var/log/journal</filename> is not available, or + when <option>Storage=volatile</option> is set in the + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + configuration file. </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>setfacl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>4</manvolnum></citerefentry>, + <command>pydoc systemd.journal</command>. + </para> + </refsect1> </refentry> diff --git a/man/systemd-localed.service.xml b/man/systemd-localed.service.xml index 1551e6a2ba..8999166383 100644 --- a/man/systemd-localed.service.xml +++ b/man/systemd-localed.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,67 +23,65 @@ <refentry id="systemd-localed.service" conditional='ENABLE_LOCALED'> - <refentryinfo> - <title>systemd-localed.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-localed.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-localed.service</refname> - <refname>systemd-localed</refname> - <refpurpose>Locale bus mechanism</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-localed.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-localed</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-localed</filename> is a system - service that may be used as mechanism to change the - system locale settings, as well as the console key - mapping and default X11 key - mapping. <filename>systemd-localed</filename> is - automatically activated on request and terminates - itself when it is unused.</para> - - <para>The tool - <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - is a command line client to this service.</para> - - <para>See the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/localed"> - developer documentation</ulink> for information about - the APIs <filename>systemd-localed</filename> - provides.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-localed.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-localed.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-localed.service</refname> + <refname>systemd-localed</refname> + <refpurpose>Locale bus mechanism</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-localed.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-localed</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-localed</filename> is a system service + that may be used as mechanism to change the system locale + settings, as well as the console key mapping and default X11 key + mapping. <filename>systemd-localed</filename> is automatically + activated on request and terminates itself when it is + unused.</para> + + <para>The tool + <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + is a command line client to this service.</para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/localed"> + developer documentation</ulink> for information about the APIs + <filename>systemd-localed</filename> provides.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml index c0c3d1a897..5733e42cd1 100644 --- a/man/systemd-logind.service.xml +++ b/man/systemd-logind.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,109 +23,99 @@ <refentry id="systemd-logind.service" conditional='ENABLE_LOGIND'> - <refentryinfo> - <title>systemd-logind.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-logind.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-logind.service</refname> - <refname>systemd-logind</refname> - <refpurpose>Login manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-logind.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-logind</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-logind</command> is a system - service that manages user logins. It is responsible - for:</para> - - <itemizedlist> - <listitem><para>Keeping track of users and - sessions, their processes and their idle - state</para></listitem> - - <listitem><para>Providing PolicyKit-based access - for users to operations such as system - shutdown or sleep</para></listitem> - - <listitem><para>Implementing a shutdown/sleep - inhibition logic for - applications</para></listitem> - - <listitem><para>Handling of power/sleep - hardware keys</para></listitem> - - <listitem><para>Multi-seat - management</para></listitem> - - <listitem><para>Session - switch management</para></listitem> - - <listitem><para>Device access management for - users</para></listitem> - - <listitem><para>Automatic spawning of text - logins (gettys) on virtual console activation - and user runtime directory - management</para></listitem> - </itemizedlist> - - <para>User sessions are registered in logind via the - <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - PAM module.</para> - - <para>See - <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about the configuration of this - service.</para> - - <para>See <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat - on Linux</ulink> for an introduction into basic - concepts of logind such as users, sessions and seats.</para> - - <para>See the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/logind"> - logind D-Bus API Documentation</ulink> for information about - the APIs <filename>systemd-logind</filename> - provides.</para> - - <para>For more information on the inhibition logic see - the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor - Lock Developer Documentation</ulink>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-user-sessions.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-logind.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-logind.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-logind.service</refname> + <refname>systemd-logind</refname> + <refpurpose>Login manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-logind.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-logind</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-logind</command> is a system service that + manages user logins. It is responsible for:</para> + + <itemizedlist> + <listitem><para>Keeping track of users and sessions, their + processes and their idle state</para></listitem> + + <listitem><para>Providing PolicyKit-based access for users to + operations such as system shutdown or sleep</para></listitem> + + <listitem><para>Implementing a shutdown/sleep inhibition logic + for applications</para></listitem> + + <listitem><para>Handling of power/sleep hardware + keys</para></listitem> + + <listitem><para>Multi-seat management</para></listitem> + + <listitem><para>Session switch management</para></listitem> + + <listitem><para>Device access management for + users</para></listitem> + + <listitem><para>Automatic spawning of text logins (gettys) on + virtual console activation and user runtime directory + management</para></listitem> + </itemizedlist> + + <para>User sessions are registered in logind via the + <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + PAM module.</para> + + <para>See + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the configuration of this service.</para> + + <para>See <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat + on Linux</ulink> for an introduction into basic concepts of logind + such as users, sessions and seats.</para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/logind"> + logind D-Bus API Documentation</ulink> for information about the + APIs <filename>systemd-logind</filename> provides.</para> + + <para>For more information on the inhibition logic see the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor + Lock Developer Documentation</ulink>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-user-sessions.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-machine-id-commit.service.xml b/man/systemd-machine-id-commit.service.xml index c6a0e84564..7c8fc0874e 100644 --- a/man/systemd-machine-id-commit.service.xml +++ b/man/systemd-machine-id-commit.service.xml @@ -21,81 +21,80 @@ --> <refentry id="systemd-machine-id-commit.service"> - <refentryinfo> - <title>systemd-machine-id-commit.service</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Didier</firstname> - <surname>Roche</surname> - <email>didrocks@ubuntu.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-machine-id-commit.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-machine-id-commit.service</refname> - <refpurpose>Commit transient machine-id to disk</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-machine-id-commit.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-machine-id-commit</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-machine-id-commit.service</filename> is - a service responsible for committing any transient - <filename>/etc/machine-id</filename> file to a writable file - system. See - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about this file.</para> - - <para>This service is started shortly after - <filename>local-fs.target</filename> if - <filename>/etc/machine-id</filename> is an independent mount - point (probably a tmpfs one) and /etc is writable. - <command>systemd-machine-id-commit</command> will then - write current machine ID to disk and unmount the transient - <filename>/etc/machine-id</filename> file in a race-free - manner to ensure that file is always valid for other - processes.</para> - - <para>Note that the traditional way to initialize the machine - ID in <filename>/etc/machine-id</filename> is to use - <command>systemd-machine-id-setup</command> by system - installer tools. You can also use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the machine ID on mounted (but not - booted) system images. The main use case for that service is - <filename>/etc/machine-id</filename> being an empty file at - boot and initrd chaining to systemd giving it a read only file - system that will be turned read-write later during the boot - process.</para> - - <para>There is no consequence if that service fails other than - a newer machine-id will be generated during next system boot. - </para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-commit</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-machine-id-commit.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Didier</firstname> + <surname>Roche</surname> + <email>didrocks@ubuntu.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-machine-id-commit.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-machine-id-commit.service</refname> + <refpurpose>Commit transient machine-id to disk</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-machine-id-commit.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-machine-id-commit</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-machine-id-commit.service</filename> is a + service responsible for committing any transient + <filename>/etc/machine-id</filename> file to a writable file + system. See + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information about this file.</para> + + <para>This service is started shortly after + <filename>local-fs.target</filename> if + <filename>/etc/machine-id</filename> is an independent mount point + (probably a tmpfs one) and /etc is writable. + <command>systemd-machine-id-commit</command> will then write + current machine ID to disk and unmount the transient + <filename>/etc/machine-id</filename> file in a race-free manner to + ensure that file is always valid for other processes.</para> + + <para>Note that the traditional way to initialize the machine ID + in <filename>/etc/machine-id</filename> is to use + <command>systemd-machine-id-setup</command> by system installer + tools. You can also use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize the machine ID on mounted (but not booted) system + images. The main use case for that service is + <filename>/etc/machine-id</filename> being an empty file at boot + and initrd chaining to systemd giving it a read only file system + that will be turned read-write later during the boot + process.</para> + + <para>There is no consequence if that service fails other than a + newer machine-id will be generated during next system boot. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-commit</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-machine-id-commit.xml b/man/systemd-machine-id-commit.xml index ed2a6d0bd7..cfb1722063 100644 --- a/man/systemd-machine-id-commit.xml +++ b/man/systemd-machine-id-commit.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,104 +22,102 @@ --> <refentry id="systemd-machine-id-commit" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-machine-id-commit</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Didier</firstname> - <surname>Roche</surname> - <email>didrocks@ubuntu.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-machine-id-commit</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-machine-id-commit</refname> - <refpurpose>Commit transient machine ID to /etc/machine-id</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-machine-id-commit</command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-machine-id-commit</command> may - be used to write on disk any transient machine ID - mounted as a temporary file system in - <filename>/etc/machine-id</filename> at boot time. See - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about this file.</para> - - <para>This tool will execute no operation if - <filename>/etc/machine-id</filename> doesn't contain any - valid machine ID, isn't mounted as an independent temporary - file system, of <filename>/etc</filename> is read-only. If - those conditions are met, it will then write current machine ID - to disk and unmount the transient - <filename>/etc/machine-id</filename> file in a race-free - manner to ensure that this file is always valid for other - processes.</para> - - <para>Note that the traditional way to initialize the machine - ID in <filename>/etc/machine-id</filename> is to use - <command>systemd-machine-id-setup</command> by system - installer tools. You can also use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the machine ID on mounted (but not - booted) system images.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path - as an argument. All paths will be - prefixed with the given alternate - <replaceable>root</replaceable> path, - including config search paths. - </para></listitem> - </varlistentry> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-machine-id-commit</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Didier</firstname> + <surname>Roche</surname> + <email>didrocks@ubuntu.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-machine-id-commit</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-machine-id-commit</refname> + <refpurpose>Commit transient machine ID to /etc/machine-id</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-machine-id-commit</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-machine-id-commit</command> may be used to + write on disk any transient machine ID mounted as a temporary file + system in <filename>/etc/machine-id</filename> at boot time. See + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information about this file.</para> + + <para>This tool will execute no operation if + <filename>/etc/machine-id</filename> doesn't contain any valid + machine ID, isn't mounted as an independent temporary file system, + of <filename>/etc</filename> is read-only. If those conditions are + met, it will then write current machine ID to disk and unmount the + transient <filename>/etc/machine-id</filename> file in a race-free + manner to ensure that this file is always valid for other + processes.</para> + + <para>Note that the traditional way to initialize the machine ID + in <filename>/etc/machine-id</filename> is to use + <command>systemd-machine-id-setup</command> by system installer + tools. You can also use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize the machine ID on mounted (but not booted) system + images.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--root=<replaceable>root</replaceable></option></term> + <listitem><para>Takes a directory path + as an argument. All paths will be + prefixed with the given alternate + <replaceable>root</replaceable> path, + including config search paths. + </para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml index 28352e357f..22bad3e5f4 100644 --- a/man/systemd-machine-id-setup.xml +++ b/man/systemd-machine-id-setup.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,115 +22,109 @@ --> <refentry id="systemd-machine-id-setup" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-machine-id-setup</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-machine-id-setup</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-machine-id-setup</refname> - <refpurpose>Initialize the machine ID in /etc/machine-id</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-machine-id-setup</command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-machine-id-setup</command> may - be used by system installer tools to initialize the - machine ID stored in - <filename>/etc/machine-id</filename> at install time - with a randomly generated ID. See - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about this file.</para> - - <para>This tool will execute no operation if - <filename>/etc/machine-id</filename> is already - initialized.</para> - - <para>If a valid D-Bus machine ID is already - configured for the system, the D-Bus machine ID is - copied and used to initialize the machine ID in - <filename>/etc/machine-id</filename>.</para> - - <para>If run inside a KVM virtual machine and a UUID - is passed via the <option>-uuid</option> option, this - UUID is used to initialize the machine ID instead of a - randomly generated one. The caller must ensure that the - UUID passed is sufficiently unique and is different - for every booted instanced of the VM.</para> - - <para>Similar, if run inside a Linux container - environment and a UUID is set for the container this - is used to initialize the machine ID. For details see - the documentation of the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container - Interface</ulink>.</para> - - <para>Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the machine ID on mounted (but not - booted) system images.</para> - - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path - as an argument. All paths will be - prefixed with the given alternate - <replaceable>root</replaceable> path, - including config search paths. - </para></listitem> - </varlistentry> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-machine-id-setup</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-machine-id-setup</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-machine-id-setup</refname> + <refpurpose>Initialize the machine ID in /etc/machine-id</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-machine-id-setup</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-machine-id-setup</command> may be used by + system installer tools to initialize the machine ID stored in + <filename>/etc/machine-id</filename> at install time with a + randomly generated ID. See + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information about this file.</para> + + <para>This tool will execute no operation if + <filename>/etc/machine-id</filename> is already + initialized.</para> + + <para>If a valid D-Bus machine ID is already configured for the + system, the D-Bus machine ID is copied and used to initialize the + machine ID in <filename>/etc/machine-id</filename>.</para> + + <para>If run inside a KVM virtual machine and a UUID is passed via + the <option>-uuid</option> option, this UUID is used to initialize + the machine ID instead of a randomly generated one. The caller + must ensure that the UUID passed is sufficiently unique and is + different for every booted instanced of the VM.</para> + + <para>Similar, if run inside a Linux container environment and a + UUID is set for the container this is used to initialize the + machine ID. For details see the documentation of the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container + Interface</ulink>.</para> + + <para>Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize the machine ID on mounted (but not booted) system + images.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--root=<replaceable>root</replaceable></option></term> + <listitem><para>Takes a directory path as an argument. All + paths will be prefixed with the given alternate + <replaceable>root</replaceable> path, including config search + paths. </para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-machined.service.xml b/man/systemd-machined.service.xml index 475b53a86e..999aeee1c6 100644 --- a/man/systemd-machined.service.xml +++ b/man/systemd-machined.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,70 +23,68 @@ <refentry id="systemd-machined.service" conditional='ENABLE_MACHINED'> - <refentryinfo> - <title>systemd-machined.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-machined.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-machined.service</refname> - <refname>systemd-machined</refname> - <refpurpose>Virtual machine and container registration manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-machined.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-machined</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-machined</command> is a - system service that keeps track of virtual machines - and containers, and processes belonging to - them.</para> - - <para>See - <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for some examples on how to run containers with OS tools.</para> - - <para>Use - <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry> - to make the names of local containers known to - <command>systemd-machined</command> locally resolvable - as host names.</para> - - <para>See the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/machined"> - machined D-Bus API Documentation</ulink> for information about - the APIs <filename>systemd-machined</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-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-machined.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-machined.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-machined.service</refname> + <refname>systemd-machined</refname> + <refpurpose>Virtual machine and container registration manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-machined.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-machined</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-machined</command> is a system service that + keeps track of virtual machines and containers, and processes + belonging to them.</para> + + <para>See + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for some examples on how to run containers with OS tools.</para> + + <para>Use + <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry> + to make the names of local containers known to + <command>systemd-machined</command> locally resolvable as host + names.</para> + + <para>See the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/machined"> + machined D-Bus API Documentation</ulink> for information about the + APIs <filename>systemd-machined</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-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-modules-load.service.xml b/man/systemd-modules-load.service.xml index 7b99be6be0..dacd083bad 100644 --- a/man/systemd-modules-load.service.xml +++ b/man/systemd-modules-load.service.xml @@ -21,80 +21,76 @@ --> <refentry id="systemd-modules-load.service" conditional='HAVE_KMOD'> - <refentryinfo> - <title>systemd-modules-load.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-modules-load.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-modules-load.service</refname> - <refname>systemd-modules-load</refname> - <refpurpose>Load kernel modules at boot</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-modules-load.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-modules-load</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-modules-load.service</filename> - is an early-boot service that loads kernel modules - based on static configuration.</para> - - <para>See - <citerefentry><refentrytitle>modules-load.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about the configuration of this - service.</para> - - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-modules-load.service</filename> understands - the following kernel command line parameters:</para> - - <variablelist class='kernel-commandline-options'> - - <varlistentry> - <term><varname>modules-load=</varname></term> - <term><varname>rd.modules-load=</varname></term> - - <listitem><para>Takes a comma-separated - list of kernel modules to - statically load during early boot. The - option prefixed with - <literal>rd.</literal> is read by the - initial RAM disk - only.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>modules-load.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - </para> - </refsect1> + <refentryinfo> + <title>systemd-modules-load.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-modules-load.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-modules-load.service</refname> + <refname>systemd-modules-load</refname> + <refpurpose>Load kernel modules at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-modules-load.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-modules-load</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-modules-load.service</filename> is an + early-boot service that loads kernel modules based on static + configuration.</para> + + <para>See + <citerefentry><refentrytitle>modules-load.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the configuration of this service.</para> + + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-modules-load.service</filename> + understands the following kernel command line parameters:</para> + + <variablelist class='kernel-commandline-options'> + + <varlistentry> + <term><varname>modules-load=</varname></term> + <term><varname>rd.modules-load=</varname></term> + + <listitem><para>Takes a comma-separated list of kernel modules + to statically load during early boot. The option prefixed with + <literal>rd.</literal> is read by the initial RAM disk + only.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>modules-load.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + </para> + </refsect1> </refentry> diff --git a/man/systemd-networkd-wait-online.service.xml b/man/systemd-networkd-wait-online.service.xml index 4f039fedc7..f53b337daa 100644 --- a/man/systemd-networkd-wait-online.service.xml +++ b/man/systemd-networkd-wait-online.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,89 +23,87 @@ <refentry id="systemd-networkd-wait-online.service" conditional='ENABLE_NETWORKD'> - <refentryinfo> - <title>systemd-networkd.service</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-networkd-wait-online.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-networkd-wait-online.service</refname> - <refname>systemd-networkd-wait-online</refname> - <refpurpose>Wait for network to come online</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-networkd-wait-online.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-networkd-wait-online</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-networkd-wait-online</command> is a - one-shot system service that waits for the network to be configured. - By default, it will wait for all links it is aware of and which are managed by - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - to be fully configured or failed, and for at least one link to gain a - carrier.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>-i</option></term> - <term><option>--interface=</option></term> - - <listitem><para>Network interface to wait for - before deciding if the system is online. This is - useful when a system has several interfaces which - will be configured, but a particular one is necessary - to access some network resources. This option may be - used more than once to wait for multiple network - interfaces.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--ignore=</option></term> - <listitem><para>Network interfaces to be ignored when - deciding if the system is online. By default only - the loopback interface is ignored. This option may be used - more than once to ignore multiple network interfaces. - </para></listitem> - </varlistentry> - <varlistentry> - <term><option>--timeout=</option></term> - <listitem><para>Fail the service if the network is not - online by the time the timeout elapses. A timeout of 0 - disables the timeout. Defaults to 120 seconds. - </para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-networkd.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + <email>teg@jklm.no</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-networkd-wait-online.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-networkd-wait-online.service</refname> + <refname>systemd-networkd-wait-online</refname> + <refpurpose>Wait for network to come online</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-networkd-wait-online.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-networkd-wait-online</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-networkd-wait-online</command> is a + one-shot system service that waits for the network to be + configured. By default, it will wait for all links it is aware of + and which are managed by + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + to be fully configured or failed, and for at least one link to + gain a carrier.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>-i</option></term> + <term><option>--interface=</option></term> + + <listitem><para>Network interface to wait for before deciding + if the system is online. This is useful when a system has + several interfaces which will be configured, but a particular + one is necessary to access some network resources. This option + may be used more than once to wait for multiple network + interfaces.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--ignore=</option></term> + <listitem><para>Network interfaces to be ignored when deciding + if the system is online. By default only the loopback + interface is ignored. This option may be used more than once + to ignore multiple network interfaces. </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--timeout=</option></term> + <listitem><para>Fail the service if the network is not online + by the time the timeout elapses. A timeout of 0 disables the + timeout. Defaults to 120 seconds. </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-networkd.service.xml b/man/systemd-networkd.service.xml index 7c20fa45b4..0bfe5519bc 100644 --- a/man/systemd-networkd.service.xml +++ b/man/systemd-networkd.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,80 +23,81 @@ <refentry id="systemd-networkd.service" conditional='ENABLE_NETWORKD'> - <refentryinfo> - <title>systemd-networkd.service</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-networkd.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-networkd.service</refname> - <refname>systemd-networkd</refname> - <refpurpose>Network manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-networkd.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-networkd</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-networkd</command> is a system - service that manages networks. It detects and configures - network devices as they appear, as well as creating virtual - network devices.</para> - - <para>To configure low-level link settings independently of - networks, see - <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>Network configurations applied before networkd is started - are not removed, and static configuration applied by networkd - is not removed when networkd exits. Dynamic configuration applied by - networkd may also optionally be left in place on shutdown. This ensures - restarting networkd does not cut the network connection, and, in particular, - that it is safe to transition between the initrd and the real root, - and back.</para> - </refsect1> - - <refsect1><title>Configuration Files</title> - <para>The configuration files are read from the files located in the - system network directory <filename>/usr/lib/systemd/network</filename>, - the volatile runtime network directory - <filename>/run/systemd/network</filename> and the local administration - network directory <filename>/etc/systemd/network</filename>.</para> - - <para>Networks are configured in <filename>.network</filename> files, see - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - and virtual network devices are configured in <filename>.netdev</filename> files, see - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd-wait-online.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-networkd.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + <email>teg@jklm.no</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-networkd.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-networkd.service</refname> + <refname>systemd-networkd</refname> + <refpurpose>Network manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-networkd.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-networkd</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-networkd</command> is a system service that + manages networks. It detects and configures network devices as + they appear, as well as creating virtual network devices.</para> + + <para>To configure low-level link settings independently of + networks, see + <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>Network configurations applied before networkd is started + are not removed, and static configuration applied by networkd is + not removed when networkd exits. Dynamic configuration applied by + networkd may also optionally be left in place on shutdown. This + ensures restarting networkd does not cut the network connection, + and, in particular, that it is safe to transition between the + initrd and the real root, and back.</para> + </refsect1> + + <refsect1><title>Configuration Files</title> + <para>The configuration files are read from the files located in the + system network directory <filename>/usr/lib/systemd/network</filename>, + the volatile runtime network directory + <filename>/run/systemd/network</filename> and the local administration + network directory <filename>/etc/systemd/network</filename>.</para> + + <para>Networks are configured in <filename>.network</filename> + files, see + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + and virtual network devices are configured in + <filename>.netdev</filename> files, see + <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd-wait-online.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml index 684f490099..06d5ae5319 100644 --- a/man/systemd-notify.xml +++ b/man/systemd-notify.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,175 +22,159 @@ --> <refentry id="systemd-notify" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-notify</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-notify</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-notify</refname> - <refpurpose>Notify service manager about start-up completion and other daemon status changes</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-notify <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-notify</command> may be - called by daemon scripts to notify the init system - about status changes. It can be used to send arbitrary - information, encoded in an environment-block-like list - of strings. Most importantly it can be used for - start-up completion notification.</para> - - <para>This is mostly just a wrapper around - <function>sd_notify()</function> and makes this - functionality available to shell scripts. For details - see - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - - <para>The command line may carry a list of - environment variables to send as part of the status - update.</para> - - <para>Note that systemd will refuse reception of - status updates from this command unless - <varname>NotifyAccess=all</varname> is set for the - service unit this command is called from.</para> - - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--ready</option></term> - - <listitem><para>Inform the init system - about service start-up - completion. This is equivalent to - <command>systemd-notify - READY=1</command>. For details about - the semantics of this option see - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--pid=</option></term> - - <listitem><para>Inform the init system - about the main PID of the - daemon. Takes a PID as argument. If - the argument is omitted, the PID of the - process that invoked - <command>systemd-notify</command> is - used. This is equivalent to - <command>systemd-notify - MAINPID=$PID</command>. For details - about the semantics of this option see - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--status=</option></term> - - <listitem><para>Send a free-form - status string for the daemon to the - init systemd. This option takes the - status string as argument. This is - equivalent to <command>systemd-notify - STATUS=...</command>. For details - about the semantics of this option see - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--booted</option></term> - - <listitem><para>Returns 0 if the - system was booted up with systemd, - non-zero otherwise. If this option is - passed, no message is sent. This option - is hence unrelated to the other - options. For details about the - semantics of this option, see - <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>Example</title> - - <example> - <title>Start-up Notification and Status Updates</title> - - <para>A simple shell daemon that sends - start-up notifications after having set up its - communication channel. During runtime it sends - further status updates to the init - system:</para> - - <programlisting>#!/bin/bash + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-notify</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-notify</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-notify</refname> + <refpurpose>Notify service manager about start-up completion and other daemon status changes</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-notify <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-notify</command> may be called by daemon + scripts to notify the init system about status changes. It can be + used to send arbitrary information, encoded in an + environment-block-like list of strings. Most importantly it can be + used for start-up completion notification.</para> + + <para>This is mostly just a wrapper around + <function>sd_notify()</function> and makes this functionality + available to shell scripts. For details see + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + + <para>The command line may carry a list of environment variables + to send as part of the status update.</para> + + <para>Note that systemd will refuse reception of status updates + from this command unless <varname>NotifyAccess=all</varname> is + set for the service unit this command is called from.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--ready</option></term> + + <listitem><para>Inform the init system about service start-up + completion. This is equivalent to <command>systemd-notify + READY=1</command>. For details about the semantics of this + option see + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--pid=</option></term> + + <listitem><para>Inform the init system about the main PID of + the daemon. Takes a PID as argument. If the argument is + omitted, the PID of the process that invoked + <command>systemd-notify</command> is used. This is equivalent + to <command>systemd-notify MAINPID=$PID</command>. For details + about the semantics of this option see + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--status=</option></term> + + <listitem><para>Send a free-form status string for the daemon + to the init systemd. This option takes the status string as + argument. This is equivalent to <command>systemd-notify + STATUS=...</command>. For details about the semantics of this + option see + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--booted</option></term> + + <listitem><para>Returns 0 if the system was booted up with + systemd, non-zero otherwise. If this option is passed, no + message is sent. This option is hence unrelated to the other + options. For details about the semantics of this option, see + <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <example> + <title>Start-up Notification and Status Updates</title> + + <para>A simple shell daemon that sends start-up notifications + after having set up its communication channel. During runtime it + sends further status updates to the init system:</para> + + <programlisting>#!/bin/bash mkfifo /tmp/waldo systemd-notify --ready --status="Waiting for data..." while : ; do - read a < /tmp/waldo - systemd-notify --status="Processing $a" + read a < /tmp/waldo + systemd-notify --status="Processing $a" - # Do something with $a ... + # Do something with $a ... - systemd-notify --status="Waiting for data..." + systemd-notify --status="Waiting for data..." done</programlisting> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 4b7ec1d391..4a936d326f 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,919 +22,721 @@ --> <refentry id="systemd-nspawn" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-nspawn</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-nspawn</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-nspawn</refname> - <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-nspawn</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt"><replaceable>COMMAND</replaceable> - <arg choice="opt" rep="repeat">ARGS</arg> - </arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-nspawn</command> - <arg choice="plain">-b</arg> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat">ARGS</arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-nspawn</command> may be used to - run a command or OS in a light-weight namespace - container. In many ways it is similar to - <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - but more powerful since it fully virtualizes the file - system hierarchy, as well as the process tree, the - various IPC subsystems and the host and domain - name.</para> - - <para><command>systemd-nspawn</command> limits access - to various kernel interfaces in the container to - read-only, such as <filename>/sys</filename>, - <filename>/proc/sys</filename> or - <filename>/sys/fs/selinux</filename>. Network - interfaces and the system clock may not be changed - from within the container. Device nodes may not be - created. The host system cannot be rebooted and kernel - modules may not be loaded from within the - container.</para> - - <para>Note that even though these security precautions - are taken <command>systemd-nspawn</command> is not - suitable for secure container setups. Many of the - security features may be circumvented and are hence - primarily useful to avoid accidental changes to the - host system from the container. The intended use of - this program is debugging and testing as well as - building of packages, distributions and software - involved with boot and systems management.</para> - - <para>In contrast to - <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command> - may be used to boot full Linux-based operating systems - in a container.</para> - - <para>Use a tool like - <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - or - <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry> - to set up an OS directory tree suitable as file system - hierarchy for <command>systemd-nspawn</command> - containers.</para> - - <para>Note that <command>systemd-nspawn</command> will - mount file systems private to the container to - <filename>/dev</filename>, - <filename>/run</filename> and similar. These will - not be visible outside of the container, and their - contents will be lost when the container exits.</para> - - <para>Note that running two - <command>systemd-nspawn</command> containers from the - same directory tree will not make processes in them - see each other. The PID namespace separation of the - two containers is complete and the containers will - share very few runtime objects except for the - underlying file system. Use - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <command>login</command> command to request an - additional login prompt in a running container.</para> - - <para><command>systemd-nspawn</command> implements the - <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container - Interface</ulink> specification.</para> - - <para>As a safety check - <command>systemd-nspawn</command> will verify the - existence of <filename>/usr/lib/os-release</filename> - or <filename>/etc/os-release</filename> in the - container tree before starting the container (see - <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It - might be necessary to add this file to the container - tree manually if the OS of the container is too old to - contain this file out-of-the-box.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>If option <option>-b</option> is specified, the - arguments are used as arguments for the init - binary. Otherwise, <replaceable>COMMAND</replaceable> - specifies the program to launch in the container, and - the remaining arguments are used as arguments for this - program. If <option>-b</option> is not used and no - arguments are specifed, a shell is launched in the - container.</para> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>-D</option></term> - <term><option>--directory=</option></term> - - <listitem><para>Directory to use as - file system root for the container.</para> - - <para>If neither - <option>--directory=</option>, nor - <option>--image=</option> is specified - the directory is determined as - <filename>/var/lib/machines/</filename> - suffixed by the machine name as - specified with - <option>--machine=</option>. If - neither <option>--directory=</option>, - <option>--image=</option>, nor - <option>--machine=</option> are - specified, the current directory will - be used. May not be specified together - with - <option>--image=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--template=</option></term> - - <listitem><para>Directory or - <literal>btrfs</literal> subvolume to - use as template for the container's - root directory. If this is specified - and the container's root directory (as - configured by - <option>--directory=</option>) does - not yet exist it is created as - <literal>btrfs</literal> subvolume and - populated from this template - tree. Ideally, the specified template - path refers to the root of a - <literal>btrfs</literal> subvolume, in - which case a simple copy-on-write - snapshot is taken, and populating the - root directory is instant. If the - specified template path does not refer - to the root of a - <literal>btrfs</literal> subvolume (or - not even to a <literal>btrfs</literal> - file system at all), the tree is - copied, which can be substantially - more time-consuming. Note that if this - option is used the container's root - directory (in contrast to the template - directory!) must be located on a - <literal>btrfs</literal> file system, - so that the <literal>btrfs</literal> - subvolume may be created. May not be - specified together with - <option>--image=</option> or - <option>--ephemeral</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-x</option></term> - <term><option>--ephemeral</option></term> - - <listitem><para>If specified, the - container is run with a temporary - <literal>btrfs</literal> snapshot of - its root directory (as configured with - <option>--directory=</option>), that - is removed immediately when the - container terminates. This option is - only supported if the root file system - is <literal>btrfs</literal>. May not - be specified together with - <option>--image=</option> or - <option>--template=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-i</option></term> - <term><option>--image=</option></term> - - <listitem><para>Disk image to mount - the root directory for the container - from. Takes a path to a regular file - or to a block device node. The file or - block device must contain either:</para> - - <itemizedlist> - <listitem><para>An MBR - partition table with a single - partition of type 0x83 that is - marked - bootable.</para></listitem> - - <listitem><para>A GUID - partition table (GPT) with a single - partition of type - 0fc63daf-8483-4772-8e79-3d69d8477de4.</para></listitem> - - <listitem><para>A GUID - partition table (GPT) with a - marked root partition which is - mounted as the root directory - of the container. Optionally, - GPT images may contain a home - and/or a server data partition - which are mounted to the - appropriate places in the - container. All these - partitions must be identified - by the partition types defined - by the <ulink - url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable - Partitions - Specification</ulink>.</para></listitem> - </itemizedlist> - - <para>Any other partitions, such as - foreign partitions, swap partitions or - EFI system partitions are not - mounted. May not be specified together - with <option>--directory=</option>, - <option>--template=</option> or - <option>--ephemeral</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-b</option></term> - <term><option>--boot</option></term> - - <listitem><para>Automatically search - for an init binary and invoke it - instead of a shell or a user supplied - program. If this option is used, - arguments specified on the command - line are used as arguments for the - init binary. This option may not be - combined with - <option>--share-system</option>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-u</option></term> - <term><option>--user=</option></term> - - <listitem><para>After transitioning - into the container, change to the - specified user-defined in the - container's user database. Like all - other systemd-nspawn features, this is - not a security feature and provides - protection against accidental - destructive operations - only.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-M</option></term> - <term><option>--machine=</option></term> - - <listitem><para>Sets the machine name - for this container. This name may be - used to identify this container during - its runtime (for example in tools like - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and similar), and is used to - initialize the container's hostname - (which the container can choose to - override, however). If not specified, - the last component of the root - directory path of the container is - used, possibly suffixed with a random - identifier in case - <option>--ephemeral</option> mode is - selected. If the root directory - selected is the host's root directory - the host's hostname is used as default - instead.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--uuid=</option></term> - - <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> - </varlistentry> - - <varlistentry> - <term><option>--slice=</option></term> - - <listitem><para>Make the container - part of the specified slice, instead - of the default - <filename>machine.slice</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--private-network</option></term> - - <listitem><para>Disconnect networking - of the container from the host. This - makes all network interfaces - unavailable in the container, with the - exception of the loopback device and - those specified with - <option>--network-interface=</option> - and configured with - <option>--network-veth</option>. If - this option is specified, the - CAP_NET_ADMIN capability will be added - to the set of capabilities the - container retains. The latter may be - disabled by using - <option>--drop-capability=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--network-interface=</option></term> - - <listitem><para>Assign the specified - network interface to the - container. This will remove the - specified interface from the calling - namespace and place it in the - container. When the container - terminates, it is moved back to the - host namespace. Note that - <option>--network-interface=</option> - implies - <option>--private-network</option>. This - option may be used more than once to - add multiple network interfaces to the - container.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--network-macvlan=</option></term> - - <listitem><para>Create a - <literal>macvlan</literal> interface - of the specified Ethernet network - interface and add it to the - container. A - <literal>macvlan</literal> interface - is a virtual interface that adds a - second MAC address to an existing - physical Ethernet link. The interface - in the container will be named after - the interface on the host, prefixed - with <literal>mv-</literal>. Note that - <option>--network-macvlan=</option> - implies - <option>--private-network</option>. This - option may be used more than once to - add multiple network interfaces to the - container.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--network-ipvlan=</option></term> - - <listitem><para>Create an - <literal>ipvlan</literal> interface - of the specified Ethernet network - interface and add it to the - container. An - <literal>ipvlan</literal> interface - is a virtual interface, similar to a - <literal>macvlan</literal> interface, which - uses the same MAC address as the underlying - interface. The interface - in the container will be named after - the interface on the host, prefixed - with <literal>iv-</literal>. Note that - <option>--network-ipvlan=</option> - implies - <option>--private-network</option>. This - option may be used more than once to - add multiple network interfaces to the - container.</para></listitem> - </varlistentry> - - <varlistentry> - <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> - </varlistentry> - - <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 <literal>ve-</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-p</option></term> - <term><option>--port=</option></term> - - <listitem><para>If private networking - is enabled, maps an IP port on the - host onto an IP port on the - container. Takes a protocol specifier - (either <literal>tcp</literal> or - <literal>udp</literal>), separated by - a colon from a host port number in the - range 1 to 65535, separated by a colon - from a container port number in the - range from 1 to 65535. The protocol - specifier and its separating colon may - be omitted, in which case - <literal>tcp</literal> is assumed. - The container port number and its - colon may be ommitted, in which case - the same port as the host port is - implied. This option is only supported - if private networking is used, such as - <option>--network-veth</option> or - <option>--network-bridge=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-Z</option></term> - <term><option>--selinux-context=</option></term> - - <listitem><para>Sets the SELinux - security context to be used to label - processes in the container.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>-L</option></term> - <term><option>--selinux-apifs-context=</option></term> - - <listitem><para>Sets the SELinux security - context to be used to label files in - the virtual API file systems in the - container.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>--capability=</option></term> - - <listitem><para>List one or more - additional capabilities to grant the - container. Takes a comma-separated - list of capability names, see - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for more information. Note that the - following capabilities will be granted - in any way: CAP_CHOWN, - CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, - CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, - CAP_KILL, CAP_LEASE, - CAP_LINUX_IMMUTABLE, - CAP_NET_BIND_SERVICE, - CAP_NET_BROADCAST, CAP_NET_RAW, - CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, - CAP_SETUID, CAP_SYS_ADMIN, - CAP_SYS_CHROOT, CAP_SYS_NICE, - CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG, - CAP_SYS_RESOURCE, CAP_SYS_BOOT, - CAP_AUDIT_WRITE, - CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN - is retained if - <option>--private-network</option> is - specified. If the special value - <literal>all</literal> is passed, all - capabilities are - retained.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--drop-capability=</option></term> - - <listitem><para>Specify one or more - additional capabilities to drop for - the container. This allows running the - container with fewer capabilities than - the default (see above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--link-journal=</option></term> - - <listitem><para>Control whether the - container's journal shall be made - visible to the host system. If enabled, - allows viewing the container's journal - files from the host (but not vice - versa). Takes one of - <literal>no</literal>, - <literal>host</literal>, - <literal>try-host</literal>, - <literal>guest</literal>, - <literal>try-guest</literal>, - <literal>auto</literal>. If - <literal>no</literal>, the journal is - not linked. If <literal>host</literal>, - the journal files are stored on the - host file system (beneath - <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>) - and the subdirectory is bind-mounted - into the container at the same - location. If <literal>guest</literal>, - the journal files are stored on the - guest file system (beneath - <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>) - and the subdirectory is symlinked into the host - at the same location. <literal>try-host</literal> - and <literal>try-guest</literal> do the same - but do not fail if the host does not have - persistent journalling enabled. - If <literal>auto</literal> (the default), - and the right subdirectory of - <filename>/var/log/journal</filename> - exists, it will be bind mounted - into the container. If the - subdirectory does not exist, no - linking is performed. Effectively, - booting a container once with - <literal>guest</literal> or - <literal>host</literal> will link the - journal persistently if further on - the default of <literal>auto</literal> - is used.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-j</option></term> - - <listitem><para>Equivalent to - <option>--link-journal=try-guest</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--read-only</option></term> - - <listitem><para>Mount the root file - system read-only for the - container.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--bind=</option></term> - <term><option>--bind-ro=</option></term> - - <listitem><para>Bind mount a file or - directory from the host into the - container. Either takes a path - argument -- in which case the - specified path will be mounted from - the host to the same path in the - container --, or a colon-separated - pair of paths -- in which case the - first specified path is the source in - the host, and the second path is the - destination in the container. The - <option>--bind-ro=</option> option - creates read-only bind - mounts.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--tmpfs=</option></term> - - <listitem><para>Mount a tmpfs file - system into the container. Takes a - single absolute path argument that - specifies where to mount the tmpfs - instance to (in which case the - directory access mode will be chosen - as 0755, owned by root/root), or - optionally a colon-separated pair of - path and mount option string, that is - used for mounting (in which case the - kernel default for access mode and - owner will be chosen, unless otherwise - specified). This option is - particularly useful for mounting - directories such as - <filename>/var</filename> as tmpfs, to - allow state-less systems, in - particular when combined with - <option>--read-only</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--setenv=</option></term> - - <listitem><para>Specifies an - environment variable assignment to - pass to the init process in the - container, in the format - <literal>NAME=VALUE</literal>. This - may be used to override the default - variables or to set additional - variables. This parameter may be used - more than once.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--share-system</option></term> - - <listitem><para>Allows the container - to share certain system facilities - with the host. More specifically, this - turns off PID namespacing, UTS - namespacing and IPC namespacing, and - thus allows the guest to see and - interact more easily with processes - outside of the container. Note that - using this option makes it impossible - to start up a full Operating System in - the container, as an init system - cannot operate in this mode. It is - only useful to run specific programs - or applications this way, without - involving an init system in the - container. This option implies - <option>--register=no</option>. This - option may not be combined with - <option>--boot</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--register=</option></term> - - <listitem><para>Controls whether the - container is registered with - <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes - a boolean argument, defaults to - <literal>yes</literal>. This option - should be enabled when the container - runs a full Operating System (more - specifically: an init system), and is - useful to ensure that the container is - accessible via - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and shown by tools such as - <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If - the container does not run an init - system, it is recommended to set this - option to <literal>no</literal>. Note - that <option>--share-system</option> - implies - <option>--register=no</option>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--keep-unit</option></term> - - <listitem><para>Instead of creating a - transient scope unit to run the - container in, simply register the - service or scope unit - <command>systemd-nspawn</command> has - been invoked in with - <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This - has no effect if - <option>--register=no</option> is - used. This switch should be used if - <command>systemd-nspawn</command> is - invoked from within a service unit, - and the service unit's sole purpose - is to run a single - <command>systemd-nspawn</command> - container. This option is not - available if run from a user - session.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--personality=</option></term> - - <listitem><para>Control the - architecture ("personality") reported - by - <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> - in the container. Currently, only - <literal>x86</literal> and - <literal>x86-64</literal> are - supported. This is useful when running - a 32-bit container on a 64-bit - host. If this setting is not used, - the personality reported in the - container is the same as the one - reported on the - host.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>-q</option></term> - <term><option>--quiet</option></term> - - <listitem><para>Turns off any status - output by the tool itself. When this - switch is used, the only output - from nspawn will be the console output - of the container OS itself.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--volatile</option><replaceable>=MODE</replaceable></term> - - <listitem><para>Boots the container in - volatile mode. When no mode parameter - is passed or when mode is specified as - <literal>yes</literal> full volatile - mode is enabled. This means the root - directory is mounted as mostly - unpopulated <literal>tmpfs</literal> - instance, and - <filename>/usr</filename> from the OS - tree is mounted into it, read-only - (the system thus starts up with - read-only OS resources, but pristine - state and configuration, any changes - to the either are lost on - shutdown). When the mode parameter is - specified as <literal>state</literal> - the OS tree is mounted read-only, but - <filename>/var</filename> is mounted - as <literal>tmpfs</literal> instance - into it (the system thus starts up - with read-only OS resources and - configuration, but pristine state, any - changes to the latter are lost on - shutdown). When the mode parameter is - specified as <literal>no</literal> - (the default) the whole OS tree is - made available writable.</para> - - <para>Note that setting this to - <literal>yes</literal> or - <literal>state</literal> will only - work correctly with operating systems - in the container that can boot up with - only <filename>/usr</filename> - mounted, and are able to populate - <filename>/var</filename> - automatically, as - needed.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Download a Fedora image and start a shell in it</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 + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-nspawn</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-nspawn</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-nspawn</refname> + <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-nspawn</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt"><replaceable>COMMAND</replaceable> + <arg choice="opt" rep="repeat">ARGS</arg> + </arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-nspawn</command> + <arg choice="plain">-b</arg> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt" rep="repeat">ARGS</arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-nspawn</command> may be used to run a + command or OS in a light-weight namespace container. In many ways + it is similar to + <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + but more powerful since it fully virtualizes the file system + hierarchy, as well as the process tree, the various IPC subsystems + and the host and domain name.</para> + + <para><command>systemd-nspawn</command> limits access to various + kernel interfaces in the container to read-only, such as + <filename>/sys</filename>, <filename>/proc/sys</filename> or + <filename>/sys/fs/selinux</filename>. Network interfaces and the + system clock may not be changed from within the container. Device + nodes may not be created. The host system cannot be rebooted and + kernel modules may not be loaded from within the container.</para> + + <para>Note that even though these security precautions are taken + <command>systemd-nspawn</command> is not suitable for secure + container setups. Many of the security features may be + circumvented and are hence primarily useful to avoid accidental + changes to the host system from the container. The intended use of + this program is debugging and testing as well as building of + packages, distributions and software involved with boot and + systems management.</para> + + <para>In contrast to + <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command> + may be used to boot full Linux-based operating systems in a + container.</para> + + <para>Use a tool like + <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + or + <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry> + to set up an OS directory tree suitable as file system hierarchy + for <command>systemd-nspawn</command> containers.</para> + + <para>Note that <command>systemd-nspawn</command> will mount file + systems private to the container to <filename>/dev</filename>, + <filename>/run</filename> and similar. These will not be visible + outside of the container, and their contents will be lost when the + container exits.</para> + + <para>Note that running two <command>systemd-nspawn</command> + containers from the same directory tree will not make processes in + them see each other. The PID namespace separation of the two + containers is complete and the containers will share very few + runtime objects except for the underlying file system. Use + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <command>login</command> command to request an additional login + prompt in a running container.</para> + + <para><command>systemd-nspawn</command> implements the + <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container + Interface</ulink> specification.</para> + + <para>As a safety check <command>systemd-nspawn</command> will + verify the existence of <filename>/usr/lib/os-release</filename> + or <filename>/etc/os-release</filename> in the container tree + before starting the container (see + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + It might be necessary to add this file to the container tree + manually if the OS of the container is too old to contain this + file out-of-the-box.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>If option <option>-b</option> is specified, the arguments + are used as arguments for the init binary. Otherwise, + <replaceable>COMMAND</replaceable> specifies the program to launch + in the container, and the remaining arguments are used as + arguments for this program. If <option>-b</option> is not used and + no arguments are specifed, a shell is launched in the + container.</para> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>-D</option></term> + <term><option>--directory=</option></term> + + <listitem><para>Directory to use as file system root for the + container.</para> + + <para>If neither <option>--directory=</option>, nor + <option>--image=</option> is specified the directory is + determined as <filename>/var/lib/machines/</filename> suffixed + by the machine name as specified with + <option>--machine=</option>. If neither + <option>--directory=</option>, <option>--image=</option>, nor + <option>--machine=</option> are specified, the current + directory will be used. May not be specified together with + <option>--image=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--template=</option></term> + + <listitem><para>Directory or <literal>btrfs</literal> + subvolume to use as template for the container's root + directory. If this is specified and the container's root + directory (as configured by <option>--directory=</option>) + does not yet exist it is created as <literal>btrfs</literal> + subvolume and populated from this template tree. Ideally, the + specified template path refers to the root of a + <literal>btrfs</literal> subvolume, in which case a simple + copy-on-write snapshot is taken, and populating the root + directory is instant. If the specified template path does not + refer to the root of a <literal>btrfs</literal> subvolume (or + not even to a <literal>btrfs</literal> file system at all), + the tree is copied, which can be substantially more + time-consuming. Note that if this option is used the + container's root directory (in contrast to the template + directory!) must be located on a <literal>btrfs</literal> file + system, so that the <literal>btrfs</literal> subvolume may be + created. May not be specified together with + <option>--image=</option> or + <option>--ephemeral</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-x</option></term> + <term><option>--ephemeral</option></term> + + <listitem><para>If specified, the container is run with a + temporary <literal>btrfs</literal> snapshot of its root + directory (as configured with <option>--directory=</option>), + that is removed immediately when the container terminates. + This option is only supported if the root file system is + <literal>btrfs</literal>. May not be specified together with + <option>--image=</option> or + <option>--template=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-i</option></term> + <term><option>--image=</option></term> + + <listitem><para>Disk image to mount the root directory for the + container from. Takes a path to a regular file or to a block + device node. The file or block device must contain + either:</para> + + <itemizedlist> + <listitem><para>An MBR partition table with a single + partition of type 0x83 that is marked + bootable.</para></listitem> + + <listitem><para>A GUID partition table (GPT) with a single + partition of type + 0fc63daf-8483-4772-8e79-3d69d8477de4.</para></listitem> + + <listitem><para>A GUID partition table (GPT) with a marked + root partition which is mounted as the root directory of the + container. Optionally, GPT images may contain a home and/or + a server data partition which are mounted to the appropriate + places in the container. All these partitions must be + identified by the partition types defined by the <ulink + url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable + Partitions Specification</ulink>.</para></listitem> + </itemizedlist> + + <para>Any other partitions, such as foreign partitions, swap + partitions or EFI system partitions are not mounted. May not + be specified together with <option>--directory=</option>, + <option>--template=</option> or + <option>--ephemeral</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-b</option></term> + <term><option>--boot</option></term> + + <listitem><para>Automatically search for an init binary and + invoke it instead of a shell or a user supplied program. If + this option is used, arguments specified on the command line + are used as arguments for the init binary. This option may not + be combined with <option>--share-system</option>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-u</option></term> + <term><option>--user=</option></term> + + <listitem><para>After transitioning into the container, change + to the specified user-defined in the container's user + database. Like all other systemd-nspawn features, this is not + a security feature and provides protection against accidental + destructive operations only.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-M</option></term> + <term><option>--machine=</option></term> + + <listitem><para>Sets the machine name for this container. This + name may be used to identify this container during its runtime + (for example in tools like + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and similar), and is used to initialize the container's + hostname (which the container can choose to override, + however). If not specified, the last component of the root + directory path of the container is used, possibly suffixed + with a random identifier in case <option>--ephemeral</option> + mode is selected. If the root directory selected is the host's + root directory the host's hostname is used as default + instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--uuid=</option></term> + + <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> + </varlistentry> + + <varlistentry> + <term><option>--slice=</option></term> + + <listitem><para>Make the container part of the specified + slice, instead of the default + <filename>machine.slice</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--private-network</option></term> + + <listitem><para>Disconnect networking of the container from + the host. This makes all network interfaces unavailable in the + container, with the exception of the loopback device and those + specified with <option>--network-interface=</option> and + configured with <option>--network-veth</option>. If this + option is specified, the CAP_NET_ADMIN capability will be + added to the set of capabilities the container retains. The + latter may be disabled by using + <option>--drop-capability=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--network-interface=</option></term> + + <listitem><para>Assign the specified network interface to the + container. This will remove the specified interface from the + calling namespace and place it in the container. When the + container terminates, it is moved back to the host namespace. + Note that <option>--network-interface=</option> implies + <option>--private-network</option>. This option may be used + more than once to add multiple network interfaces to the + container.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--network-macvlan=</option></term> + + <listitem><para>Create a <literal>macvlan</literal> interface + of the specified Ethernet network interface and add it to the + container. A <literal>macvlan</literal> interface is a virtual + interface that adds a second MAC address to an existing + physical Ethernet link. The interface in the container will be + named after the interface on the host, prefixed with + <literal>mv-</literal>. Note that + <option>--network-macvlan=</option> implies + <option>--private-network</option>. This option may be used + more than once to add multiple network interfaces to the + container.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--network-ipvlan=</option></term> + + <listitem><para>Create an <literal>ipvlan</literal> interface + of the specified Ethernet network interface and add it to the + container. An <literal>ipvlan</literal> interface is a virtual + interface, similar to a <literal>macvlan</literal> interface, + which uses the same MAC address as the underlying interface. + The interface in the container will be named after the + interface on the host, prefixed with <literal>iv-</literal>. + Note that <option>--network-ipvlan=</option> implies + <option>--private-network</option>. This option may be used + more than once to add multiple network interfaces to the + container.</para></listitem> + </varlistentry> + + <varlistentry> + <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> + </varlistentry> + + <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 + <literal>ve-</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-p</option></term> + <term><option>--port=</option></term> + + <listitem><para>If private networking is enabled, maps an IP + port on the host onto an IP port on the container. Takes a + protocol specifier (either <literal>tcp</literal> or + <literal>udp</literal>), separated by a colon from a host port + number in the range 1 to 65535, separated by a colon from a + container port number in the range from 1 to 65535. The + protocol specifier and its separating colon may be omitted, in + which case <literal>tcp</literal> is assumed. The container + port number and its colon may be ommitted, in which case the + same port as the host port is implied. This option is only + supported if private networking is used, such as + <option>--network-veth</option> or + <option>--network-bridge=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-Z</option></term> + <term><option>--selinux-context=</option></term> + + <listitem><para>Sets the SELinux security context to be used + to label processes in the container.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-L</option></term> + <term><option>--selinux-apifs-context=</option></term> + + <listitem><para>Sets the SELinux security context to be used + to label files in the virtual API file systems in the + container.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--capability=</option></term> + + <listitem><para>List one or more additional capabilities to + grant the container. Takes a comma-separated list of + capability names, see + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for more information. Note that the following capabilities + will be granted in any way: CAP_CHOWN, CAP_DAC_OVERRIDE, + CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, + CAP_KILL, CAP_LEASE, CAP_LINUX_IMMUTABLE, + CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_RAW, + CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, CAP_SETUID, + CAP_SYS_ADMIN, CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE, + CAP_SYS_TTY_CONFIG, CAP_SYS_RESOURCE, CAP_SYS_BOOT, + CAP_AUDIT_WRITE, CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN is + retained if <option>--private-network</option> is specified. + If the special value <literal>all</literal> is passed, all + capabilities are retained.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--drop-capability=</option></term> + + <listitem><para>Specify one or more additional capabilities to + drop for the container. This allows running the container with + fewer capabilities than the default (see + above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--link-journal=</option></term> + + <listitem><para>Control whether the container's journal shall + be made visible to the host system. If enabled, allows viewing + the container's journal files from the host (but not vice + versa). Takes one of <literal>no</literal>, + <literal>host</literal>, <literal>try-host</literal>, + <literal>guest</literal>, <literal>try-guest</literal>, + <literal>auto</literal>. If <literal>no</literal>, the journal + is not linked. If <literal>host</literal>, the journal files + are stored on the host file system (beneath + <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>) + and the subdirectory is bind-mounted into the container at the + same location. If <literal>guest</literal>, the journal files + are stored on the guest file system (beneath + <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>) + and the subdirectory is symlinked into the host at the same + location. <literal>try-host</literal> and + <literal>try-guest</literal> do the same but do not fail if + the host does not have persistent journalling enabled. If + <literal>auto</literal> (the default), and the right + subdirectory of <filename>/var/log/journal</filename> exists, + it will be bind mounted into the container. If the + subdirectory does not exist, no linking is performed. + Effectively, booting a container once with + <literal>guest</literal> or <literal>host</literal> will link + the journal persistently if further on the default of + <literal>auto</literal> is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-j</option></term> + + <listitem><para>Equivalent to + <option>--link-journal=try-guest</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--read-only</option></term> + + <listitem><para>Mount the root file system read-only for the + container.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--bind=</option></term> + <term><option>--bind-ro=</option></term> + + <listitem><para>Bind mount a file or directory from the host + into the container. Either takes a path argument -- in which + case the specified path will be mounted from the host to the + same path in the container --, or a colon-separated pair of + paths -- in which case the first specified path is the source + in the host, and the second path is the destination in the + container. The <option>--bind-ro=</option> option creates + read-only bind mounts.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--tmpfs=</option></term> + + <listitem><para>Mount a tmpfs file system into the container. + Takes a single absolute path argument that specifies where to + mount the tmpfs instance to (in which case the directory + access mode will be chosen as 0755, owned by root/root), or + optionally a colon-separated pair of path and mount option + string, that is used for mounting (in which case the kernel + default for access mode and owner will be chosen, unless + otherwise specified). This option is particularly useful for + mounting directories such as <filename>/var</filename> as + tmpfs, to allow state-less systems, in particular when + combined with <option>--read-only</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--setenv=</option></term> + + <listitem><para>Specifies an environment variable assignment + to pass to the init process in the container, in the format + <literal>NAME=VALUE</literal>. This may be used to override + the default variables or to set additional variables. This + parameter may be used more than once.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--share-system</option></term> + + <listitem><para>Allows the container to share certain system + facilities with the host. More specifically, this turns off + PID namespacing, UTS namespacing and IPC namespacing, and thus + allows the guest to see and interact more easily with + processes outside of the container. Note that using this + option makes it impossible to start up a full Operating System + in the container, as an init system cannot operate in this + mode. It is only useful to run specific programs or + applications this way, without involving an init system in the + container. This option implies <option>--register=no</option>. + This option may not be combined with + <option>--boot</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--register=</option></term> + + <listitem><para>Controls whether the container is registered + with + <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + Takes a boolean argument, defaults to <literal>yes</literal>. + This option should be enabled when the container runs a full + Operating System (more specifically: an init system), and is + useful to ensure that the container is accessible via + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and shown by tools such as + <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + If the container does not run an init system, it is + recommended to set this option to <literal>no</literal>. Note + that <option>--share-system</option> implies + <option>--register=no</option>. </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--keep-unit</option></term> + + <listitem><para>Instead of creating a transient scope unit to + run the container in, simply register the service or scope + unit <command>systemd-nspawn</command> has been invoked in + with + <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + This has no effect if <option>--register=no</option> is used. + This switch should be used if + <command>systemd-nspawn</command> is invoked from within a + service unit, and the service unit's sole purpose is to run a + single <command>systemd-nspawn</command> container. This + option is not available if run from a user + session.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--personality=</option></term> + + <listitem><para>Control the architecture ("personality") + reported by + <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> + in the container. Currently, only <literal>x86</literal> and + <literal>x86-64</literal> are supported. This is useful when + running a 32-bit container on a 64-bit host. If this setting + is not used, the personality reported in the container is the + same as the one reported on the host.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-q</option></term> + <term><option>--quiet</option></term> + + <listitem><para>Turns off any status output by the tool + itself. When this switch is used, the only output from nspawn + will be the console output of the container OS + itself.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--volatile</option><replaceable>=MODE</replaceable></term> + + <listitem><para>Boots the container in volatile mode. When no + mode parameter is passed or when mode is specified as + <literal>yes</literal> full volatile mode is enabled. This + means the root directory is mounted as mostly unpopulated + <literal>tmpfs</literal> instance, and + <filename>/usr</filename> from the OS tree is mounted into it, + read-only (the system thus starts up with read-only OS + resources, but pristine state and configuration, any changes + to the either are lost on shutdown). When the mode parameter + is specified as <literal>state</literal> the OS tree is + mounted read-only, but <filename>/var</filename> is mounted as + <literal>tmpfs</literal> instance into it (the system thus + starts up with read-only OS resources and configuration, but + pristine state, any changes to the latter are lost on + shutdown). When the mode parameter is specified as + <literal>no</literal> (the default) the whole OS tree is made + available writable.</para> + + <para>Note that setting this to <literal>yes</literal> or + <literal>state</literal> will only work correctly with + operating systems in the container that can boot up with only + <filename>/usr</filename> mounted, and are able to populate + <filename>/var</filename> automatically, as + needed.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Download a Fedora image and start a shell in it</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> -<para>This downloads an image using <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and opens a shell in it.</para> - </example> + <para>This downloads an image using + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and opens a shell in it.</para> + </example> - <example> - <title>Build and boot a minimal Fedora distribution in a container</title> + <example> + <title>Build and boot a minimal Fedora distribution in a container</title> - <programlisting># dnf -y --releasever=21 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd dnf fedora-release vim-minimal + <programlisting># dnf -y --releasever=21 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd dnf fedora-release vim-minimal # systemd-nspawn -bD /srv/mycontainer</programlisting> - <para>This installs a minimal Fedora distribution into - the directory <filename noindex='true'>/srv/mycontainer/</filename> and - then boots an OS in a namespace container in - it.</para> - </example> + <para>This installs a minimal Fedora distribution into the + directory <filename noindex='true'>/srv/mycontainer/</filename> + and then boots an OS in a namespace container in it.</para> + </example> - <example> - <title>Spawn a shell in a container of a minimal Debian unstable distribution</title> + <example> + <title>Spawn a shell in a container of a minimal Debian unstable distribution</title> - <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/ + <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/ # systemd-nspawn -D ~/debian-tree/</programlisting> - <para>This installs a minimal Debian unstable - distribution into the directory - <filename>~/debian-tree/</filename> and then spawns a - shell in a namespace container in it.</para> - </example> + <para>This installs a minimal Debian unstable distribution into + the directory <filename>~/debian-tree/</filename> and then + spawns a shell in a namespace container in it.</para> + </example> - <example> - <title>Boot a minimal Arch Linux distribution in a container</title> + <example> + <title>Boot a minimal Arch Linux distribution in a container</title> - <programlisting># pacstrap -c -d ~/arch-tree/ base + <programlisting># pacstrap -c -d ~/arch-tree/ base # systemd-nspawn -bD ~/arch-tree/</programlisting> - <para>This installs a mimimal Arch Linux distribution into - the directory <filename>~/arch-tree/</filename> and then - boots an OS in a namespace container in it.</para> - </example> + <para>This installs a mimimal Arch Linux distribution into the + directory <filename>~/arch-tree/</filename> and then boots an OS + in a namespace container in it.</para> + </example> - <example> - <title>Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system</title> + <example> + <title>Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system</title> - <programlisting># systemd-nspawn -D / -xb</programlisting> + <programlisting># systemd-nspawn -D / -xb</programlisting> - <para>This runs a copy of the host system in a - <literal>btrfs</literal> snapshot which is - removed immediately when the container - exits. All file system changes made during - runtime will be lost on shutdown, - hence.</para> - </example> + <para>This runs a copy of the host system in a + <literal>btrfs</literal> snapshot which is removed immediately + when the container exits. All file system changes made during + runtime will be lost on shutdown, hence.</para> + </example> - <example> - <title>Run a container with SELinux sandbox security contexts</title> + <example> + <title>Run a container with SELinux sandbox security contexts</title> - <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container + <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container # systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh</programlisting> - </example> - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>The exit code of the program executed in the - container is returned.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + </example> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>The exit code of the program executed in the container is + returned.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-path.xml b/man/systemd-path.xml index fc01d5edd4..dfc75ee0ff 100644 --- a/man/systemd-path.xml +++ b/man/systemd-path.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,90 +22,86 @@ --> <refentry id="systemd-path" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-path</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-path</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-path</refname> - <refpurpose>List and query system and user paths</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-path <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">NAME</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-path</command> may be used to - query system and user paths. The tool makes many of - the paths described in - <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry> - queriable.</para> - - <para>When invoked without arguments a list of known - paths and their current values is shown. When at least - one argument is passed the path with this is name is - queried and its value shown. The variables whose name - begins with <literal>search-</literal> don't refer to - individual paths, but instead a to a list of - colon-separated search paths, in their order of - precedence.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--suffix=</option></term> - - <listitem><para>The printed paths are - suffixed by the specified - string.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-path</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-path</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-path</refname> + <refpurpose>List and query system and user paths</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-path <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">NAME</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-path</command> may be used to query system + and user paths. The tool makes many of the paths described in + <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry> + queriable.</para> + + <para>When invoked without arguments a list of known paths and + their current values is shown. When at least one argument is + passed the path with this is name is queried and its value shown. + The variables whose name begins with <literal>search-</literal> + don't refer to individual paths, but instead a to a list of + colon-separated search paths, in their order of precedence.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--suffix=</option></term> + + <listitem><para>The printed paths are suffixed by the + specified string.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>file-hierarchy</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-quotacheck.service.xml b/man/systemd-quotacheck.service.xml index ff04e582de..2179f11e95 100644 --- a/man/systemd-quotacheck.service.xml +++ b/man/systemd-quotacheck.service.xml @@ -21,82 +21,74 @@ --> <refentry id="systemd-quotacheck.service" conditional='ENABLE_QUOTACHECK'> - <refentryinfo> - <title>systemd-quotacheck.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-quotacheck.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-quotacheck.service</refname> - <refname>systemd-quotacheck</refname> - <refpurpose>File system quota checker logic</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-quotacheck.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-quotacheck</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-quotacheck.service</filename> - is a service responsible for file system quota - checks. It is run once at boot after all necessary - file systems are mounted. It is pulled in only if at - least one file system has quotas enabled.</para> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-quotacheck</filename> understands - one kernel command line parameter:</para> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>quotacheck.mode=</varname></term> - - <listitem><para>One of - <literal>auto</literal>, - <literal>force</literal>, - <literal>skip</literal>. Controls the - mode of operation. The default is - <literal>auto</literal>, and ensures - that file system quota checks are done - when the file system quota checker - deems them - necessary. <literal>force</literal> - unconditionally results in full file - system quota - checks. <literal>skip</literal> skips - any file system quota - checks.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>quotacheck</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fsck@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-quotacheck.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-quotacheck.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-quotacheck.service</refname> + <refname>systemd-quotacheck</refname> + <refpurpose>File system quota checker logic</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-quotacheck.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-quotacheck</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-quotacheck.service</filename> is a service + responsible for file system quota checks. It is run once at boot + after all necessary file systems are mounted. It is pulled in only + if at least one file system has quotas enabled.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-quotacheck</filename> understands one + kernel command line parameter:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>quotacheck.mode=</varname></term> + + <listitem><para>One of <literal>auto</literal>, + <literal>force</literal>, <literal>skip</literal>. Controls + the mode of operation. The default is <literal>auto</literal>, + and ensures that file system quota checks are done when the + file system quota checker deems them necessary. + <literal>force</literal> unconditionally results in full file + system quota checks. <literal>skip</literal> skips any file + system quota checks.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>quotacheck</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fsck@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-random-seed.service.xml b/man/systemd-random-seed.service.xml index e5cd03719f..8c836688fe 100644 --- a/man/systemd-random-seed.service.xml +++ b/man/systemd-random-seed.service.xml @@ -21,55 +21,55 @@ --> <refentry id="systemd-random-seed.service" conditional='ENABLE_RANDOMSEED'> - <refentryinfo> - <title>systemd-random-seed.service</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-random-seed.service</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-random-seed.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-random-seed.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-random-seed.service</refname> - <refname>systemd-random-seed</refname> - <refpurpose>Load and save the system random seed at boot and shutdown</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-random-seed.service</refname> + <refname>systemd-random-seed</refname> + <refpurpose>Load and save the system random seed at boot and shutdown</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>systemd-random-seed.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-random-seed</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>systemd-random-seed.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-random-seed</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-random-seed.service</filename> - is a service that restores the random seed of the - system at early-boot and saves it at shutdown. See - <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> - for details. Saving/restoring the random seed across - boots increases the amount of available entropy early - at boot. On disk the random seed is stored in - <filename>/var/lib/systemd/random-seed</filename>.</para> - </refsect1> + <para><filename>systemd-random-seed.service</filename> is a + service that restores the random seed of the system at early-boot + and saves it at shutdown. See + <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> + for details. Saving/restoring the random seed across boots + increases the amount of available entropy early at boot. On disk + the random seed is stored in + <filename>/var/lib/systemd/random-seed</filename>.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-remount-fs.service.xml b/man/systemd-remount-fs.service.xml index cf04713a00..7b88ac3f3c 100644 --- a/man/systemd-remount-fs.service.xml +++ b/man/systemd-remount-fs.service.xml @@ -21,73 +21,68 @@ --> <refentry id="systemd-remount-fs.service"> - <refentryinfo> - <title>systemd-remount-fs.service</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-remount-fs.service</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-remount-fs.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-remount-fs.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-remount-fs.service</refname> - <refname>systemd-remount-fs</refname> - <refpurpose>Remount root and kernel file systems</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-remount-fs.service</refname> + <refname>systemd-remount-fs</refname> + <refpurpose>Remount root and kernel file systems</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>systemd-remount-fs.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-remount-fs</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>systemd-remount-fs.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-remount-fs</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-remount-fs.service</filename> - is an early-boot service that applies mount options - listed in - <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> - to the root file system, the <filename>/usr</filename> - file system and the kernel API file systems. This is - required so that the mount options of these file - systems -- which are pre-mounted by the kernel, the - initial RAM disk, container environments or system - manager code -- are updated to those listed in - <filename>/etc/fstab</filename>. This service ignores - normal file systems and only changes the root file - system (i.e. <filename>/</filename>), - <filename>/usr</filename> and the virtual kernel API - file systems such as <filename>/proc</filename>, - <filename>/sys</filename> or - <filename>/dev</filename>. This service executes no - operation if <filename>/etc/fstab</filename> does not - exist or lists no entries for the mentioned file - systems.</para> + <para><filename>systemd-remount-fs.service</filename> is an + early-boot service that applies mount options listed in + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + to the root file system, the <filename>/usr</filename> file system + and the kernel API file systems. This is required so that the + mount options of these file systems -- which are pre-mounted by + the kernel, the initial RAM disk, container environments or system + manager code -- are updated to those listed in + <filename>/etc/fstab</filename>. This service ignores normal file + systems and only changes the root file system (i.e. + <filename>/</filename>), <filename>/usr</filename> and the virtual + kernel API file systems such as <filename>/proc</filename>, + <filename>/sys</filename> or <filename>/dev</filename>. This + service executes no operation if <filename>/etc/fstab</filename> + does not exist or lists no entries for the mentioned file + systems.</para> - <para>For a longer discussion of kernel API file - systems see <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API - File Systems</ulink>.</para> - </refsect1> + <para>For a longer discussion of kernel API file systems see + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API + File Systems</ulink>.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index c44b10c472..89ec5f8b19 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,69 +23,68 @@ <refentry id="systemd-resolved.service" conditional='ENABLE_RESOLVED'> - <refentryinfo> - <title>systemd-resolved.service</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-resolved.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-resolved.service</refname> - <refname>systemd-resolved</refname> - <refpurpose>Network Name Resolution manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-resolved.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-resolved</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-resolved</command> is a system - service that manages network name resolution. It - implements a caching DNS stub resolver and an LLMNR - resolver and responder. It also generates - <filename>/run/systemd/resolve/resolv.conf</filename> - for compatibility which may be symlinked from - <filename>/etc/resolv.conf</filename>.</para> - - <para>The DNS servers contacted are determined from - the global settings in - <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - the per-link static settings in - <filename>.network</filename> files, and the per-link - dynamic settings received over DHCP. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more details.</para> - - <para>Note that <filename>/run/systemd/resolve/resolv.conf</filename> - should not be used directly, but only through a symlink from - <filename>/etc/resolv.conf</filename>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-resolved.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + <email>teg@jklm.no</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-resolved.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-resolved.service</refname> + <refname>systemd-resolved</refname> + <refpurpose>Network Name Resolution manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-resolved.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-resolved</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-resolved</command> is a system service that + manages network name resolution. It implements a caching DNS stub + resolver and an LLMNR resolver and responder. It also generates + <filename>/run/systemd/resolve/resolv.conf</filename> for + compatibility which may be symlinked from + <filename>/etc/resolv.conf</filename>.</para> + + <para>The DNS servers contacted are determined from the global + settings in + <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + the per-link static settings in <filename>.network</filename> + files, and the per-link dynamic settings received over DHCP. See + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more details.</para> + + <para>Note that + <filename>/run/systemd/resolve/resolv.conf</filename> should not + be used directly, but only through a symlink from + <filename>/etc/resolv.conf</filename>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-rfkill@.service.xml b/man/systemd-rfkill@.service.xml index 987bbaab7e..709b09d818 100644 --- a/man/systemd-rfkill@.service.xml +++ b/man/systemd-rfkill@.service.xml @@ -21,72 +21,68 @@ --> <refentry id="systemd-rfkill@.service" conditional='ENABLE_RFKILL'> - <refentryinfo> - <title>systemd-rfkill@.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-rfkill@.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-rfkill@.service</refname> - <refname>systemd-rfkill</refname> - <refpurpose>Load and save the RF kill switch state at boot and shutdown</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-rfkill@.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-rfkill</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-rfkill@.service</filename> is - a service that restores the RF kill switch state at - early boot and saves it at shutdown. On disk, the RF - kill switch state is stored in - <filename>/var/lib/systemd/rfkill/</filename>.</para> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para><filename>systemd-rfkill</filename> understands - the following kernel command line parameter:</para> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>systemd.restore_state=</varname></term> - - <listitem><para>Takes a boolean - argument. Defaults to - <literal>1</literal>. If - <literal>0</literal>, does not restore - the rfkill settings on boot. However, - settings will still be stored on shutdown. - </para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-rfkill@.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-rfkill@.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-rfkill@.service</refname> + <refname>systemd-rfkill</refname> + <refpurpose>Load and save the RF kill switch state at boot and shutdown</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-rfkill@.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-rfkill</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-rfkill@.service</filename> is a service + that restores the RF kill switch state at early boot and saves it + at shutdown. On disk, the RF kill switch state is stored in + <filename>/var/lib/systemd/rfkill/</filename>.</para> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para><filename>systemd-rfkill</filename> understands the + following kernel command line parameter:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>systemd.restore_state=</varname></term> + + <listitem><para>Takes a boolean argument. Defaults to + <literal>1</literal>. If <literal>0</literal>, does not + restore the rfkill settings on boot. However, settings will + still be stored on shutdown. </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-shutdownd.service.xml b/man/systemd-shutdownd.service.xml index c1b8ef7a49..756949ce55 100644 --- a/man/systemd-shutdownd.service.xml +++ b/man/systemd-shutdownd.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,55 +23,55 @@ <refentry id="systemd-shutdownd.service"> - <refentryinfo> - <title>systemd-shutdownd.service</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-shutdownd.service</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-shutdownd.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-shutdownd.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-shutdownd.service</refname> - <refname>systemd-shutdownd.socket</refname> - <refname>systemd-shutdownd</refname> - <refpurpose>Scheduled shutdown service</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-shutdownd.service</refname> + <refname>systemd-shutdownd.socket</refname> + <refname>systemd-shutdownd</refname> + <refpurpose>Scheduled shutdown service</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>systemd-shutdownd.service</filename></para> - <para><filename>systemd-shutdownd.socket</filename></para> - <para><filename>/usr/lib/systemd/systemd-shutdownd</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>systemd-shutdownd.service</filename></para> + <para><filename>systemd-shutdownd.socket</filename></para> + <para><filename>/usr/lib/systemd/systemd-shutdownd</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-shutdownd.service</filename> is a - system service that implements scheduled shutdowns, as - exposed by - <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - <filename>systemd-shutdownd.service</filename> is automatically activated on request and terminates - itself when it is unused.</para> - </refsect1> + <para><filename>systemd-shutdownd.service</filename> is a system + service that implements scheduled shutdowns, as exposed by + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + <filename>systemd-shutdownd.service</filename> is automatically + activated on request and terminates itself when it is + unused.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-socket-proxyd.xml b/man/systemd-socket-proxyd.xml index ab80a2b4ba..1c78b656e1 100644 --- a/man/systemd-socket-proxyd.xml +++ b/man/systemd-socket-proxyd.xml @@ -21,96 +21,94 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> <refentry id="systemd-socket-proxyd" - xmlns:xi="http://www.w3.org/2001/XInclude"> + xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>systemd-socket-proxyd</title> - <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>David</firstname> - <surname>Strauss</surname> - <email>david@davidstrauss.net</email> - </author> - </authorgroup> - </refentryinfo> - <refmeta> - <refentrytitle>systemd-socket-proxyd</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - <refnamediv> - <refname>systemd-socket-proxyd</refname> - <refpurpose>Bidirectionally proxy local sockets to another (possibly remote) socket.</refpurpose> - </refnamediv> - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-socket-proxyd</command> - <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg> - <arg choice="plain"><replaceable>HOST</replaceable>:<replaceable>PORT</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>systemd-socket-proxyd</command> - <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg> - <arg choice="plain"><replaceable>UNIX-DOMAIN-SOCKET-PATH</replaceable> - </arg> - </cmdsynopsis> - </refsynopsisdiv> - <refsect1> - <title>Description</title> - <para> - <command>systemd-socket-proxyd</command> is a generic - socket-activated network socket forwarder proxy daemon - for IPv4, IPv6 and UNIX stream sockets. It may be used - to bi-directionally forward traffic from a local listening socket to a - local or remote destination socket.</para> + <refentryinfo> + <title>systemd-socket-proxyd</title> + <productname>systemd</productname> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>David</firstname> + <surname>Strauss</surname> + <email>david@davidstrauss.net</email> + </author> + </authorgroup> + </refentryinfo> + <refmeta> + <refentrytitle>systemd-socket-proxyd</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + <refnamediv> + <refname>systemd-socket-proxyd</refname> + <refpurpose>Bidirectionally proxy local sockets to another (possibly remote) socket.</refpurpose> + </refnamediv> + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-socket-proxyd</command> + <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg> + <arg choice="plain"><replaceable>HOST</replaceable>:<replaceable>PORT</replaceable></arg> + </cmdsynopsis> + <cmdsynopsis> + <command>systemd-socket-proxyd</command> + <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg> + <arg choice="plain"><replaceable>UNIX-DOMAIN-SOCKET-PATH</replaceable> + </arg> + </cmdsynopsis> + </refsynopsisdiv> + <refsect1> + <title>Description</title> + <para> + <command>systemd-socket-proxyd</command> is a generic + socket-activated network socket forwarder proxy daemon for IPv4, + IPv6 and UNIX stream sockets. It may be used to bi-directionally + forward traffic from a local listening socket to a local or remote + destination socket.</para> - <para>One use of this tool is to provide - socket activation support for services that do not - natively support socket activation. On behalf of the - service to activate, the proxy inherits the socket - from systemd, accepts each client connection, opens a - connection to a configured server for each client, and - then bidirectionally forwards data between the - two.</para> - <para>This utility's behavior is similar to - <citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - The main differences for <command>systemd-socket-proxyd</command> - are support for socket activation with - <literal>Accept=false</literal> and an event-driven - design that scales better with the number of - connections.</para> - </refsect1> - <refsect1> - <title>Options</title> - <para>The following options are understood:</para> - <variablelist> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - <refsect1> - <title>Exit status</title> - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - <refsect1> - <title>Examples</title> - <refsect2> - <title>Simple Example</title> - <para>Use two services with a dependency - and no namespace isolation.</para> - <example> - <title>proxy-to-nginx.socket</title> - <programlisting><![CDATA[[Socket] + <para>One use of this tool is to provide socket activation support + for services that do not natively support socket activation. On + behalf of the service to activate, the proxy inherits the socket + from systemd, accepts each client connection, opens a connection + to a configured server for each client, and then bidirectionally + forwards data between the two.</para> + <para>This utility's behavior is similar to + <citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + The main differences for <command>systemd-socket-proxyd</command> + are support for socket activation with + <literal>Accept=false</literal> and an event-driven + design that scales better with the number of + connections.</para> + </refsect1> + <refsect1> + <title>Options</title> + <para>The following options are understood:</para> + <variablelist> + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + </refsect1> + <refsect1> + <title>Exit status</title> + <para>On success, 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + <refsect1> + <title>Examples</title> + <refsect2> + <title>Simple Example</title> + <para>Use two services with a dependency and no namespace + isolation.</para> + <example> + <title>proxy-to-nginx.socket</title> + <programlisting><![CDATA[[Socket] ListenStream=80 [Install] WantedBy=sockets.target]]></programlisting> - </example> - <example> - <title>proxy-to-nginx.service</title> - <programlisting><![CDATA[[Unit] + </example> + <example> + <title>proxy-to-nginx.service</title> + <programlisting><![CDATA[[Unit] Requires=nginx.service After=nginx.service @@ -118,43 +116,41 @@ After=nginx.service ExecStart=/usr/lib/systemd/systemd-socket-proxyd /tmp/nginx.sock PrivateTmp=yes PrivateNetwork=yes]]></programlisting> - </example> - <example> - <title>nginx.conf</title> - <programlisting> + </example> + <example> + <title>nginx.conf</title> + <programlisting> <![CDATA[[...] server { listen unix:/tmp/nginx.sock; [...]]]> </programlisting> - </example> - <example> - <title>Enabling the proxy</title> - <programlisting><![CDATA[# systemctl enable proxy-to-nginx.socket + </example> + <example> + <title>Enabling the proxy</title> + <programlisting><![CDATA[# systemctl enable proxy-to-nginx.socket # systemctl start proxy-to-nginx.socket $ curl http://localhost:80/]]></programlisting> - </example> - </refsect2> - <refsect2> - <title>Namespace Example</title> - <para>Similar as above, but runs the socket - proxy and the main service in the same private - namespace, assuming that - <filename>nginx.service</filename> has - <varname>PrivateTmp=</varname> and - <varname>PrivateNetwork=</varname> set, - too.</para> - <example> - <title>proxy-to-nginx.socket</title> - <programlisting><![CDATA[[Socket] + </example> + </refsect2> + <refsect2> + <title>Namespace Example</title> + <para>Similar as above, but runs the socket proxy and the main + service in the same private namespace, assuming that + <filename>nginx.service</filename> has + <varname>PrivateTmp=</varname> and + <varname>PrivateNetwork=</varname> set, too.</para> + <example> + <title>proxy-to-nginx.socket</title> + <programlisting><![CDATA[[Socket] ListenStream=80 [Install] WantedBy=sockets.target]]></programlisting> - </example> - <example> - <title>proxy-to-nginx.service</title> - <programlisting><![CDATA[[Unit] + </example> + <example> + <title>proxy-to-nginx.service</title> + <programlisting><![CDATA[[Unit] Requires=nginx.service After=nginx.service JoinsNamespaceOf=nginx.service @@ -163,33 +159,33 @@ JoinsNamespaceOf=nginx.service ExecStart=/usr/lib/systemd/systemd-socket-proxyd 127.0.0.1:8080 PrivateTmp=yes PrivateNetwork=yes]]></programlisting> - </example> - <example> - <title>nginx.conf</title> - <programlisting><![CDATA[[...] + </example> + <example> + <title>nginx.conf</title> + <programlisting><![CDATA[[...] server { listen 8080; listen unix:/tmp/nginx.sock; [...]]]></programlisting> - </example> - <example> - <title>Enabling the proxy</title> - <programlisting><![CDATA[# systemctl enable proxy-to-nginx.socket + </example> + <example> + <title>Enabling the proxy</title> + <programlisting><![CDATA[# systemctl enable proxy-to-nginx.socket # systemctl start proxy-to-nginx.socket $ curl http://localhost:80/]]></programlisting> - </example> - </refsect2> - </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>nginx</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>curl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + </example> + </refsect2> + </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>socat</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nginx</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>curl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-suspend.service.xml b/man/systemd-suspend.service.xml index 375c25576d..a8beb86f4d 100644 --- a/man/systemd-suspend.service.xml +++ b/man/systemd-suspend.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,134 +23,124 @@ --> <refentry id="systemd-suspend.service" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-suspend.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-suspend.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-suspend.service</refname> - <refname>systemd-hibernate.service</refname> - <refname>systemd-hybrid-sleep.service</refname> - <refname>systemd-sleep</refname> - <refpurpose>System sleep state logic</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-suspend.service</filename></para> - <para><filename>systemd-hibernate.service</filename></para> - <para><filename>systemd-hybrid-sleep.service</filename></para> - <para><filename>/usr/lib/systemd/system-sleep</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-suspend.service</filename> is - a system service that is pulled in by - <filename>suspend.target</filename> and is responsible - for the actual system suspend. Similarly, - <filename>systemd-hibernate.service</filename> is - pulled in by <filename>hibernate.target</filename> to - execute the actual hibernation. Finally, - <filename>systemd-hybrid-sleep.service</filename> is - pulled in by <filename>hybrid-sleep.target</filename> - to execute hybrid hibernation with system - suspend.</para> - - <para>Immediately before entering system suspend - and/or hibernation - <filename>systemd-suspend.service</filename> (and the - other mentioned units, respectively) will run all - executables in - <filename>/usr/lib/systemd/system-sleep/</filename> - and pass two arguments to them. The first argument - will be <literal>pre</literal>, the second either - <literal>suspend</literal>, - <literal>hibernate</literal>, or - <literal>hybrid-sleep</literal> depending on the - chosen action. Immediately after leaving system - suspend and/or hibernation the same executables are run, - but the first argument is now - <literal>post</literal>. All executables in this - directory are executed in parallel, and execution of - the action is not continued until all executables - have finished.</para> - - <para>Note that scripts or binaries dropped in - <filename>/usr/lib/systemd/system-sleep/</filename> - are intended for local use only and should be - considered hacks. If applications want to be notified - of system suspend/hibernation and resume, there are - much nicer interfaces available.</para> - - <para>Note that - <filename>systemd-suspend.service</filename>, - <filename>systemd-hibernate.service</filename>, and - <filename>systemd-hybrid-sleep.service</filename> - should never be executed directly. Instead, trigger - system sleep states with a command such as - <literal>systemctl suspend</literal> or - similar.</para> - - <para>Internally, this service will echo a string like - <literal>mem</literal> into - <filename>/sys/power/state</filename>, to trigger the - actual system suspend. What exactly is written - where can be configured in the <literal>[Sleep]</literal> - section of <filename>/etc/systemd/sleep.conf</filename> or a - <filename>sleep.conf.d</filename> file. - See <citerefentry><refentrytitle>systemd-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para><command>systemd-sleep</command> understands the - following commands:</para> - - <variablelist> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - - <varlistentry> - <term><option>suspend</option></term> - <term><option>hibernate</option></term> - <term><option>hybrid-sleep</option></term> - - <listitem><para>Suspend, hibernate, or - put the system to hybrid sleep.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-halt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-suspend.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-suspend.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-suspend.service</refname> + <refname>systemd-hibernate.service</refname> + <refname>systemd-hybrid-sleep.service</refname> + <refname>systemd-sleep</refname> + <refpurpose>System sleep state logic</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-suspend.service</filename></para> + <para><filename>systemd-hibernate.service</filename></para> + <para><filename>systemd-hybrid-sleep.service</filename></para> + <para><filename>/usr/lib/systemd/system-sleep</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-suspend.service</filename> is a system + service that is pulled in by <filename>suspend.target</filename> + and is responsible for the actual system suspend. Similarly, + <filename>systemd-hibernate.service</filename> is pulled in by + <filename>hibernate.target</filename> to execute the actual + hibernation. Finally, + <filename>systemd-hybrid-sleep.service</filename> is pulled in by + <filename>hybrid-sleep.target</filename> to execute hybrid + hibernation with system suspend.</para> + + <para>Immediately before entering system suspend and/or + hibernation <filename>systemd-suspend.service</filename> (and the + other mentioned units, respectively) will run all executables in + <filename>/usr/lib/systemd/system-sleep/</filename> and pass two + arguments to them. The first argument will be + <literal>pre</literal>, the second either + <literal>suspend</literal>, <literal>hibernate</literal>, or + <literal>hybrid-sleep</literal> depending on the chosen action. + Immediately after leaving system suspend and/or hibernation the + same executables are run, but the first argument is now + <literal>post</literal>. All executables in this directory are + executed in parallel, and execution of the action is not continued + until all executables have finished.</para> + + <para>Note that scripts or binaries dropped in + <filename>/usr/lib/systemd/system-sleep/</filename> are intended + for local use only and should be considered hacks. If applications + want to be notified of system suspend/hibernation and resume, + there are much nicer interfaces available.</para> + + <para>Note that + <filename>systemd-suspend.service</filename>, + <filename>systemd-hibernate.service</filename>, and + <filename>systemd-hybrid-sleep.service</filename> + should never be executed directly. Instead, trigger system sleep + states with a command such as <literal>systemctl suspend</literal> + or similar.</para> + + <para>Internally, this service will echo a string like + <literal>mem</literal> into <filename>/sys/power/state</filename>, + to trigger the actual system suspend. What exactly is written + where can be configured in the <literal>[Sleep]</literal> section + of <filename>/etc/systemd/sleep.conf</filename> or a + <filename>sleep.conf.d</filename> file. See + <citerefentry><refentrytitle>systemd-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para><command>systemd-sleep</command> understands the + following commands:</para> + + <variablelist> + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + + <varlistentry> + <term><option>suspend</option></term> + <term><option>hibernate</option></term> + <term><option>hybrid-sleep</option></term> + + <listitem><para>Suspend, hibernate, or put the system to + hybrid sleep.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-halt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-sysctl.service.xml b/man/systemd-sysctl.service.xml index a9a4765630..f35a18a4d4 100644 --- a/man/systemd-sysctl.service.xml +++ b/man/systemd-sysctl.service.xml @@ -21,57 +21,56 @@ --> <refentry id="systemd-sysctl.service"> - <refentryinfo> - <title>systemd-sysctl.service</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-sysctl.service</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-sysctl.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-sysctl.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-sysctl.service</refname> - <refname>systemd-sysctl</refname> - <refpurpose>Configure kernel parameters at boot</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-sysctl.service</refname> + <refname>systemd-sysctl</refname> + <refpurpose>Configure kernel parameters at boot</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>systemd-sysctl.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-sysctl</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>systemd-sysctl.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-sysctl</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-sysctl.service</filename> is - an early-boot service that configures - <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - kernel parameters.</para> + <para><filename>systemd-sysctl.service</filename> is an early-boot + service that configures + <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + kernel parameters.</para> - <para>See - <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about the configuration of this - service.</para> - </refsect1> + <para>See + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the configuration of this service.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + </para> + </refsect1> </refentry> diff --git a/man/systemd-system-update-generator.xml b/man/systemd-system-update-generator.xml index 18a23ed7fc..3eec1d7b93 100644 --- a/man/systemd-system-update-generator.xml +++ b/man/systemd-system-update-generator.xml @@ -21,59 +21,58 @@ --> <refentry id="systemd-system-update-generator"> - <refentryinfo> - <title>systemd-system-update-generator</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-system-update-generator</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-system-update-generator</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-system-update-generator</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-system-update-generator</refname> - <refpurpose>Generator for redirecting boot to offline update mode</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-system-update-generator</refname> + <refpurpose>Generator for redirecting boot to offline update mode</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>/usr/lib/systemd/system-generators/systemd-system-update-generator</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>/usr/lib/systemd/system-generators/systemd-system-update-generator</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-system-update-generator</filename> - is a generator that automatically redirects the boot - process to <filename>system-update.target</filename> - if <filename>/system-update</filename> exists. This is - required to implement the logic explained in the - <ulink - url="http://freedesktop.org/wiki/Software/systemd/SystemUpdates">System - Updates Specification</ulink>. - </para> + <para><filename>systemd-system-update-generator</filename> is a + generator that automatically redirects the boot process to + <filename>system-update.target</filename> if + <filename>/system-update</filename> exists. This is required to + implement the logic explained in the <ulink + url="http://freedesktop.org/wiki/Software/systemd/SystemUpdates">System + Updates Specification</ulink>. + </para> - <para><filename>systemd-system-update-generator</filename> - implements the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator - specification</ulink>.</para> - </refsect1> + <para><filename>systemd-system-update-generator</filename> + implements the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/Generators">generator + specification</ulink>.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml index dfb180cc54..7137fdb07d 100644 --- a/man/systemd-system.conf.xml +++ b/man/systemd-system.conf.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,421 +23,334 @@ --> <refentry id="systemd-system.conf" - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>systemd-system.conf</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-system.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-system.conf</refname> - <refname>system.conf.d</refname> - <refname>systemd-user.conf</refname> - <refname>user.conf.d</refname> - <refpurpose>System and session service manager configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/system.conf</filename></para> - <para><filename>/etc/systemd/system.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/system.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/system.conf.d/*.conf</filename></para> - <para><filename>/etc/systemd/user.conf</filename></para> - <para><filename>/etc/systemd/user.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/user.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/user.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>When run as a system instance, systemd interprets the - configuration file <filename>system.conf</filename> and the - files in <filename>system.conf.d</filename> directories; when - run as a user instance, systemd interprets the configuration - file <filename>user.conf</filename> and the files in - <filename>user.conf.d</filename> directories. These - configuration files contain a few settings controlling - basic manager operations.</para> - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - <xi:include href="standard-conf.xml" xpointer="conf" /> - - <refsect1> - <title>Options</title> - - <para>All options are configured in the - <literal>[Manager]</literal> section:</para> - - <variablelist class='systemd-directives'> - - <varlistentry> - <term><varname>LogLevel=</varname></term> - <term><varname>LogTarget=</varname></term> - <term><varname>LogColor=</varname></term> - <term><varname>LogLocation=</varname></term> - <term><varname>DumpCore=yes</varname></term> - <term><varname>CrashShell=no</varname></term> - <term><varname>ShowStatus=yes</varname></term> - <term><varname>CrashChVT=1</varname></term> - <term><varname>DefaultStandardOutput=journal</varname></term> - <term><varname>DefaultStandardError=inherit</varname></term> - - <listitem><para>Configures various - parameters of basic manager - operation. These options may be - overridden by the respective command - line arguments. See - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for details about these command line - arguments.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>CPUAffinity=</varname></term> - - <listitem><para>Configures the initial - CPU affinity for the init - process. Takes a space-separated list - of CPU indices.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>JoinControllers=cpu,cpuacct net_cls,netprio</varname></term> - - <listitem><para>Configures controllers - that shall be mounted in a single - hierarchy. By default, systemd will - mount all controllers which are - enabled in the kernel in individual - hierarchies, with the exception of - those listed in this setting. Takes a - space-separated list of comma-separated - controller names, in order - to allow multiple joined - hierarchies. Defaults to - 'cpu,cpuacct'. Pass an empty string to - ensure that systemd mounts all - controllers in separate - hierarchies.</para> - - <para>Note that this option is only - applied once, at very early boot. If - you use an initial RAM disk (initrd) - that uses systemd, it might hence be - necessary to rebuild the initrd if - this option is changed, and make sure - the new configuration file is included - in it. Otherwise, the initrd might - mount the controller hierarchies in a - different configuration than intended, - and the main system cannot remount - them anymore.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RuntimeWatchdogSec=</varname></term> - <term><varname>ShutdownWatchdogSec=</varname></term> - - <listitem><para>Configure the hardware - watchdog at runtime and at - reboot. Takes a timeout value in - seconds (or in other time units if - suffixed with <literal>ms</literal>, - <literal>min</literal>, - <literal>h</literal>, - <literal>d</literal>, - <literal>w</literal>). If - <varname>RuntimeWatchdogSec=</varname> - is set to a non-zero value, the - watchdog hardware - (<filename>/dev/watchdog</filename>) - will be programmed to automatically - reboot the system if it is not - contacted within the specified timeout - interval. The system manager will - ensure to contact it at least once in - half the specified timeout - interval. This feature requires a - hardware watchdog device to be - present, as it is commonly the case in - embedded and server systems. Not all - hardware watchdogs allow configuration - of the reboot timeout, in which case - the closest available timeout is - picked. <varname>ShutdownWatchdogSec=</varname> - may be used to configure the hardware - watchdog when the system is asked to - reboot. It works as a safety net to - ensure that the reboot takes place - even if a clean reboot attempt times - out. By default - <varname>RuntimeWatchdogSec=</varname> - defaults to 0 (off), and - <varname>ShutdownWatchdogSec=</varname> - to 10min. These settings have no - effect if a hardware watchdog is not - available.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>CapabilityBoundingSet=</varname></term> - - <listitem><para>Controls which - capabilities to include in the - capability bounding set for PID 1 and - its children. 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><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - Capabilities listed will be included - in the bounding set, all others are - removed. If the list of capabilities - is prefixed with ~, 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. The - capability bounding set may also be - individually configured for units - using the - <varname>CapabilityBoundingSet=</varname> - directive for units, but note that - capabilities dropped for PID 1 cannot - be regained in individual units, they - are lost for good.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SystemCallArchitectures=</varname></term> - - <listitem><para>Takes a - space-separated list of architecture - identifiers. Selects from which - architectures system calls may be - invoked on this system. This may be - used as an effective way to disable - invocation of non-native binaries - system-wide, for example to prohibit - execution of 32-bit x86 binaries on - 64-bit x86-64 systems. This option - operates system-wide, and acts - similar to the - <varname>SystemCallArchitectures=</varname> - setting of unit files, see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. This setting defaults to - the empty list, in which case no - filtering of system calls based on - architecture is applied. Known - architecture identifiers are - <literal>x86</literal>, - <literal>x86-64</literal>, - <literal>x32</literal>, - <literal>arm</literal> and the special - identifier - <literal>native</literal>. The latter - implicitly maps to the native - architecture of the system (or more - specifically, the architecture the - system manager was compiled for). Set - this setting to - <literal>native</literal> to prohibit - execution of any non-native - binaries. When a binary executes a - system call of an architecture that is - not listed in this setting, it will be - immediately terminated with the SIGSYS - signal.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TimerSlackNSec=</varname></term> - - <listitem><para>Sets the timer slack - in nanoseconds for PID 1, which is - inherited by all executed processes, - unless overridden individually, for - example with the - <varname>TimerSlackNSec=</varname> - setting in service units (for details - see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>). The - timer slack controls the accuracy of - wake-ups triggered by system - timers. See - <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for more information. Note that in - contrast to most other time span - definitions this parameter takes an - integer value in nano-seconds if no - unit is specified. The usual time - units are understood - too.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultTimerAccuracySec=</varname></term> - - <listitem><para>Sets the default - accuracy of timer units. This controls - the global default for the - <varname>AccuracySec=</varname> - setting of timer units, see - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for - details. <varname>AccuracySec=</varname> - set in individual units override the - global default for the specific - unit. Defaults to 1min. Note that the - accuracy of timer units is also - affected by the configured timer slack - for PID 1, see - <varname>TimerSlackNSec=</varname> - above.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultTimeoutStartSec=</varname></term> - <term><varname>DefaultTimeoutStopSec=</varname></term> - <term><varname>DefaultRestartSec=</varname></term> - - <listitem><para>Configures the default - timeouts for starting and stopping of - units, as well as the default time to - sleep between automatic restarts of - units, as configured per-unit in - <varname>TimeoutStartSec=</varname>, - <varname>TimeoutStopSec=</varname> and - <varname>RestartSec=</varname> (for - services, see - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on the per-unit - settings). For non-service units, - <varname>DefaultTimeoutStartSec=</varname> - sets the default - <varname>TimeoutSec=</varname> value. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultStartLimitInterval=</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>StartLimitBurst=</varname>. See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on the per-service - settings.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultEnvironment=</varname></term> - - <listitem><para>Sets manager - environment variables passed to all - executed processes. Takes a - space-separated list of variable - assignments. See - <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details about environment - variables.</para> - - <para>Example: - - <programlisting>DefaultEnvironment="VAR1=word1 word2" VAR2=word3 "VAR3=word 5 6"</programlisting> - - Sets three variables - <literal>VAR1</literal>, - <literal>VAR2</literal>, - <literal>VAR3</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultCPUAccounting=</varname></term> - <term><varname>DefaultBlockIOAccounting=</varname></term> - <term><varname>DefaultMemoryAccounting=</varname></term> - - <listitem><para>Configure the default - resource accounting settings, as - configured per-unit by - <varname>CPUAccounting=</varname>, - <varname>BlockIOAccounting=</varname> - and - <varname>MemoryAccounting=</varname>. See - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on the per-unit - settings.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultLimitCPU=</varname></term> - <term><varname>DefaultLimitFSIZE=</varname></term> - <term><varname>DefaultLimitDATA=</varname></term> - <term><varname>DefaultLimitSTACK=</varname></term> - <term><varname>DefaultLimitCORE=</varname></term> - <term><varname>DefaultLimitRSS=</varname></term> - <term><varname>DefaultLimitNOFILE=</varname></term> - <term><varname>DefaultLimitAS=</varname></term> - <term><varname>DefaultLimitNPROC=</varname></term> - <term><varname>DefaultLimitMEMLOCK=</varname></term> - <term><varname>DefaultLimitLOCKS=</varname></term> - <term><varname>DefaultLimitSIGPENDING=</varname></term> - <term><varname>DefaultLimitMSGQUEUE=</varname></term> - <term><varname>DefaultLimitNICE=</varname></term> - <term><varname>DefaultLimitRTPRIO=</varname></term> - <term><varname>DefaultLimitRTTIME=</varname></term> - - <listitem><para>These settings control - various default resource limits for - units. See - <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. Use the string - <varname>infinity</varname> to - configure no limit on a specific - resource. These settings may be - overridden in individual units - using the corresponding LimitXXX= - directives. Note that these resource - limits are only defaults for units, - they are not applied to PID 1 - itself.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>systemd-system.conf</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-system.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-system.conf</refname> + <refname>system.conf.d</refname> + <refname>systemd-user.conf</refname> + <refname>user.conf.d</refname> + <refpurpose>System and session service manager configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/system.conf</filename></para> + <para><filename>/etc/systemd/system.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/system.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/system.conf.d/*.conf</filename></para> + <para><filename>/etc/systemd/user.conf</filename></para> + <para><filename>/etc/systemd/user.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/user.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/user.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>When run as a system instance, systemd interprets the + configuration file <filename>system.conf</filename> and the files + in <filename>system.conf.d</filename> directories; when run as a + user instance, systemd interprets the configuration file + <filename>user.conf</filename> and the files in + <filename>user.conf.d</filename> directories. These configuration + files contain a few settings controlling basic manager + operations.</para> + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + <xi:include href="standard-conf.xml" xpointer="conf" /> + + <refsect1> + <title>Options</title> + + <para>All options are configured in the + <literal>[Manager]</literal> section:</para> + + <variablelist class='systemd-directives'> + + <varlistentry> + <term><varname>LogLevel=</varname></term> + <term><varname>LogTarget=</varname></term> + <term><varname>LogColor=</varname></term> + <term><varname>LogLocation=</varname></term> + <term><varname>DumpCore=yes</varname></term> + <term><varname>CrashShell=no</varname></term> + <term><varname>ShowStatus=yes</varname></term> + <term><varname>CrashChVT=1</varname></term> + <term><varname>DefaultStandardOutput=journal</varname></term> + <term><varname>DefaultStandardError=inherit</varname></term> + + <listitem><para>Configures various parameters of basic manager + operation. These options may be overridden by the respective + command line arguments. See + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details about these command line + arguments.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUAffinity=</varname></term> + + <listitem><para>Configures the initial CPU affinity for the + init process. Takes a space-separated list of CPU + indices.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>JoinControllers=cpu,cpuacct net_cls,netprio</varname></term> + + <listitem><para>Configures controllers that shall be mounted + in a single hierarchy. By default, systemd will mount all + controllers which are enabled in the kernel in individual + hierarchies, with the exception of those listed in this + setting. Takes a space-separated list of comma-separated + controller names, in order to allow multiple joined + hierarchies. Defaults to 'cpu,cpuacct'. Pass an empty string + to ensure that systemd mounts all controllers in separate + hierarchies.</para> + + <para>Note that this option is only applied once, at very + early boot. If you use an initial RAM disk (initrd) that uses + systemd, it might hence be necessary to rebuild the initrd if + this option is changed, and make sure the new configuration + file is included in it. Otherwise, the initrd might mount the + controller hierarchies in a different configuration than + intended, and the main system cannot remount them + anymore.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RuntimeWatchdogSec=</varname></term> + <term><varname>ShutdownWatchdogSec=</varname></term> + + <listitem><para>Configure the hardware watchdog at runtime and + at reboot. Takes a timeout value in seconds (or in other time + units if suffixed with <literal>ms</literal>, + <literal>min</literal>, <literal>h</literal>, + <literal>d</literal>, <literal>w</literal>). If + <varname>RuntimeWatchdogSec=</varname> is set to a non-zero + value, the watchdog hardware + (<filename>/dev/watchdog</filename>) will be programmed to + automatically reboot the system if it is not contacted within + the specified timeout interval. The system manager will ensure + to contact it at least once in half the specified timeout + interval. This feature requires a hardware watchdog device to + be present, as it is commonly the case in embedded and server + systems. Not all hardware watchdogs allow configuration of the + reboot timeout, in which case the closest available timeout is + picked. <varname>ShutdownWatchdogSec=</varname> may be used to + configure the hardware watchdog when the system is asked to + reboot. It works as a safety net to ensure that the reboot + takes place even if a clean reboot attempt times out. By + default <varname>RuntimeWatchdogSec=</varname> defaults to 0 + (off), and <varname>ShutdownWatchdogSec=</varname> to 10min. + These settings have no effect if a hardware watchdog is not + available.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CapabilityBoundingSet=</varname></term> + + <listitem><para>Controls which capabilities to include in the + capability bounding set for PID 1 and its children. 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><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Capabilities listed will be included in the bounding set, all + others are removed. If the list of capabilities is prefixed + with ~, 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. The capability + bounding set may also be individually configured for units + using the <varname>CapabilityBoundingSet=</varname> directive + for units, but note that capabilities dropped for PID 1 cannot + be regained in individual units, they are lost for + good.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemCallArchitectures=</varname></term> + + <listitem><para>Takes a space-separated list of architecture + identifiers. Selects from which architectures system calls may + be invoked on this system. This may be used as an effective + way to disable invocation of non-native binaries system-wide, + for example to prohibit execution of 32-bit x86 binaries on + 64-bit x86-64 systems. This option operates system-wide, and + acts similar to the + <varname>SystemCallArchitectures=</varname> setting of unit + files, see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. This setting defaults to the empty list, in which + case no filtering of system calls based on architecture is + applied. Known architecture identifiers are + <literal>x86</literal>, <literal>x86-64</literal>, + <literal>x32</literal>, <literal>arm</literal> and the special + identifier <literal>native</literal>. The latter implicitly + maps to the native architecture of the system (or more + specifically, the architecture the system manager was compiled + for). Set this setting to <literal>native</literal> to + prohibit execution of any non-native binaries. When a binary + executes a system call of an architecture that is not listed + in this setting, it will be immediately terminated with the + SIGSYS signal.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimerSlackNSec=</varname></term> + + <listitem><para>Sets the timer slack in nanoseconds for PID 1, + which is inherited by all executed processes, unless + overridden individually, for example with the + <varname>TimerSlackNSec=</varname> setting in service units + (for details see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + The timer slack controls the accuracy of wake-ups triggered by + system timers. See + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information. Note that in contrast to most other time + span definitions this parameter takes an integer value in + nano-seconds if no unit is specified. The usual time units are + understood too.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultTimerAccuracySec=</varname></term> + + <listitem><para>Sets the default accuracy of timer units. This + controls the global default for the + <varname>AccuracySec=</varname> setting of timer units, see + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. <varname>AccuracySec=</varname> set in individual + units override the global default for the specific unit. + Defaults to 1min. Note that the accuracy of timer units is + also affected by the configured timer slack for PID 1, see + <varname>TimerSlackNSec=</varname> above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultTimeoutStartSec=</varname></term> + <term><varname>DefaultTimeoutStopSec=</varname></term> + <term><varname>DefaultRestartSec=</varname></term> + + <listitem><para>Configures the default timeouts for starting + and stopping of units, as well as the default time to sleep + between automatic restarts of units, as configured per-unit in + <varname>TimeoutStartSec=</varname>, + <varname>TimeoutStopSec=</varname> and + <varname>RestartSec=</varname> (for services, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on the per-unit settings). For non-service units, + <varname>DefaultTimeoutStartSec=</varname> sets the default + <varname>TimeoutSec=</varname> value. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultStartLimitInterval=</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>StartLimitBurst=</varname>. See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on the per-service settings.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultEnvironment=</varname></term> + + <listitem><para>Sets manager environment variables passed to + all executed processes. Takes a space-separated list of + variable assignments. See + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about environment variables.</para> + + <para>Example: + + <programlisting>DefaultEnvironment="VAR1=word1 word2" VAR2=word3 "VAR3=word 5 6"</programlisting> + + Sets three variables + <literal>VAR1</literal>, + <literal>VAR2</literal>, + <literal>VAR3</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultCPUAccounting=</varname></term> + <term><varname>DefaultBlockIOAccounting=</varname></term> + <term><varname>DefaultMemoryAccounting=</varname></term> + + <listitem><para>Configure the default resource accounting + settings, as configured per-unit by + <varname>CPUAccounting=</varname>, + <varname>BlockIOAccounting=</varname> and + <varname>MemoryAccounting=</varname>. See + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on the per-unit settings.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultLimitCPU=</varname></term> + <term><varname>DefaultLimitFSIZE=</varname></term> + <term><varname>DefaultLimitDATA=</varname></term> + <term><varname>DefaultLimitSTACK=</varname></term> + <term><varname>DefaultLimitCORE=</varname></term> + <term><varname>DefaultLimitRSS=</varname></term> + <term><varname>DefaultLimitNOFILE=</varname></term> + <term><varname>DefaultLimitAS=</varname></term> + <term><varname>DefaultLimitNPROC=</varname></term> + <term><varname>DefaultLimitMEMLOCK=</varname></term> + <term><varname>DefaultLimitLOCKS=</varname></term> + <term><varname>DefaultLimitSIGPENDING=</varname></term> + <term><varname>DefaultLimitMSGQUEUE=</varname></term> + <term><varname>DefaultLimitNICE=</varname></term> + <term><varname>DefaultLimitRTPRIO=</varname></term> + <term><varname>DefaultLimitRTTIME=</varname></term> + + <listitem><para>These settings control various default + resource limits for units. See + <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. Use the string <varname>infinity</varname> to + configure no limit on a specific resource. These settings may + be overridden in individual units using the corresponding + LimitXXX= directives. Note that these resource limits are only + defaults for units, they are not applied to PID 1 + itself.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-sysusers.xml b/man/systemd-sysusers.xml index 68710603ad..a0c0f996ac 100644 --- a/man/systemd-sysusers.xml +++ b/man/systemd-sysusers.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,99 +22,95 @@ --> <refentry id="systemd-sysusers" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-sysusers</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-sysusers</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-sysusers</refname> - <refname>systemd-sysusers.service</refname> - <refpurpose>Allocate system users and groups</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-sysusers</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg> - </cmdsynopsis> - - <para><filename>systemd-sysusers.service</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-sysusers</command> creates - system users and groups, based on the file format and - location specified in - <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para>If invoked with no arguments, it applies all - directives from all files found. If one or more - filenames are passed on the command line, only the - directives in these files are applied. If only the - basename of a file is specified, all directories as - specified in - <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - are searched for a matching file. If the string - <filename>-</filename> is specified as filenames - entries from the standard input of the process are - read.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path - as an argument. All paths will be - prefixed with the given alternate <replaceable>root</replaceable> - path, including config search paths. - </para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-sysusers</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-sysusers</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-sysusers</refname> + <refname>systemd-sysusers.service</refname> + <refpurpose>Allocate system users and groups</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-sysusers</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg> + </cmdsynopsis> + + <para><filename>systemd-sysusers.service</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-sysusers</command> creates system users and + groups, based on the file format and location specified in + <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>If invoked with no arguments, it applies all directives from + all files found. If one or more filenames are passed on the + command line, only the directives in these files are applied. If + only the basename of a file is specified, all directories as + specified in + <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + are searched for a matching file. If the string + <filename>-</filename> is specified as filenames entries from the + standard input of the process are read.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--root=<replaceable>root</replaceable></option></term> + <listitem><para>Takes a directory path as an argument. All + paths will be prefixed with the given alternate + <replaceable>root</replaceable> path, including config search + paths. </para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-timedated.service.xml b/man/systemd-timedated.service.xml index aee37db46e..e44163aefb 100644 --- a/man/systemd-timedated.service.xml +++ b/man/systemd-timedated.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,66 +23,63 @@ <refentry id="systemd-timedated.service" conditional='ENABLE_TIMEDATED'> - <refentryinfo> - <title>systemd-timedated.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-timedated.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-timedated.service</refname> - <refname>systemd-timedated</refname> - <refpurpose>Time and date bus mechanism</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-timedated.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-timedated</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-timedated</filename> is a - system service that may be used as a mechanism to change - the system clock and timezone, as well as to - enable/disable NTP time - synchronization. <filename>systemd-timedated</filename> - is automatically activated on request and terminates - itself when it is unused.</para> - - <para>The tool - <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - is a command line client to this service.</para> - - <para>See the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/timedated"> - developer documentation</ulink> for information about - the APIs <filename>systemd-timedated</filename> - provides.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-timedated.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-timedated.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-timedated.service</refname> + <refname>systemd-timedated</refname> + <refpurpose>Time and date bus mechanism</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-timedated.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-timedated</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-timedated</filename> is a system service + that may be used as a mechanism to change the system clock and + timezone, as well as to enable/disable NTP time synchronization. + <filename>systemd-timedated</filename> is automatically activated + on request and terminates itself when it is unused.</para> + + <para>The tool + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + is a command line client to this service.</para> + + <para>See the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/timedated"> + developer documentation</ulink> for information about the APIs + <filename>systemd-timedated</filename> provides.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-timesyncd.service.xml b/man/systemd-timesyncd.service.xml index f4ebccd4a5..ac1af2d136 100644 --- a/man/systemd-timesyncd.service.xml +++ b/man/systemd-timesyncd.service.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,85 +23,82 @@ <refentry id="systemd-timesyncd.service" conditional='ENABLE_TIMESYNCD'> - <refentryinfo> - <title>systemd-timesyncd.service</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Kay</firstname> - <surname>Sievers</surname> - <email>kay@vrfy.org</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-timesyncd.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-timesyncd.service</refname> - <refname>systemd-timesyncd</refname> - <refpurpose>Network Time Synchronization</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-timesyncd.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-timesyncd</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-timesyncd</filename> is a - system service that may be used to synchronize the - local system clock with a remote Network Time Protocol - server. It also saves the local time to disk every - time the clock has been synchronized and uses this to - possibly advance the system realtime clock on - subsequent reboots to ensure it - monotonically advances even if the system lacks a - battery-buffered RTC chip.</para> - - <para>The NTP servers contacted are determined from - the global settings in - <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - the per-link static settings in - <filename>.network</filename> files, and the per-link - dynamic settings received over DHCP. See - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more details.</para> - </refsect1> - - <refsect1> - <title>Files</title> - - <variablelist> - <varlistentry> - <term><filename>/var/lib/systemd/clock</filename></term> - - <listitem> - <para>This file contains the timestamp of last - successful synchronization.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-timesyncd.service</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Kay</firstname> + <surname>Sievers</surname> + <email>kay@vrfy.org</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-timesyncd.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-timesyncd.service</refname> + <refname>systemd-timesyncd</refname> + <refpurpose>Network Time Synchronization</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-timesyncd.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-timesyncd</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-timesyncd</filename> is a system service + that may be used to synchronize the local system clock with a + remote Network Time Protocol server. It also saves the local time + to disk every time the clock has been synchronized and uses this + to possibly advance the system realtime clock on subsequent + reboots to ensure it monotonically advances even if the system + lacks a battery-buffered RTC chip.</para> + + <para>The NTP servers contacted are determined from the global + settings in + <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + the per-link static settings in <filename>.network</filename> + files, and the per-link dynamic settings received over DHCP. See + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more details.</para> + </refsect1> + + <refsect1> + <title>Files</title> + + <variablelist> + <varlistentry> + <term><filename>/var/lib/systemd/clock</filename></term> + + <listitem> + <para>This file contains the timestamp of last successful + synchronization.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml index f4d53b3139..ceec06f840 100644 --- a/man/systemd-tmpfiles.xml +++ b/man/systemd-tmpfiles.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,194 +22,179 @@ --> <refentry id="systemd-tmpfiles" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-tmpfiles</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-tmpfiles</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-tmpfiles</refname> - <refname>systemd-tmpfiles-setup.service</refname> - <refname>systemd-tmpfiles-setup-dev.service</refname> - <refname>systemd-tmpfiles-clean.service</refname> - <refname>systemd-tmpfiles-clean.timer</refname> - <refpurpose>Creates, deletes and cleans up volatile - and temporary files and directories</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-tmpfiles</command> - <arg choice="opt" rep="repeat">OPTIONS</arg> - <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg> - </cmdsynopsis> - - <para><filename>systemd-tmpfiles-setup.service</filename></para> - <para><filename>systemd-tmpfiles-setup-dev.service</filename></para> - <para><filename>systemd-tmpfiles-clean.service</filename></para> - <para><filename>systemd-tmpfiles-clean.timer</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-tmpfiles</command> creates, - deletes, and cleans up volatile and temporary files and - directories, based on the configuration file format and - location specified in - <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 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 - <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - are searched for a matching file.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--create</option></term> - <listitem><para>If this option is - passed, all files and directories - marked with <varname>f</varname>, - <varname>F</varname>, - <varname>w</varname>, - <varname>d</varname>, - <varname>D</varname>, - <varname>v</varname>, - <varname>p</varname>, - <varname>L</varname>, - <varname>c</varname>, - <varname>b</varname>, - <varname>m</varname> in the - configuration files are created or - written to. Files and directories - marked with <varname>z</varname>, - <varname>Z</varname>, - <varname>t</varname>, - <varname>T</varname>, - <varname>a</varname>, and - <varname>A</varname> have their - ownership, access mode and security - labels set. </para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--clean</option></term> - <listitem><para>If this option is - passed, all files and directories with - an age parameter configured will be - cleaned up.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--remove</option></term> - <listitem><para>If this option is - passed, the contents of - directories marked with - <varname>D</varname> or - <varname>R</varname>, and files or - directories themselves marked with - <varname>r</varname> or - <varname>R</varname> are - removed.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--boot</option></term> - <listitem><para>Also execute lines - with an exclamation mark. - </para></listitem> - </varlistentry> - <varlistentry> - <term><option>--prefix=<replaceable>path</replaceable></option></term> - <listitem><para>Only apply rules with - paths that start with the specified - prefix. This option can be specified - multiple times.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--exclude-prefix=<replaceable>path</replaceable></option></term> - <listitem><para>Ignore rules with - paths that start with the specified - prefix. This option can be specified - multiple times.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path - as an argument. All paths will be - prefixed with the given alternate <replaceable>root</replaceable> - path, including config search paths. - </para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - <para>It is possible to combine - <option>--create</option>, <option>--clean</option>, - and <option>--remove</option> in one invocation. For - example, during boot the following command line is - executed to ensure that all temporary and volatile - directories are removed and created according to the - configuration file:</para> - - <programlisting>systemd-tmpfiles --remove --create</programlisting> - - </refsect1> - - <refsect1> - <title>Unprivileged --cleanup operation</title> - - <para><command>systemd-tmpfiles</command> tries to - avoid changing the access and modification times on - the directories it accesses, which requires - <constant>CAP_ADMIN</constant> privileges. When - running as non-root, directories which are checked for - files to clean up will have their access time bumped, - which might prevent their cleanup. - </para> - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-tmpfiles</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-tmpfiles</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-tmpfiles</refname> + <refname>systemd-tmpfiles-setup.service</refname> + <refname>systemd-tmpfiles-setup-dev.service</refname> + <refname>systemd-tmpfiles-clean.service</refname> + <refname>systemd-tmpfiles-clean.timer</refname> + <refpurpose>Creates, deletes and cleans up volatile + and temporary files and directories</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-tmpfiles</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg> + </cmdsynopsis> + + <para><filename>systemd-tmpfiles-setup.service</filename></para> + <para><filename>systemd-tmpfiles-setup-dev.service</filename></para> + <para><filename>systemd-tmpfiles-clean.service</filename></para> + <para><filename>systemd-tmpfiles-clean.timer</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-tmpfiles</command> creates, deletes, and + cleans up volatile and temporary files and directories, based on + the configuration file format and location specified in + <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 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 + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + are searched for a matching file.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--create</option></term> + <listitem><para>If this option is passed, all files and + directories marked with + <varname>f</varname>, + <varname>F</varname>, + <varname>w</varname>, + <varname>d</varname>, + <varname>D</varname>, + <varname>v</varname>, + <varname>p</varname>, + <varname>L</varname>, + <varname>c</varname>, + <varname>b</varname>, + <varname>m</varname> + in the configuration files are created or written to. Files + and directories marked with + <varname>z</varname>, + <varname>Z</varname>, + <varname>t</varname>, + <varname>T</varname>, + <varname>a</varname>, and + <varname>A</varname> have their ownership, access mode and + security labels set. </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--clean</option></term> + <listitem><para>If this option is passed, all files and + directories with an age parameter configured will be cleaned + up.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--remove</option></term> + <listitem><para>If this option is passed, the contents of + directories marked with <varname>D</varname> or + <varname>R</varname>, and files or directories themselves + marked with <varname>r</varname> or <varname>R</varname> are + removed.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--boot</option></term> + <listitem><para>Also execute lines with an exclamation mark. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--prefix=<replaceable>path</replaceable></option></term> + <listitem><para>Only apply rules with paths that start with + the specified prefix. This option can be specified multiple + times.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--exclude-prefix=<replaceable>path</replaceable></option></term> + <listitem><para>Ignore rules with paths that start with the + specified prefix. This option can be specified multiple + times.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--root=<replaceable>root</replaceable></option></term> + <listitem><para>Takes a directory path as an argument. All + paths will be prefixed with the given alternate + <replaceable>root</replaceable> path, including config search + paths. </para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + <para>It is possible to combine <option>--create</option>, + <option>--clean</option>, and <option>--remove</option> in one + invocation. For example, during boot the following command line is + executed to ensure that all temporary and volatile directories are + removed and created according to the configuration file:</para> + + <programlisting>systemd-tmpfiles --remove --create</programlisting> + + </refsect1> + + <refsect1> + <title>Unprivileged --cleanup operation</title> + + <para><command>systemd-tmpfiles</command> tries to avoid changing + the access and modification times on the directories it accesses, + which requires <constant>CAP_ADMIN</constant> privileges. When + running as non-root, directories which are checked for files to + clean up will have their access time bumped, which might prevent + their cleanup. + </para> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure code + otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-tty-ask-password-agent.xml b/man/systemd-tty-ask-password-agent.xml index 53bd3aa840..2876fab644 100644 --- a/man/systemd-tty-ask-password-agent.xml +++ b/man/systemd-tty-ask-password-agent.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,133 +22,128 @@ --> <refentry id="systemd-tty-ask-password-agent" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-tty-ask-password-agent</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-tty-ask-password-agent</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-tty-ask-password-agent</refname> - <refpurpose>List or process pending systemd password requests</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-tty-ask-password-agent <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-tty-ask-password-agent</command> - is a password agent that handles password - requests of the system, for example for hard disk - encryption passwords or SSL certificate passwords that - need to be queried at boot-time or during - runtime.</para> - - <para><command>systemd-tty-ask-password-agent</command> - implements the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">Password - Agents Specification</ulink>.</para> - - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--list</option></term> - - <listitem><para>Lists all currently pending system password requests.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--query</option></term> - - <listitem><para>Process all currently - pending system password requests by - querying the user on the calling - TTY.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--watch</option></term> - - <listitem><para>Continuously process - password requests.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--wall</option></term> - - <listitem><para>Forward password - requests to - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - instead of querying the user on the - calling TTY.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--plymouth</option></term> - - <listitem><para>Ask question with - <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry> - instead of querying the user on the - calling TTY.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--console</option></term> - - <listitem><para>Ask question on - <filename>/dev/console</filename> - instead of querying the user on the - calling TTY. </para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-tty-ask-password-agent</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-tty-ask-password-agent</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-tty-ask-password-agent</refname> + <refpurpose>List or process pending systemd password requests</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-tty-ask-password-agent <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-tty-ask-password-agent</command> is a + password agent that handles password requests of the system, for + example for hard disk encryption passwords or SSL certificate + passwords that need to be queried at boot-time or during + runtime.</para> + + <para><command>systemd-tty-ask-password-agent</command> implements + the <ulink url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">Password + Agents Specification</ulink>.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--list</option></term> + + <listitem><para>Lists all currently pending system password requests.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--query</option></term> + + <listitem><para>Process all currently pending system password + requests by querying the user on the calling + TTY.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--watch</option></term> + + <listitem><para>Continuously process password + requests.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--wall</option></term> + + <listitem><para>Forward password requests to + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + instead of querying the user on the calling + TTY.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--plymouth</option></term> + + <listitem><para>Ask question with + <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry> + instead of querying the user on the calling + TTY.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--console</option></term> + + <listitem><para>Ask question on + <filename>/dev/console</filename> instead of querying the user + on the calling TTY. </para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-update-done.service.xml b/man/systemd-update-done.service.xml index c3b402b601..d65f175418 100644 --- a/man/systemd-update-done.service.xml +++ b/man/systemd-update-done.service.xml @@ -21,81 +21,77 @@ --> <refentry id="systemd-update-done.service"> - <refentryinfo> - <title>systemd-update-done.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-update-done.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-update-done.service</refname> - <refname>systemd-update-done</refname> - <refpurpose>Mark <filename>/etc</filename> and <filename>/var</filename> fully updated</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-update-done.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-update-done</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-update-done.service</filename> - is a service that is invoked as part of the first boot - after the vendor operating system resources in - <filename>/usr</filename> have been updated. This is - useful to implement offline updates of - <filename>/usr</filename> which might requires updates - to <filename>/etc</filename> or - <filename>/var</filename> on the following boot.</para> - - <para><filename>systemd-update-done.service</filename> - updates the file modification time (mtime) of the - stamp files <filename>/etc/.updated</filename> and - <filename>/var/.updated</filename> to the modification - time of the <filename>/usr</filename> directory, - unless the stamp files are already newer.</para> - - <para>Services that shall run after offline upgrades - of <filename>/usr</filename> should order themselves - before - <filename>systemd-update-done.service</filename>, and - use the <varname>ConditionNeedsUpdate=</varname> (see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>) - condition to make sure to run when - <filename>/etc</filename> or <filename>/var</filename> - are older than <filename>/usr</filename> according to - the modification times of the files described - above. This requires that updates to - <filename>/usr</filename> are always followed by an - update of the modification time of - <filename>/usr</filename>, for example by invoking - <citerefentry project='man-pages'><refentrytitle>touch</refentrytitle><manvolnum>1</manvolnum></citerefentry> - on it.</para> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>touch</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-update-done.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-update-done.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-update-done.service</refname> + <refname>systemd-update-done</refname> + <refpurpose>Mark <filename>/etc</filename> and <filename>/var</filename> fully updated</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-update-done.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-update-done</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-update-done.service</filename> is a + service that is invoked as part of the first boot after the vendor + operating system resources in <filename>/usr</filename> have been + updated. This is useful to implement offline updates of + <filename>/usr</filename> which might requires updates to + <filename>/etc</filename> or <filename>/var</filename> on the + following boot.</para> + + <para><filename>systemd-update-done.service</filename> updates the + file modification time (mtime) of the stamp files + <filename>/etc/.updated</filename> and + <filename>/var/.updated</filename> to the modification time of the + <filename>/usr</filename> directory, unless the stamp files are + already newer.</para> + + <para>Services that shall run after offline upgrades of + <filename>/usr</filename> should order themselves before + <filename>systemd-update-done.service</filename>, and use the + <varname>ConditionNeedsUpdate=</varname> (see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>) + condition to make sure to run when <filename>/etc</filename> or + <filename>/var</filename> are older than <filename>/usr</filename> + according to the modification times of the files described above. + This requires that updates to <filename>/usr</filename> are always + followed by an update of the modification time of + <filename>/usr</filename>, for example by invoking + <citerefentry project='man-pages'><refentrytitle>touch</refentrytitle><manvolnum>1</manvolnum></citerefentry> + on it.</para> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>touch</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-update-utmp.service.xml b/man/systemd-update-utmp.service.xml index caa1d8f568..b842d29721 100644 --- a/man/systemd-update-utmp.service.xml +++ b/man/systemd-update-utmp.service.xml @@ -21,56 +21,56 @@ --> <refentry id="systemd-update-utmp.service" conditional="HAVE_UTMP"> - <refentryinfo> - <title>systemd-update-utmp.service</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-update-utmp.service</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-update-utmp.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-update-utmp.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-update-utmp.service</refname> - <refname>systemd-update-utmp-runlevel.service</refname> - <refname>systemd-update-utmp</refname> - <refpurpose>Write audit and utmp updates at bootup, runlevel - changes and shutdown</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-update-utmp.service</refname> + <refname>systemd-update-utmp-runlevel.service</refname> + <refname>systemd-update-utmp</refname> + <refpurpose>Write audit and utmp updates at bootup, runlevel + changes and shutdown</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>systemd-update-utmp.service</filename></para> - <para><filename>systemd-update-utmp-runlevel.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-update-utmp</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>systemd-update-utmp.service</filename></para> + <para><filename>systemd-update-utmp-runlevel.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-update-utmp</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-update-utmp-runlevel.service</filename> - is a service that writes SysV runlevel changes to utmp - and wtmp, as well as the audit logs, as they - occur. <filename>systemd-update-utmp.service</filename> - does the same for system reboots and shutdown requests.</para> - </refsect1> + <para><filename>systemd-update-utmp-runlevel.service</filename> is + a service that writes SysV runlevel changes to utmp and wtmp, as + well as the audit logs, as they occur. + <filename>systemd-update-utmp.service</filename> does the same for + system reboots and shutdown requests.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>auditd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>auditd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-user-sessions.service.xml b/man/systemd-user-sessions.service.xml index 767cbc714a..9d796b1ae1 100644 --- a/man/systemd-user-sessions.service.xml +++ b/man/systemd-user-sessions.service.xml @@ -21,57 +21,56 @@ --> <refentry id="systemd-user-sessions.service" conditional='HAVE_PAM'> - <refentryinfo> - <title>systemd-user-sessions.service</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd-user-sessions.service</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd-user-sessions.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd-user-sessions.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd-user-sessions.service</refname> - <refname>systemd-user-sessions</refname> - <refpurpose>Permit user logins after boot, prohibit user logins at shutdown</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd-user-sessions.service</refname> + <refname>systemd-user-sessions</refname> + <refpurpose>Permit user logins after boot, prohibit user logins at shutdown</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename>systemd-user-sessions.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-user-sessions</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename>systemd-user-sessions.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-user-sessions</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para><filename>systemd-user-sessions.service</filename> - is a service that controls user logins. After basic - system initialization is complete it removes - <filename>/run/nologin</filename>, thus permitting - logins. Before system shutdown it creates - <filename>/run/nologin</filename>, thus prohibiting - further logins. At the same time it also kills all - user processes, so that system shutdown may proceed - without any remaining user processes around.</para> - </refsect1> + <para><filename>systemd-user-sessions.service</filename> is a + service that controls user logins. After basic system + initialization is complete it removes + <filename>/run/nologin</filename>, thus permitting logins. Before + system shutdown it creates <filename>/run/nologin</filename>, thus + prohibiting further logins. At the same time it also kills all + user processes, so that system shutdown may proceed without any + remaining user processes around.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>pam_nologin</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>pam_nologin</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd-vconsole-setup.service.xml b/man/systemd-vconsole-setup.service.xml index 3c50799cbd..59bb5e4e8c 100644 --- a/man/systemd-vconsole-setup.service.xml +++ b/man/systemd-vconsole-setup.service.xml @@ -21,98 +21,94 @@ --> <refentry id="systemd-vconsole-setup.service" conditional='ENABLE_VCONSOLE'> - <refentryinfo> - <title>systemd-vconsole-setup.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-vconsole-setup.service</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-vconsole-setup.service</refname> - <refname>systemd-vconsole-setup</refname> - <refpurpose>Configure the virtual console at boot</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>systemd-vconsole-setup.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-vconsole-setup</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><filename>systemd-vconsole-setup.service</filename> - is an early-boot service that configures the virtual - console font and console keymap. Internally it calls - <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - - <para>See - <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about the configuration files understood by this - service.</para> - - - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para>A few configuration parameters from - <filename>vconsole.conf</filename> may be overridden on - the kernel command line:</para> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>vconsole.keymap=</varname></term> - <term><varname>vconsole.keymap.toggle=</varname></term> - - <listitem><para>Overrides the key - mapping table for the keyboard and the - second toggle keymap.</para></listitem> - </varlistentry> - <varlistentry> - - <term><varname>vconsole.font=</varname></term> - <term><varname>vconsole.font.map=</varname></term> - <term><varname>vconsole.font.unimap=</varname></term> - - <listitem><para>Configures the console - font, the console map, and the unicode - font map.</para></listitem> - - - </varlistentry> - </variablelist> - - <para>See - <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for information about these settings.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd-vconsole-setup.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-vconsole-setup.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-vconsole-setup.service</refname> + <refname>systemd-vconsole-setup</refname> + <refpurpose>Configure the virtual console at boot</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-vconsole-setup.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-vconsole-setup</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-vconsole-setup.service</filename> is an + early-boot service that configures the virtual console font and + console keymap. Internally it calls + <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para>See + <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about the configuration files understood by this + service.</para> + + + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para>A few configuration parameters from + <filename>vconsole.conf</filename> may be overridden on the kernel + command line:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>vconsole.keymap=</varname></term> + <term><varname>vconsole.keymap.toggle=</varname></term> + + <listitem><para>Overrides the key mapping table for the + keyboard and the second toggle keymap.</para></listitem> + </varlistentry> + <varlistentry> + + <term><varname>vconsole.font=</varname></term> + <term><varname>vconsole.font.map=</varname></term> + <term><varname>vconsole.font.unimap=</varname></term> + + <listitem><para>Configures the console font, the console map, + and the unicode font map.</para></listitem> + </varlistentry> + </variablelist> + + <para>See + <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information about these settings.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.automount.xml b/man/systemd.automount.xml index f04a4a4927..1aa4593854 100644 --- a/man/systemd.automount.xml +++ b/man/systemd.automount.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,146 +23,133 @@ --> <refentry id="systemd.automount"> - <refentryinfo> - <title>systemd.automount</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.automount</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.automount</refname> - <refpurpose>Automount unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>automount</replaceable>.automount</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.automount</literal> encodes information - about a file system automount point controlled and - supervised by systemd.</para> - - <para>This man page lists the configuration options - specific to this unit type. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the common options of all unit configuration - files. The common configuration items are configured - in the generic [Unit] and [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>For each automount unit file a matching mount - unit file (see - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details) must exist which is activated when the - automount path is accessed. Example: if an automount - unit <filename>home-lennart.automount</filename> is - active and the user accesses - <filename>/home/lennart</filename> the mount unit - <filename>home-lennart.mount</filename> will be - activated.</para> - - <para>Automount units may be used to implement - on-demand mounting as well as parallelized mounting of - file systems.</para> - - <para>If an automount point is beneath another mount - point in the file system hierarchy, a dependency - between both units is created automatically.</para> - </refsect1> - - <refsect1> - <title><filename>fstab</filename></title> - - <para>Automount units may either be configured via unit - files, or via <filename>/etc/fstab</filename> (see - <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details).</para> - - <para>For details how systemd parses - <filename>/etc/fstab</filename> see - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>If an automount point is configured in both - <filename>/etc/fstab</filename> and a unit file, the - configuration in the latter takes precedence.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>Automount files must include an [Automount] - section, which carries information about the file - system automount points it supervises. The options - specific to the [Automount] section of automount units - are the following:</para> - - <variablelist class='unit-directives'> - - <varlistentry> - <term><varname>Where=</varname></term> - <listitem><para>Takes an absolute path - of a directory of the automount - point. If the automount point does not - exist at time that the automount - point is installed, it is created. This - string must be reflected in the unit - filename. (See above.) This option is - mandatory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DirectoryMode=</varname></term> - <listitem><para>Directories of - automount points (and any parent - directories) are automatically created - if needed. This option specifies the - file system access mode used when - creating these directories. Takes an - access mode in octal - notation. Defaults to - 0755.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>automount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd.automount</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.automount</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.automount</refname> + <refpurpose>Automount unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>automount</replaceable>.automount</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.automount</literal> encodes information about a file + system automount point controlled and supervised by + systemd.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [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>For each automount unit file a matching mount unit file (see + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) must exist which is activated when the automount path + is accessed. Example: if an automount unit + <filename>home-lennart.automount</filename> is active and the user + accesses <filename>/home/lennart</filename> the mount unit + <filename>home-lennart.mount</filename> will be activated.</para> + + <para>Automount units may be used to implement on-demand mounting + as well as parallelized mounting of file systems.</para> + + <para>If an automount point is beneath another mount point in the + file system hierarchy, a dependency between both units is created + automatically.</para> + </refsect1> + + <refsect1> + <title><filename>fstab</filename></title> + + <para>Automount units may either be configured via unit files, or + via <filename>/etc/fstab</filename> (see + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details).</para> + + <para>For details how systemd parses + <filename>/etc/fstab</filename> see + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>If an automount point is configured in both + <filename>/etc/fstab</filename> and a unit file, the configuration + in the latter takes precedence.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Automount files must include an [Automount] section, which + carries information about the file system automount points it + supervises. The options specific to the [Automount] section of + automount units are the following:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>Where=</varname></term> + <listitem><para>Takes an absolute path of a directory of the + automount point. If the automount point does not exist at time + that the automount point is installed, it is created. This + string must be reflected in the unit filename. (See above.) + This option is mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + <listitem><para>Directories of automount points (and any + parent directories) are automatically created if needed. This + option specifies the file system access mode used when + creating these directories. Takes an access mode in octal + notation. Defaults to 0755.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>automount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.device.xml b/man/systemd.device.xml index 557f15f906..829ffd1740 100644 --- a/man/systemd.device.xml +++ b/man/systemd.device.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,173 +23,150 @@ --> <refentry id="systemd.device"> - <refentryinfo> - <title>systemd.device</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.device</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.device</refname> - <refpurpose>Device unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>device</replaceable>.device</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.device</literal> encodes information about - a device unit as exposed in the - sysfs/<citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> - device tree.</para> - - <para>This unit type has no specific options. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the common options of all unit configuration - files. The common configuration items are configured - in the generic <literal>[Unit]</literal> and - <literal>[Install]</literal> sections. A separate - <literal>[Device]</literal> section does not exist, - since no device-specific options may be - configured.</para> - - <para>systemd will dynamically create device units for - all kernel devices that are marked with the "systemd" - udev tag (by default all block and network devices, - and a few others). This may be used to define - dependencies between devices and other units. To tag a - udev device, use <literal>TAG+="systemd"</literal> in - the udev rules file, see - <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details.</para> - - <para>Device units are named after the - <filename>/sys</filename> and - <filename>/dev</filename> paths they control. Example: - the device <filename noindex='true'>/dev/sda5</filename> is exposed - in systemd as <filename>dev-sda5.device</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> - - </refsect1> - - <refsect1> - <title>The udev Database</title> - - <para>The settings of device units may either be - configured via unit files, or directly from the udev - database (which is recommended). The following udev device - properties are understood by systemd:</para> - - <variablelist class='udev-directives'> - <varlistentry> - <term><varname>SYSTEMD_WANTS=</varname></term> - <term><varname>SYSTEMD_USER_WANTS=</varname></term> - <listitem><para>Adds dependencies of - type <varname>Wants</varname> from the - device unit to all listed units. The - first form is used by the system - systemd instance, the second by user - systemd instances. Those settings may - be used to activate arbitrary units - when a specific device becomes - available.</para> - - <para>Note that this and the - other tags are not taken into account - unless the device is tagged with the - <literal>systemd</literal> string in - the udev database, because otherwise - the device is not exposed as a systemd - unit (see above).</para> - - <para>Note that systemd will only act - on <varname>Wants</varname> - dependencies when a device first - becomes active. It will not act on - them if they are added to devices that - are already active. Use - <varname>SYSTEMD_READY=</varname> (see - below) to influence on which udev - event to trigger the dependencies. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SYSTEMD_ALIAS=</varname></term> - <listitem><para>Adds an additional - alias name to the device unit. This - must be an absolute path that is - automatically transformed into a unit - name. (See above.)</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SYSTEMD_READY=</varname></term> - <listitem><para>If set to 0, systemd - will consider this device unplugged - even if it shows up in the udev - tree. If this property is unset or set - to 1, the device will be considered - plugged if it is visible in the - udev tree. This property has no - influence on the behavior when a - device disappears from the udev - tree.</para> - - <para>This option is useful to support - devices that initially show up in an - uninitialized state in the tree, and - for which a <literal>changed</literal> - event is generated the moment they are - fully set up. Note that - <varname>SYSTEMD_WANTS=</varname> (see - above) is not acted on as long as - <varname>SYSTEMD_READY=0</varname> is - set for a device.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ID_MODEL_FROM_DATABASE=</varname></term> - <term><varname>ID_MODEL=</varname></term> - - <listitem><para>If set, this property is - used as description string for the - device unit.</para></listitem> - </varlistentry> - - </variablelist> - - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd.device</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.device</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.device</refname> + <refpurpose>Device unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>device</replaceable>.device</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.device</literal> encodes information about a device unit + as exposed in the + sysfs/<citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> + device tree.</para> + + <para>This unit type has no specific options. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic + <literal>[Unit]</literal> and <literal>[Install]</literal> + sections. A separate <literal>[Device]</literal> section does not + exist, since no device-specific options may be configured.</para> + + <para>systemd will dynamically create device units for all kernel + devices that are marked with the "systemd" udev tag (by default + all block and network devices, and a few others). This may be used + to define dependencies between devices and other units. To tag a + udev device, use <literal>TAG+="systemd"</literal> in the udev + rules file, see + <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.</para> + + <para>Device units are named after the <filename>/sys</filename> + and <filename>/dev</filename> paths they control. Example: the + device <filename noindex='true'>/dev/sda5</filename> is exposed in + systemd as <filename>dev-sda5.device</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> + + </refsect1> + + <refsect1> + <title>The udev Database</title> + + <para>The settings of device units may either be configured via + unit files, or directly from the udev database (which is + recommended). The following udev device properties are understood + by systemd:</para> + + <variablelist class='udev-directives'> + <varlistentry> + <term><varname>SYSTEMD_WANTS=</varname></term> + <term><varname>SYSTEMD_USER_WANTS=</varname></term> + <listitem><para>Adds dependencies of type + <varname>Wants</varname> from the device unit to all listed + units. The first form is used by the system systemd instance, + the second by user systemd instances. Those settings may be + used to activate arbitrary units when a specific device + becomes available.</para> + + <para>Note that this and the other tags are not taken into + account unless the device is tagged with the + <literal>systemd</literal> string in the udev database, + because otherwise the device is not exposed as a systemd unit + (see above).</para> + + <para>Note that systemd will only act on + <varname>Wants</varname> dependencies when a device first + becomes active. It will not act on them if they are added to + devices that are already active. Use + <varname>SYSTEMD_READY=</varname> (see below) to influence on + which udev event to trigger the dependencies. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSTEMD_ALIAS=</varname></term> + <listitem><para>Adds an additional alias name to the device + unit. This must be an absolute path that is automatically + transformed into a unit name. (See above.)</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSTEMD_READY=</varname></term> + <listitem><para>If set to 0, systemd will consider this device + unplugged even if it shows up in the udev tree. If this + property is unset or set to 1, the device will be considered + plugged if it is visible in the udev tree. This property has + no influence on the behavior when a device disappears from the + udev tree.</para> + + <para>This option is useful to support devices that initially + show up in an uninitialized state in the tree, and for which a + <literal>changed</literal> event is generated the moment they + are fully set up. Note that <varname>SYSTEMD_WANTS=</varname> + (see above) is not acted on as long as + <varname>SYSTEMD_READY=0</varname> is set for a + device.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID_MODEL_FROM_DATABASE=</varname></term> + <term><varname>ID_MODEL=</varname></term> + + <listitem><para>If set, this property is used as description + string for the device unit.</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index cbaec9f13b..74d698dbfc 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -1,6 +1,6 @@ <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,1647 +22,1261 @@ --> <refentry id="systemd.exec"> - <refentryinfo> - <title>systemd.exec</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.exec</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.exec</refname> - <refpurpose>Execution environment configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>service</replaceable>.service</filename>, - <filename><replaceable>socket</replaceable>.socket</filename>, - <filename><replaceable>mount</replaceable>.mount</filename>, - <filename><replaceable>swap</replaceable>.swap</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>Unit configuration files for services, sockets, - mount points, and swap devices share a subset of - configuration options which define the execution - environment of spawned processes.</para> - - <para>This man page lists the configuration options - shared by these four unit types. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the common options of all unit configuration - files, and - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - and - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information on the specific unit - configuration files. The execution specific - configuration options are configured in the [Service], - [Socket], [Mount], or [Swap] sections, depending on the unit - type.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <variablelist class='unit-directives'> - - <varlistentry> - <term><varname>WorkingDirectory=</varname></term> - - <listitem><para>Takes an absolute - directory path. Sets the working - directory for executed processes. If - not set, defaults to the root directory - when systemd is running as a system - instance and the respective user's - home directory if run as - user.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RootDirectory=</varname></term> - - <listitem><para>Takes an absolute - directory path. Sets the root - directory for executed processes, with - the - <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call. If this is used, it must - be ensured that the process and all - its auxiliary files are available in - the <function>chroot()</function> - jail.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>User=</varname></term> - <term><varname>Group=</varname></term> - - <listitem><para>Sets the Unix user - or group that the processes are executed - as, respectively. Takes a single user or group - name or ID as argument. If no group is - set, the default group of the user is - chosen.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SupplementaryGroups=</varname></term> - - <listitem><para>Sets the supplementary - Unix groups the processes are executed - as. This takes a space-separated list - of group names or IDs. This option may - be specified more than once in which - case all listed groups are set as - supplementary groups. When the empty - string is assigned the list of - supplementary groups is reset, and all - assignments prior to this one will - have no effect. In any way, this - option does not override, but extends - the list of supplementary groups - configured in the system group - database for the - user.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Nice=</varname></term> - - <listitem><para>Sets the default nice - level (scheduling priority) for - executed processes. Takes an integer - between -20 (highest priority) and 19 - (lowest priority). See - <citerefentry><refentrytitle>setpriority</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>OOMScoreAdjust=</varname></term> - - <listitem><para>Sets the adjustment - level for the Out-Of-Memory killer for - executed processes. Takes an integer - between -1000 (to disable OOM killing - for this process) and 1000 (to make - killing of this process under memory - pressure very likely). See <ulink - url="https://www.kernel.org/doc/Documentation/filesystems/proc.txt">proc.txt</ulink> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>IOSchedulingClass=</varname></term> - - <listitem><para>Sets the IO scheduling - class for executed processes. Takes an - integer between 0 and 3 or one of the - strings <option>none</option>, - <option>realtime</option>, - <option>best-effort</option> or - <option>idle</option>. See - <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>IOSchedulingPriority=</varname></term> - - <listitem><para>Sets the IO scheduling - priority for executed processes. Takes - an integer between 0 (highest - priority) and 7 (lowest priority). The - available priorities depend on the - selected IO scheduling class (see - above). See - <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>CPUSchedulingPolicy=</varname></term> - - <listitem><para>Sets the CPU - scheduling policy for executed - processes. Takes one of - <option>other</option>, - <option>batch</option>, - <option>idle</option>, - <option>fifo</option> or - <option>rr</option>. See - <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>CPUSchedulingPriority=</varname></term> - - <listitem><para>Sets the CPU - scheduling priority for executed - processes. The available priority - range depends on the selected CPU - scheduling policy (see above). For - real-time scheduling policies an - integer between 1 (lowest priority) - and 99 (highest priority) can be used. - See <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>CPUSchedulingResetOnFork=</varname></term> - - <listitem><para>Takes a boolean - argument. If true, elevated CPU - scheduling priorities and policies - will be reset when the executed - processes fork, and can hence not leak - into child processes. See - <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. Defaults to false.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>CPUAffinity=</varname></term> - - <listitem><para>Controls the CPU - affinity of the executed - processes. Takes a space-separated - list of CPU indices. This option may - be specified more than once in which - case the specified CPU affinity masks - are merged. If the empty string is - assigned, the mask is reset, all - assignments prior to this will have no - effect. See - <citerefentry><refentrytitle>sched_setaffinity</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>UMask=</varname></term> - - <listitem><para>Controls the file mode - creation mask. Takes an access mode in - octal notation. See - <citerefentry><refentrytitle>umask</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. Defaults to - 0022.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Environment=</varname></term> - - <listitem><para>Sets environment - variables for executed - processes. Takes a space-separated - list of variable assignments. This - option may be specified more than once - in which case all listed variables - will be set. If the same variable is - set twice, the later setting will - override the earlier setting. If the - empty string is assigned to this - option, the list of environment - variables is reset, all prior - assignments have no effect. - Variable expansion is not performed - inside the strings, however, specifier - expansion is possible. The $ character has - no special meaning. - If you need to assign a value containing spaces - to a variable, use double quotes (") - for the assignment.</para> - - <para>Example: - <programlisting>Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6"</programlisting> - gives three variables <literal>VAR1</literal>, - <literal>VAR2</literal>, <literal>VAR3</literal> - with the values <literal>word1 word2</literal>, - <literal>word3</literal>, <literal>$word 5 6</literal>. - </para> - - <para> - See - <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details about environment variables.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>EnvironmentFile=</varname></term> - <listitem><para>Similar to - <varname>Environment=</varname> but - reads the environment variables from a - text file. The text file should - contain new-line-separated variable - assignments. Empty lines and lines - starting with ; or # will be ignored, - which may be used for commenting. A line - ending with a backslash will be concatenated - with the following one, allowing multiline variable - definitions. The parser strips leading - and trailing whitespace from the values - of assignments, unless you use - double quotes (").</para> - - <para>The argument passed should be an - absolute filename or wildcard - expression, optionally prefixed with - <literal>-</literal>, which indicates - that if the file does not exist, it - will not be read and no error or warning - message is logged. This option may be - specified more than once in which case - all specified files are read. If the - empty string is assigned to this - option, the list of file to read is - reset, all prior assignments have no - effect.</para> - - <para>The files listed with this - directive will be read shortly before - the process is executed (more - specifically, after all - processes from a previous unit state - terminated. This means you can - generate these files in one unit - state, and read it with this option in - the next). Settings from these files - override settings made with - <varname>Environment=</varname>. If - the same variable is set twice from - these files, the files will be read in - the order they are specified and the - later setting will override the - earlier setting.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>StandardInput=</varname></term> - <listitem><para>Controls where file - descriptor 0 (STDIN) of the executed - processes is connected to. Takes one - of <option>null</option>, - <option>tty</option>, - <option>tty-force</option>, - <option>tty-fail</option> or - <option>socket</option>.</para> - - <para>If <option>null</option> is - selected, standard input will be - connected to - <filename>/dev/null</filename>, - i.e. all read attempts by the process - will result in immediate EOF.</para> - - <para>If <option>tty</option> is - selected, standard input is connected - to a TTY (as configured by - <varname>TTYPath=</varname>, see - below) and the executed process - becomes the controlling process of the - terminal. If the terminal is already - being controlled by another process, - the executed process waits until the - current controlling process releases - the terminal.</para> - - <para><option>tty-force</option> is similar - to <option>tty</option>, but the - executed process is forcefully and - immediately made the controlling - process of the terminal, potentially - removing previous controlling - processes from the - terminal.</para> - - <para><option>tty-fail</option> is - similar to <option>tty</option> but if - the terminal already has a controlling - process start-up of the executed - process fails.</para> - - <para>The <option>socket</option> - option is only valid in - socket-activated services, and only - when the socket configuration file - (see - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details) specifies a single socket - only. If this option is set, standard - input will be connected to the socket - the service was activated from, which - is primarily useful for compatibility - with daemons designed for use with the - traditional - <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - daemon.</para> - - <para>This setting defaults to - <option>null</option>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>StandardOutput=</varname></term> - <listitem><para>Controls where file - descriptor 1 (STDOUT) of the executed - processes is connected to. Takes one - of <option>inherit</option>, - <option>null</option>, - <option>tty</option>, - <option>journal</option>, - <option>syslog</option>, - <option>kmsg</option>, - <option>journal+console</option>, - <option>syslog+console</option>, - <option>kmsg+console</option> or - <option>socket</option>.</para> - - <para><option>inherit</option> - duplicates the file descriptor of - standard input for standard - output.</para> - - <para><option>null</option> connects - standard output to - <filename>/dev/null</filename>, - i.e. everything written to it will be - lost.</para> - - <para><option>tty</option> connects - standard output to a tty (as - configured via - <varname>TTYPath=</varname>, see - below). If the TTY is used for output - only, the executed process will not - become the controlling process of the - terminal, and will not fail or wait - for other processes to release the - terminal.</para> - - <para><option>journal</option> - connects standard output with the - journal which is accessible via - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - Note that everything that is written - to syslog or kmsg (see below) is - implicitly stored in the journal as - well, the specific two options listed - below are hence supersets of this - one.</para> - - <para><option>syslog</option> connects - standard output to the <citerefentry - project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - system syslog service, in addition to - the journal. Note that the journal - daemon is usually configured to - forward everything it receives to - syslog anyway, in which case this - option is no different from - <option>journal</option>.</para> - - <para><option>kmsg</option> connects - standard output with the kernel log - buffer which is accessible via - <citerefentry - project='man-pages'><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - in addition to the journal. The - journal daemon might be configured to - send all logs to kmsg anyway, in which - case this option is no different from - <option>journal</option>.</para> - - <para><option>journal+console</option>, - <option>syslog+console</option> and - <option>kmsg+console</option> work in - a similar way as the three options - above but copy the output to the - system console as well.</para> - - <para><option>socket</option> connects - standard output to a socket acquired - via socket activation. The semantics - are similar to the same option of - <varname>StandardInput=</varname>.</para> - - <para>This setting defaults to the - value set with - <option>DefaultStandardOutput=</option> - in - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which defaults to - <option>journal</option>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>StandardError=</varname></term> - <listitem><para>Controls where file - descriptor 2 (STDERR) of the - executed processes is connected to. - The available options are identical to - those of - <varname>StandardOutput=</varname>, - with one exception: if set to - <option>inherit</option> the file - descriptor used for standard output is - duplicated for standard error. This - setting defaults to the value set with - <option>DefaultStandardError=</option> - in - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which defaults to - <option>inherit</option>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>TTYPath=</varname></term> - <listitem><para>Sets the terminal - device node to use if standard input, output, - or error are connected to a - TTY (see above). Defaults to - <filename>/dev/console</filename>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>TTYReset=</varname></term> - <listitem><para>Reset the terminal - device specified with - <varname>TTYPath=</varname> before and - after execution. Defaults to - <literal>no</literal>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>TTYVHangup=</varname></term> - <listitem><para>Disconnect all clients - which have opened the terminal device - specified with - <varname>TTYPath=</varname> - before and after execution. Defaults - to - <literal>no</literal>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>TTYVTDisallocate=</varname></term> - <listitem><para>If the terminal - device specified with - <varname>TTYPath=</varname> is a - virtual console terminal, try to - deallocate the TTY before and after - execution. This ensures that the - screen and scrollback buffer is - cleared. Defaults to - <literal>no</literal>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SyslogIdentifier=</varname></term> - <listitem><para>Sets the process name - to prefix log lines sent to the - logging system or the kernel log - buffer with. If not set, defaults to - the process name of the executed - process. This option is only useful - when - <varname>StandardOutput=</varname> or - <varname>StandardError=</varname> are - set to <option>syslog</option>, - <option>journal</option> or - <option>kmsg</option> (or to the same - settings in combination with - <option>+console</option>).</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SyslogFacility=</varname></term> - <listitem><para>Sets the syslog - facility to use when logging to - syslog. One of <option>kern</option>, - <option>user</option>, - <option>mail</option>, - <option>daemon</option>, - <option>auth</option>, - <option>syslog</option>, - <option>lpr</option>, - <option>news</option>, - <option>uucp</option>, - <option>cron</option>, - <option>authpriv</option>, - <option>ftp</option>, - <option>local0</option>, - <option>local1</option>, - <option>local2</option>, - <option>local3</option>, - <option>local4</option>, - <option>local5</option>, - <option>local6</option> or - <option>local7</option>. See - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details. This option is only - useful when - <varname>StandardOutput=</varname> or - <varname>StandardError=</varname> are - set to <option>syslog</option>. - Defaults to - <option>daemon</option>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>SyslogLevel=</varname></term> - <listitem><para>Default syslog level - to use when logging to syslog or the - kernel log buffer. One of - <option>emerg</option>, - <option>alert</option>, - <option>crit</option>, - <option>err</option>, - <option>warning</option>, - <option>notice</option>, - <option>info</option>, - <option>debug</option>. See - <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details. This option is only - useful when - <varname>StandardOutput=</varname> or - <varname>StandardError=</varname> are - set to <option>syslog</option> or - <option>kmsg</option>. Note that - individual lines output by the daemon - might be prefixed with a different log - level which can be used to override - the default log level specified - here. The interpretation of these - prefixes may be disabled with - <varname>SyslogLevelPrefix=</varname>, - see below. For details see - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - - Defaults to - <option>info</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SyslogLevelPrefix=</varname></term> - <listitem><para>Takes a boolean - argument. If true and - <varname>StandardOutput=</varname> or - <varname>StandardError=</varname> are - set to <option>syslog</option>, - <option>kmsg</option> or - <option>journal</option>, log lines - written by the executed process that - are prefixed with a log level will be - passed on to syslog with this log - level set but the prefix removed. If - set to false, the interpretation of - these prefixes is disabled and the - logged lines are passed on as-is. For - details about this prefixing see - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - Defaults to true.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TimerSlackNSec=</varname></term> - <listitem><para>Sets the timer slack - in nanoseconds for the executed - processes. The timer slack controls - the accuracy of wake-ups triggered by - timers. See - <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for more information. Note that in - contrast to most other time span - definitions this parameter takes an - integer value in nano-seconds if no - unit is specified. The usual time - units are understood - too.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>LimitCPU=</varname></term> - <term><varname>LimitFSIZE=</varname></term> - <term><varname>LimitDATA=</varname></term> - <term><varname>LimitSTACK=</varname></term> - <term><varname>LimitCORE=</varname></term> - <term><varname>LimitRSS=</varname></term> - <term><varname>LimitNOFILE=</varname></term> - <term><varname>LimitAS=</varname></term> - <term><varname>LimitNPROC=</varname></term> - <term><varname>LimitMEMLOCK=</varname></term> - <term><varname>LimitLOCKS=</varname></term> - <term><varname>LimitSIGPENDING=</varname></term> - <term><varname>LimitMSGQUEUE=</varname></term> - <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. Use the string - <varname>infinity</varname> to - configure no limit on a specific - resource.</para></listitem> - - <table> - <title>Limit directives and their equivalent with ulimit</title> - - <tgroup cols='2'> - <colspec colname='directive' /> - <colspec colname='equivalent' /> - <thead> - <row> - <entry>Directive</entry> - <entry>ulimit equivalent</entry> - </row> - </thead> - <tbody> - <row> - <entry>LimitCPU</entry> - <entry>ulimit -t</entry> - </row> - <row> - <entry>LimitFSIZE</entry> - <entry>ulimit -f</entry> - </row> - <row> - <entry>LimitDATA</entry> - <entry>ulimit -d</entry> - </row> - <row> - <entry>LimitSTACK</entry> - <entry>ulimit -s</entry> - </row> - <row> - <entry>LimitCORE</entry> - <entry>ulimit -c</entry> - </row> - <row> - <entry>LimitRSS</entry> - <entry>ulimit -m</entry> - </row> - <row> - <entry>LimitNOFILE</entry> - <entry>ulimit -n</entry> - </row> - <row> - <entry>LimitAS</entry> - <entry>ulimit -v</entry> - </row> - <row> - <entry>LimitNPROC</entry> - <entry>ulimit -u</entry> - </row> - <row> - <entry>LimitMEMLOCK</entry> - <entry>ulimit -l</entry> - </row> - <row> - <entry>LimitLOCKS</entry> - <entry>ulimit -x</entry> - </row> - <row> - <entry>LimitSIGPENDING</entry> - <entry>ulimit -i</entry> - </row> - <row> - <entry>LimitMSGQUEUE</entry> - <entry>ulimit -q</entry> - </row> - <row> - <entry>LimitNICE</entry> - <entry>ulimit -e</entry> - </row> - <row> - <entry>LimitRTPRIO</entry> - <entry>ulimit -r</entry> - </row> - <row> - <entry>LimitRTTIME</entry> - <entry>No equivalent</entry> - </row> - </tbody> - </tgroup> - </table> - </varlistentry> - - <varlistentry> - <term><varname>PAMName=</varname></term> - <listitem><para>Sets the PAM service - name to set up a session as. If set, - the executed process will be - registered as a PAM session under the - specified service name. This is only - useful in conjunction with the - <varname>User=</varname> setting. If - not set, no PAM session will be opened - for the executed processes. See - <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <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><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> - </varlistentry> - - <varlistentry> - <term><varname>SecureBits=</varname></term> - <listitem><para>Controls the secure - bits set for the executed process. - Takes a space-separated combination of - options from the following list: - <option>keep-caps</option>, - <option>keep-caps-locked</option>, - <option>no-setuid-fixup</option>, - <option>no-setuid-fixup-locked</option>, - <option>noroot</option>, and - <option>noroot-locked</option>. This - option may appear more than once in - which case the secure bits are ORed. - If the empty string is assigned to - this option, the bits are reset to 0. - See <citerefentry - project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details.</para></listitem> - </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><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> - - <listitem><para>Sets up a new file - system namespace for executed - processes. These options may be used - to limit access a process might have - to the main file system - hierarchy. Each setting takes a - space-separated list of absolute - directory paths. Directories listed in - <varname>ReadWriteDirectories=</varname> - are accessible from within the - namespace with the same access rights - as from outside. Directories listed in - <varname>ReadOnlyDirectories=</varname> - are accessible for reading only, - writing will be refused even if the - usual file access controls would - permit this. Directories listed in - <varname>InaccessibleDirectories=</varname> - will be made 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 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 specific list is reset, - and all prior assignments have no - effect.</para> - <para>Paths in - <varname>ReadOnlyDirectories=</varname> - and - <varname>InaccessibleDirectories=</varname> - may be prefixed with - <literal>-</literal>, in which case - they will be ignored when they do not - exist. Note that using this - setting will disconnect propagation of - mounts from the service to the host - (propagation in the opposite direction - continues to work). This means that - this setting may not be used for - services which shall be able to - install mount points in the main mount - namespace.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PrivateTmp=</varname></term> - - <listitem><para>Takes a boolean - argument. If true, sets up a new file - system namespace for the executed - processes and mounts private - <filename>/tmp</filename> and - <filename>/var/tmp</filename> - directories inside it that is not - shared by processes outside of the - namespace. This is useful to secure - access to temporary files of the - process, but makes sharing between - processes via - <filename>/tmp</filename> or - <filename>/var/tmp</filename> - impossible. If this is enabled, all - temporary files created by a service - in these directories will be removed - after the service is stopped. Defaults - to false. It is possible to run two or - more units within the same private - <filename>/tmp</filename> and - <filename>/var/tmp</filename> - namespace by using the - <varname>JoinsNamespaceOf=</varname> - directive, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Note that using this - setting will disconnect propagation of - mounts from the service to the host - (propagation in the opposite direction - continues to work). This means that - this setting may not be used for - services which shall be able to install - mount points in the main mount - namespace.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PrivateDevices=</varname></term> - - <listitem><para>Takes a boolean - argument. If true, sets up a new /dev - namespace for the executed processes - and only adds API pseudo devices such - as <filename>/dev/null</filename>, - <filename>/dev/zero</filename> or - <filename>/dev/random</filename> (as - well as the pseudo TTY subsystem) to - it, but no physical devices such as - <filename>/dev/sda</filename>. This is - useful to securely turn off physical - device access by the executed - process. Defaults to false. Enabling - this option will also remove - <constant>CAP_MKNOD</constant> from - the capability bounding set for the - unit (see above), and set - <varname>DevicePolicy=closed</varname> - (see - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). Note that using this - setting will disconnect propagation of - mounts from the service to the host - (propagation in the opposite direction - continues to work). This means that - this setting may not be used for - services which shall be able to - install mount points in the main mount - namespace.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PrivateNetwork=</varname></term> - - <listitem><para>Takes a boolean - argument. If true, sets up a new - network namespace for the executed - processes and configures only the - loopback network device - <literal>lo</literal> inside it. No - other network devices will be - available to the executed process. - This is useful to securely turn off - network access by the executed - process. Defaults to false. It is - possible to run two or more units - within the same private network - namespace by using the - <varname>JoinsNamespaceOf=</varname> - directive, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Note that this option - will disconnect all socket families - from the host, this includes - AF_NETLINK and AF_UNIX. The latter has - the effect that AF_UNIX sockets in the - abstract socket namespace will become - unavailable to the processes (however, - those located in the file system will - continue to be - accessible).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ProtectSystem=</varname></term> - - <listitem><para>Takes a boolean - argument or - <literal>full</literal>. If true, - mounts the <filename>/usr</filename> - and <filename>/boot</filename> - directories read-only for processes - invoked by this unit. If set to - <literal>full</literal>, the - <filename>/etc</filename> directory is - mounted read-only, too. This setting - ensures that any modification of the - vendor supplied operating system (and - optionally its configuration) is - prohibited for the service. It is - recommended to enable this setting for - all long-running services, unless they - are involved with system updates or - need to modify the operating system in - other ways. Note however that - processes retaining the CAP_SYS_ADMIN - capability can undo the effect of this - setting. This setting is hence - particularly useful for daemons which - have this capability removed, for - example with - <varname>CapabilityBoundingSet=</varname>. Defaults - to off.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ProtectHome=</varname></term> - - <listitem><para>Takes a boolean - argument or - <literal>read-only</literal>. If true, - the directories - <filename>/home</filename> and - <filename>/run/user</filename> are - made inaccessible and empty for - processes invoked by this unit. If set - to <literal>read-only</literal>, the - two directories are made read-only - instead. It is recommended to enable - this setting for all long-running - services (in particular network-facing - ones), to ensure they cannot get access - to private user data, unless the - services actually require access to - the user's private data. Note however - that processes retaining the - CAP_SYS_ADMIN capability can undo the - effect of this setting. This setting - is hence particularly useful for - daemons which have this capability - removed, for example with - <varname>CapabilityBoundingSet=</varname>. Defaults - to off.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>MountFlags=</varname></term> - - <listitem><para>Takes a mount - propagation flag: - <option>shared</option>, - <option>slave</option> or - <option>private</option>, which - control whether mounts in the file - system namespace set up for this - unit's processes will receive or - propagate mounts or unmounts. See - <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. Defaults to - <option>shared</option>. Use - <option>shared</option> to ensure that - mounts and unmounts are propagated - from the host to the container and - vice versa. Use <option>slave</option> - to run processes so that none of their - mounts and unmounts will propagate to - the host. Use <option>private</option> - to also ensure that no mounts and - unmounts from the host will propagate - into the unit processes' - namespace. Note that - <option>slave</option> means that file - systems mounted on the host might stay - mounted continuously in the unit's - namespace, and thus keep the device - busy. Note that the file system - namespace related options - (<varname>PrivateTmp=</varname>, - <varname>PrivateDevices=</varname>, - <varname>ProtectSystem=</varname>, - <varname>ProtectHome=</varname>, - <varname>ReadOnlyDirectories=</varname>, - <varname>InaccessibleDirectories=</varname> - and - <varname>ReadWriteDirectories=</varname>) - require that mount and unmount - propagation from the unit's file - system namespace is disabled, and - hence downgrade - <option>shared</option> to - <option>slave</option>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>UtmpIdentifier=</varname></term> - - <listitem><para>Takes a four - character identifier string for an - utmp/wtmp entry for this service. This - should only be set for services such - as <command>getty</command> - implementations where utmp/wtmp - entries must be created and cleared - before and after execution. If the - configured string is longer than four - characters, it is truncated and the - terminal four characters are - used. This setting interprets %I style - string replacements. This setting is - unset by default, i.e. no utmp/wtmp - entries are created or cleaned up for - this service.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SELinuxContext=</varname></term> - - <listitem><para>Set the SELinux - security context of the executed - process. If set, this will override - the automated domain - transition. However, the policy still - needs to authorize the transition. This - directive is ignored if SELinux is - disabled. If prefixed by - <literal>-</literal>, all errors will - be ignored. See - <citerefentry><refentrytitle>setexeccon</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>AppArmorProfile=</varname></term> - - <listitem><para>Takes a profile name as argument. - The process executed by the unit will switch to - this profile when started. Profiles must already - be loaded in the kernel, or the unit will fail. - This result in a non operation if AppArmor is not - enabled. If prefixed by <literal>-</literal>, all errors - will be ignored. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SmackProcessLabel=</varname></term> - - <listitem><para>Takes a - <option>SMACK64</option> security - label as argument. The process - executed by the unit will be started - under this label and SMACK will decide - whether the processes is allowed to - run or not based on it. The process - will continue to run under the label - specified here unless the executable - has its own - <option>SMACK64EXEC</option> label, in - which case the process will transition - to run under that label. When not - specified, the label that systemd is - running under is used. This directive - is ignored if SMACK is - disabled.</para> - - <para>The value may be prefixed by - <literal>-</literal>, in which case - all errors will be ignored. An empty - value may be specified to unset - previous assignments.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>IgnoreSIGPIPE=</varname></term> - - <listitem><para>Takes a boolean - argument. If true, causes <constant>SIGPIPE</constant> to be - ignored in the executed - process. Defaults to true because - <constant>SIGPIPE</constant> generally is useful only in - shell pipelines.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>NoNewPrivileges=</varname></term> - - <listitem><para>Takes a boolean - argument. If true, ensures that the - service process and all its children - can never gain new privileges. This - option is more powerful than the respective - secure bits flags (see above), as it - also prohibits UID changes of any - kind. This is the simplest, most - effective way to ensure that a process - and its children can never elevate - privileges again.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SystemCallFilter=</varname></term> - - <listitem><para>Takes a - space-separated list of system call - names. If this setting is used, all - system calls executed by the unit - processes except for the listed ones - will result in immediate process - termination with the - <constant>SIGSYS</constant> signal - (whitelisting). If the first character - of the list is <literal>~</literal>, - the effect is inverted: only the - listed system calls will result in - immediate process termination - (blacklisting). If running in user - mode and this option is used, - <varname>NoNewPrivileges=yes</varname> - is implied. This feature makes use of the - Secure Computing Mode 2 interfaces of - the kernel ('seccomp filtering') and - is useful for enforcing a minimal - sandboxing environment. Note that the - <function>execve</function>, - <function>rt_sigreturn</function>, - <function>sigreturn</function>, - <function>exit_group</function>, - <function>exit</function> system calls - are implicitly whitelisted and do not - need to be listed explicitly. This - option may be specified more than once - in which case the filter masks are - merged. If the empty string is - assigned, the filter is reset, all - prior assignments will have no - effect.</para> - - <para>If you specify both types of - this option (i.e. whitelisting and - blacklisting), the first encountered - will take precedence and will dictate - the default action (termination or - approval of a system call). Then the - next occurrences of this option will - add or delete the listed system calls - from the set of the filtered system - calls, depending of its type and the - default action. (For example, if you have started - with a whitelisting of - <function>read</function> and - <function>write</function>, and right - after it add a blacklisting of - <function>write</function>, then - <function>write</function> will be - removed from the set.) - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SystemCallErrorNumber=</varname></term> - - <listitem><para>Takes an - <literal>errno</literal> error number - name to return when the system call - filter configured with - <varname>SystemCallFilter=</varname> - is triggered, instead of terminating - the process immediately. Takes an - error name such as - <constant>EPERM</constant>, - <constant>EACCES</constant> or - <constant>EUCLEAN</constant>. When this - setting is not used, or when the empty - string is assigned, the process will be - terminated immediately when the filter - is triggered.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SystemCallArchitectures=</varname></term> - - <listitem><para>Takes a space - separated list of architecture - identifiers to include in the system - call filter. The known architecture - identifiers are - <constant>x86</constant>, - <constant>x86-64</constant>, - <constant>x32</constant>, - <constant>arm</constant> as well as - the special identifier - <constant>native</constant>. Only - system calls of the specified - architectures will be permitted to - processes of this unit. This is an - effective way to disable compatibility - with non-native architectures for - processes, for example to prohibit - execution of 32-bit x86 binaries on - 64-bit x86-64 systems. The special - <constant>native</constant> identifier - implicitly maps to the native - architecture of the system (or more - strictly: to the architecture the - system manager is compiled for). If - running in user mode and this option - is used, - <varname>NoNewPrivileges=yes</varname> - is implied. Note that setting this - option to a non-empty list implies - that <constant>native</constant> is - included too. By default, this option - is set to the empty list, i.e. no - architecture system call filtering is - applied.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RestrictAddressFamilies=</varname></term> - - <listitem><para>Restricts the set of - socket address families accessible to - the processes of this unit. Takes a - space-separated list of address family - names to whitelist, such as - <constant>AF_UNIX</constant>, - <constant>AF_INET</constant> or - <constant>AF_INET6</constant>. When - prefixed with <constant>~</constant> - the listed address families will be - applied as blacklist, otherwise as - whitelist. Note that this restricts - access to the - <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call only. Sockets passed into - the process by other means (for - example, by using socket activation - with socket units, see - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>) - are unaffected. Also, sockets created - with <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 default, no - restriction applies, all address - families are accessible to - processes. If assigned the empty - string, any previous list changes are - undone.</para> - - <para>Use this option to limit - exposure of processes to remote - systems, in particular via exotic - network protocols. Note that in most - cases, the local - <constant>AF_UNIX</constant> address - family should be included in the - configured whitelist as it is - frequently used for local - communication, including for - <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry> - logging.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Personality=</varname></term> - - <listitem><para>Controls which - kernel architecture - <citerefentry><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> - </varlistentry> - - <varlistentry> - <term><varname>RuntimeDirectory=</varname></term> - <term><varname>RuntimeDirectoryMode=</varname></term> - - <listitem><para>Takes a list of - directory names. If set, one or more - directories by the specified names - will be created below - <filename>/run</filename> (for system - services) or below - <varname>$XDG_RUNTIME_DIR</varname> - (for user services) when the unit is - started, and removed when the unit is - stopped. The directories will have the - access mode specified in - <varname>RuntimeDirectoryMode=</varname>, - and will be owned by the user and - group specified in - <varname>User=</varname> and - <varname>Group=</varname>. Use this to - manage one or more runtime directories - of the unit and bind their lifetime to - the daemon runtime. The specified - directory names must be relative, and - may not include a - <literal>/</literal>, i.e. must refer - to simple directories to create or - remove. This is particularly useful - for unprivileged daemons that cannot - create runtime directories in - <filename>/run</filename> due to lack - of privileges, and to make sure the - runtime directory is cleaned up - automatically after use. For runtime - directories that require more complex - or different configuration or lifetime - guarantees, please consider using - <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Environment variables in spawned processes</title> - - <para>Processes started by the system are executed in - a clean environment in which select variables - listed below are set. System processes started by systemd - do not inherit variables from PID 1, but processes - started by user systemd instances inherit all - environment variables from the user systemd instance. - </para> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$PATH</varname></term> - - <listitem><para>Colon-separated list - of directories to use when launching - executables. Systemd uses a fixed - value of - <filename>/usr/local/sbin</filename>:<filename>/usr/local/bin</filename>:<filename>/usr/sbin</filename>:<filename>/usr/bin</filename>:<filename>/sbin</filename>:<filename>/bin</filename>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$LANG</varname></term> - - <listitem><para>Locale. Can be set in - <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - or on the kernel command line (see - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>). - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$USER</varname></term> - <term><varname>$LOGNAME</varname></term> - <term><varname>$HOME</varname></term> - <term><varname>$SHELL</varname></term> - - <listitem><para>User name (twice), home - directory, and the login shell. - The variables are set for the units that - have <varname>User=</varname> set, - which includes user - <command>systemd</command> instances. - See - <citerefentry><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_RUNTIME_DIR</varname></term> - - <listitem><para>The directory for volatile - state. Set for the user <command>systemd</command> - instance, and also in user sessions. - See - <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_SESSION_ID</varname></term> - <term><varname>$XDG_SEAT</varname></term> - <term><varname>$XDG_VTNR</varname></term> - - <listitem><para>The identifier of the - session, the seat name, and - virtual terminal of the session. Set - by - <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for login sessions. - <varname>$XDG_SEAT</varname> and - <varname>$XDG_VTNR</varname> will - only be set when attached to a seat and a - tty.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$MAINPID</varname></term> - - <listitem><para>The PID of the units - main process if it is known. This is - only set for control processes as - invoked by - <varname>ExecReload=</varname> and - similar. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$MANAGERPID</varname></term> - - <listitem><para>The PID of the user - <command>systemd</command> instance, - set for processes spawned by it. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$LISTEN_FDS</varname></term> - <term><varname>$LISTEN_PID</varname></term> - - <listitem><para>Information about file - descriptors passed to a service for - socket activation. See - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$TERM</varname></term> - - <listitem><para>Terminal type, set - only for units connected to a terminal - (<varname>StandardInput=tty</varname>, - <varname>StandardOutput=tty</varname>, - or - <varname>StandardError=tty</varname>). - See - <citerefentry project='man-pages'><refentrytitle>termcap</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - </variablelist> - - <para>Additional variables may be configured by the - following means: for processes spawned in specific - units, use the <varname>Environment=</varname> and - <varname>EnvironmentFile=</varname> options above; to - specify variables globally, use - <varname>DefaultEnvironment=</varname> (see - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) - or the kernel option - <varname>systemd.setenv=</varname> (see - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>). Additional - variables may also be set through PAM, - cf. <citerefentry project='man-pages'><refentrytitle>pam_env</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>exec</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd.exec</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.exec</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.exec</refname> + <refpurpose>Execution environment configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>service</replaceable>.service</filename>, + <filename><replaceable>socket</replaceable>.socket</filename>, + <filename><replaceable>mount</replaceable>.mount</filename>, + <filename><replaceable>swap</replaceable>.swap</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Unit configuration files for services, sockets, mount + points, and swap devices share a subset of configuration options + which define the execution environment of spawned + processes.</para> + + <para>This man page lists the configuration options shared by + these four unit types. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files, and + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + and + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information on the specific unit configuration files. The + execution specific configuration options are configured in the + [Service], [Socket], [Mount], or [Swap] sections, depending on the + unit type.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>WorkingDirectory=</varname></term> + + <listitem><para>Takes an absolute directory path. Sets the + working directory for executed processes. If not set, defaults + to the root directory when systemd is running as a system + instance and the respective user's home directory if run as + user.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RootDirectory=</varname></term> + + <listitem><para>Takes an absolute directory path. Sets the + root directory for executed processes, with the + <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system call. If this is used, it must be ensured that the + process and all its auxiliary files are available in the + <function>chroot()</function> jail.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>User=</varname></term> + <term><varname>Group=</varname></term> + + <listitem><para>Sets the Unix user or group that the processes + are executed as, respectively. Takes a single user or group + name or ID as argument. If no group is set, the default group + of the user is chosen.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SupplementaryGroups=</varname></term> + + <listitem><para>Sets the supplementary Unix groups the + processes are executed as. This takes a space-separated list + of group names or IDs. This option may be specified more than + once in which case all listed groups are set as supplementary + groups. When the empty string is assigned the list of + supplementary groups is reset, and all assignments prior to + this one will have no effect. In any way, this option does not + override, but extends the list of supplementary groups + configured in the system group database for the + user.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Nice=</varname></term> + + <listitem><para>Sets the default nice level (scheduling + priority) for executed processes. Takes an integer between -20 + (highest priority) and 19 (lowest priority). See + <citerefentry><refentrytitle>setpriority</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>OOMScoreAdjust=</varname></term> + + <listitem><para>Sets the adjustment level for the + Out-Of-Memory killer for executed processes. Takes an integer + between -1000 (to disable OOM killing for this process) and + 1000 (to make killing of this process under memory pressure + very likely). See <ulink + url="https://www.kernel.org/doc/Documentation/filesystems/proc.txt">proc.txt</ulink> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOSchedulingClass=</varname></term> + + <listitem><para>Sets the IO scheduling class for executed + processes. Takes an integer between 0 and 3 or one of the + strings <option>none</option>, <option>realtime</option>, + <option>best-effort</option> or <option>idle</option>. See + <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IOSchedulingPriority=</varname></term> + + <listitem><para>Sets the IO scheduling priority for executed + processes. Takes an integer between 0 (highest priority) and 7 + (lowest priority). The available priorities depend on the + selected IO scheduling class (see above). See + <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUSchedulingPolicy=</varname></term> + + <listitem><para>Sets the CPU scheduling policy for executed + processes. Takes one of + <option>other</option>, + <option>batch</option>, + <option>idle</option>, + <option>fifo</option> or + <option>rr</option>. See + <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUSchedulingPriority=</varname></term> + + <listitem><para>Sets the CPU scheduling priority for executed + processes. The available priority range depends on the + selected CPU scheduling policy (see above). For real-time + scheduling policies an integer between 1 (lowest priority) and + 99 (highest priority) can be used. See + <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUSchedulingResetOnFork=</varname></term> + + <listitem><para>Takes a boolean argument. If true, elevated + CPU scheduling priorities and policies will be reset when the + executed processes fork, and can hence not leak into child + processes. See + <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. Defaults to false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPUAffinity=</varname></term> + + <listitem><para>Controls the CPU affinity of the executed + processes. Takes a space-separated list of CPU indices. This + option may be specified more than once in which case the + specified CPU affinity masks are merged. If the empty string + is assigned, the mask is reset, all assignments prior to this + will have no effect. See + <citerefentry><refentrytitle>sched_setaffinity</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>UMask=</varname></term> + + <listitem><para>Controls the file mode creation mask. Takes an + access mode in octal notation. See + <citerefentry><refentrytitle>umask</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. Defaults to 0022.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Environment=</varname></term> + + <listitem><para>Sets environment variables for executed + processes. Takes a space-separated list of variable + assignments. This option may be specified more than once in + which case all listed variables will be set. If the same + variable is set twice, the later setting will override the + earlier setting. If the empty string is assigned to this + option, the list of environment variables is reset, all prior + assignments have no effect. Variable expansion is not + performed inside the strings, however, specifier expansion is + possible. The $ character has no special meaning. If you need + to assign a value containing spaces to a variable, use double + quotes (") for the assignment.</para> + + <para>Example: + <programlisting>Environment="VAR1=word1 word2" VAR2=word3 "VAR3=$word 5 6"</programlisting> + gives three variables <literal>VAR1</literal>, + <literal>VAR2</literal>, <literal>VAR3</literal> + with the values <literal>word1 word2</literal>, + <literal>word3</literal>, <literal>$word 5 6</literal>. + </para> + + <para> + See + <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about environment variables.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>EnvironmentFile=</varname></term> + <listitem><para>Similar to <varname>Environment=</varname> but + reads the environment variables from a text file. The text + file should contain new-line-separated variable assignments. + Empty lines and lines starting with ; or # will be ignored, + which may be used for commenting. A line ending with a + backslash will be concatenated with the following one, + allowing multiline variable definitions. The parser strips + leading and trailing whitespace from the values of + assignments, unless you use double quotes (").</para> + + <para>The argument passed should be an absolute filename or + wildcard expression, optionally prefixed with + <literal>-</literal>, which indicates that if the file does + not exist, it will not be read and no error or warning message + is logged. This option may be specified more than once in + which case all specified files are read. If the empty string + is assigned to this option, the list of file to read is reset, + all prior assignments have no effect.</para> + + <para>The files listed with this directive will be read + shortly before the process is executed (more specifically, + after all processes from a previous unit state terminated. + This means you can generate these files in one unit state, and + read it with this option in the next). Settings from these + files override settings made with + <varname>Environment=</varname>. If the same variable is set + twice from these files, the files will be read in the order + they are specified and the later setting will override the + earlier setting.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StandardInput=</varname></term> + <listitem><para>Controls where file descriptor 0 (STDIN) of + the executed processes is connected to. Takes one of + <option>null</option>, + <option>tty</option>, + <option>tty-force</option>, + <option>tty-fail</option> or + <option>socket</option>.</para> + + <para>If <option>null</option> is selected, standard input + will be connected to <filename>/dev/null</filename>, i.e. all + read attempts by the process will result in immediate + EOF.</para> + + <para>If <option>tty</option> is selected, standard input is + connected to a TTY (as configured by + <varname>TTYPath=</varname>, see below) and the executed + process becomes the controlling process of the terminal. If + the terminal is already being controlled by another process, + the executed process waits until the current controlling + process releases the terminal.</para> + + <para><option>tty-force</option> is similar to + <option>tty</option>, but the executed process is forcefully + and immediately made the controlling process of the terminal, + potentially removing previous controlling processes from the + terminal.</para> + + <para><option>tty-fail</option> is similar to + <option>tty</option> but if the terminal already has a + controlling process start-up of the executed process + fails.</para> + + <para>The <option>socket</option> option is only valid in + socket-activated services, and only when the socket + configuration file (see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) specifies a single socket only. If this option is + set, standard input will be connected to the socket the + service was activated from, which is primarily useful for + compatibility with daemons designed for use with the + traditional + <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + daemon.</para> + + <para>This setting defaults to + <option>null</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>StandardOutput=</varname></term> + <listitem><para>Controls where file descriptor 1 (STDOUT) of + the executed processes is connected to. Takes one of + <option>inherit</option>, + <option>null</option>, + <option>tty</option>, + <option>journal</option>, + <option>syslog</option>, + <option>kmsg</option>, + <option>journal+console</option>, + <option>syslog+console</option>, + <option>kmsg+console</option> or + <option>socket</option>.</para> + + <para><option>inherit</option> duplicates the file descriptor + of standard input for standard output.</para> + + <para><option>null</option> connects standard output to + <filename>/dev/null</filename>, i.e. everything written to it + will be lost.</para> + + <para><option>tty</option> connects standard output to a tty + (as configured via <varname>TTYPath=</varname>, see below). If + the TTY is used for output only, the executed process will not + become the controlling process of the terminal, and will not + fail or wait for other processes to release the + terminal.</para> + + <para><option>journal</option> connects standard output with + the journal which is accessible via + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + Note that everything that is written to syslog or kmsg (see + below) is implicitly stored in the journal as well, the + specific two options listed below are hence supersets of this + one.</para> + + <para><option>syslog</option> connects standard output to the + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + system syslog service, in addition to the journal. Note that + the journal daemon is usually configured to forward everything + it receives to syslog anyway, in which case this option is no + different from <option>journal</option>.</para> + + <para><option>kmsg</option> connects standard output with the + kernel log buffer which is accessible via + <citerefentry project='man-pages'><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + in addition to the journal. The journal daemon might be + configured to send all logs to kmsg anyway, in which case this + option is no different from <option>journal</option>.</para> + + <para><option>journal+console</option>, + <option>syslog+console</option> and + <option>kmsg+console</option> work in a similar way as the + three options above but copy the output to the system console + as well.</para> + + <para><option>socket</option> connects standard output to a + socket acquired via socket activation. The semantics are + similar to the same option of + <varname>StandardInput=</varname>.</para> + + <para>This setting defaults to the value set with + <option>DefaultStandardOutput=</option> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which defaults to <option>journal</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>StandardError=</varname></term> + <listitem><para>Controls where file descriptor 2 (STDERR) of + the executed processes is connected to. The available options + are identical to those of <varname>StandardOutput=</varname>, + with one exception: if set to <option>inherit</option> the + file descriptor used for standard output is duplicated for + standard error. This setting defaults to the value set with + <option>DefaultStandardError=</option> in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which defaults to <option>inherit</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>TTYPath=</varname></term> + <listitem><para>Sets the terminal device node to use if + standard input, output, or error are connected to a TTY (see + above). Defaults to + <filename>/dev/console</filename>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>TTYReset=</varname></term> + <listitem><para>Reset the terminal device specified with + <varname>TTYPath=</varname> before and after execution. + Defaults to <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>TTYVHangup=</varname></term> + <listitem><para>Disconnect all clients which have opened the + terminal device specified with <varname>TTYPath=</varname> + before and after execution. Defaults to + <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>TTYVTDisallocate=</varname></term> + <listitem><para>If the terminal device specified with + <varname>TTYPath=</varname> is a virtual console terminal, try + to deallocate the TTY before and after execution. This ensures + that the screen and scrollback buffer is cleared. Defaults to + <literal>no</literal>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SyslogIdentifier=</varname></term> + <listitem><para>Sets the process name to prefix log lines sent + to the logging system or the kernel log buffer with. If not + set, defaults to the process name of the executed process. + This option is only useful when + <varname>StandardOutput=</varname> or + <varname>StandardError=</varname> are set to + <option>syslog</option>, <option>journal</option> or + <option>kmsg</option> (or to the same settings in combination + with <option>+console</option>).</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SyslogFacility=</varname></term> + <listitem><para>Sets the syslog facility to use when logging + to syslog. One of <option>kern</option>, + <option>user</option>, <option>mail</option>, + <option>daemon</option>, <option>auth</option>, + <option>syslog</option>, <option>lpr</option>, + <option>news</option>, <option>uucp</option>, + <option>cron</option>, <option>authpriv</option>, + <option>ftp</option>, <option>local0</option>, + <option>local1</option>, <option>local2</option>, + <option>local3</option>, <option>local4</option>, + <option>local5</option>, <option>local6</option> or + <option>local7</option>. See + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details. This option is only useful when + <varname>StandardOutput=</varname> or + <varname>StandardError=</varname> are set to + <option>syslog</option>. Defaults to + <option>daemon</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>SyslogLevel=</varname></term> + <listitem><para>Default syslog level to use when logging to + syslog or the kernel log buffer. One of + <option>emerg</option>, + <option>alert</option>, + <option>crit</option>, + <option>err</option>, + <option>warning</option>, + <option>notice</option>, + <option>info</option>, + <option>debug</option>. See + <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details. This option is only useful when + <varname>StandardOutput=</varname> or + <varname>StandardError=</varname> are set to + <option>syslog</option> or <option>kmsg</option>. Note that + individual lines output by the daemon might be prefixed with a + different log level which can be used to override the default + log level specified here. The interpretation of these prefixes + may be disabled with <varname>SyslogLevelPrefix=</varname>, + see below. For details see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + + Defaults to + <option>info</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SyslogLevelPrefix=</varname></term> + <listitem><para>Takes a boolean argument. If true and + <varname>StandardOutput=</varname> or + <varname>StandardError=</varname> are set to + <option>syslog</option>, <option>kmsg</option> or + <option>journal</option>, log lines written by the executed + process that are prefixed with a log level will be passed on + to syslog with this log level set but the prefix removed. If + set to false, the interpretation of these prefixes is disabled + and the logged lines are passed on as-is. For details about + this prefixing see + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Defaults to true.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimerSlackNSec=</varname></term> + <listitem><para>Sets the timer slack in nanoseconds for the + executed processes. The timer slack controls the accuracy of + wake-ups triggered by timers. See + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information. Note that in contrast to most other time + span definitions this parameter takes an integer value in + nano-seconds if no unit is specified. The usual time units are + understood too.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LimitCPU=</varname></term> + <term><varname>LimitFSIZE=</varname></term> + <term><varname>LimitDATA=</varname></term> + <term><varname>LimitSTACK=</varname></term> + <term><varname>LimitCORE=</varname></term> + <term><varname>LimitRSS=</varname></term> + <term><varname>LimitNOFILE=</varname></term> + <term><varname>LimitAS=</varname></term> + <term><varname>LimitNPROC=</varname></term> + <term><varname>LimitMEMLOCK=</varname></term> + <term><varname>LimitLOCKS=</varname></term> + <term><varname>LimitSIGPENDING=</varname></term> + <term><varname>LimitMSGQUEUE=</varname></term> + <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. Use the string <varname>infinity</varname> to + configure no limit on a specific resource.</para></listitem> + + <table> + <title>Limit directives and their equivalent with ulimit</title> + + <tgroup cols='2'> + <colspec colname='directive' /> + <colspec colname='equivalent' /> + <thead> + <row> + <entry>Directive</entry> + <entry>ulimit equivalent</entry> + </row> + </thead> + <tbody> + <row> + <entry>LimitCPU</entry> + <entry>ulimit -t</entry> + </row> + <row> + <entry>LimitFSIZE</entry> + <entry>ulimit -f</entry> + </row> + <row> + <entry>LimitDATA</entry> + <entry>ulimit -d</entry> + </row> + <row> + <entry>LimitSTACK</entry> + <entry>ulimit -s</entry> + </row> + <row> + <entry>LimitCORE</entry> + <entry>ulimit -c</entry> + </row> + <row> + <entry>LimitRSS</entry> + <entry>ulimit -m</entry> + </row> + <row> + <entry>LimitNOFILE</entry> + <entry>ulimit -n</entry> + </row> + <row> + <entry>LimitAS</entry> + <entry>ulimit -v</entry> + </row> + <row> + <entry>LimitNPROC</entry> + <entry>ulimit -u</entry> + </row> + <row> + <entry>LimitMEMLOCK</entry> + <entry>ulimit -l</entry> + </row> + <row> + <entry>LimitLOCKS</entry> + <entry>ulimit -x</entry> + </row> + <row> + <entry>LimitSIGPENDING</entry> + <entry>ulimit -i</entry> + </row> + <row> + <entry>LimitMSGQUEUE</entry> + <entry>ulimit -q</entry> + </row> + <row> + <entry>LimitNICE</entry> + <entry>ulimit -e</entry> + </row> + <row> + <entry>LimitRTPRIO</entry> + <entry>ulimit -r</entry> + </row> + <row> + <entry>LimitRTTIME</entry> + <entry>No equivalent</entry> + </row> + </tbody> + </tgroup> + </table> + </varlistentry> + + <varlistentry> + <term><varname>PAMName=</varname></term> + <listitem><para>Sets the PAM service name to set up a session + as. If set, the executed process will be registered as a PAM + session under the specified service name. This is only useful + in conjunction with the <varname>User=</varname> setting. If + not set, no PAM session will be opened for the executed + processes. See + <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <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><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> + </varlistentry> + + <varlistentry> + <term><varname>SecureBits=</varname></term> + <listitem><para>Controls the secure bits set for the executed + process. Takes a space-separated combination of options from + the following list: + <option>keep-caps</option>, + <option>keep-caps-locked</option>, + <option>no-setuid-fixup</option>, + <option>no-setuid-fixup-locked</option>, + <option>noroot</option>, and + <option>noroot-locked</option>. + This option may appear more than once in which case the secure + bits are ORed. If the empty string is assigned to this option, + the bits are reset to 0. See + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.</para></listitem> + </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><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> + + <listitem><para>Sets up a new file system namespace for + executed processes. These options may be used to limit access + a process might have to the main file system hierarchy. Each + setting takes a space-separated list of absolute directory + paths. Directories listed in + <varname>ReadWriteDirectories=</varname> are accessible from + within the namespace with the same access rights as from + outside. Directories listed in + <varname>ReadOnlyDirectories=</varname> are accessible for + reading only, writing will be refused even if the usual file + access controls would permit this. Directories listed in + <varname>InaccessibleDirectories=</varname> will be made + 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 + 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 + specific list is reset, and all prior assignments have no + effect.</para> + <para>Paths in + <varname>ReadOnlyDirectories=</varname> + and + <varname>InaccessibleDirectories=</varname> + may be prefixed with + <literal>-</literal>, in which case + they will be ignored when they do not + exist. Note that using this + setting will disconnect propagation of + mounts from the service to the host + (propagation in the opposite direction + continues to work). This means that + this setting may not be used for + services which shall be able to + install mount points in the main mount + namespace.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrivateTmp=</varname></term> + + <listitem><para>Takes a boolean argument. If true, sets up a + new file system namespace for the executed processes and + mounts private <filename>/tmp</filename> and + <filename>/var/tmp</filename> directories inside it that is + not shared by processes outside of the namespace. This is + useful to secure access to temporary files of the process, but + makes sharing between processes via <filename>/tmp</filename> + or <filename>/var/tmp</filename> impossible. If this is + enabled, all temporary files created by a service in these + directories will be removed after the service is stopped. + Defaults to false. It is possible to run two or more units + within the same private <filename>/tmp</filename> and + <filename>/var/tmp</filename> namespace by using the + <varname>JoinsNamespaceOf=</varname> directive, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Note that using this setting will disconnect + propagation of mounts from the service to the host + (propagation in the opposite direction continues to work). + This means that this setting may not be used for services + which shall be able to install mount points in the main mount + namespace.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrivateDevices=</varname></term> + + <listitem><para>Takes a boolean argument. If true, sets up a + new /dev namespace for the executed processes and only adds + API pseudo devices such as <filename>/dev/null</filename>, + <filename>/dev/zero</filename> or + <filename>/dev/random</filename> (as well as the pseudo TTY + subsystem) to it, but no physical devices such as + <filename>/dev/sda</filename>. This is useful to securely turn + off physical device access by the executed process. Defaults + to false. Enabling this option will also remove + <constant>CAP_MKNOD</constant> from the capability bounding + set for the unit (see above), and set + <varname>DevicePolicy=closed</varname> (see + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Note that using this setting will disconnect + propagation of mounts from the service to the host + (propagation in the opposite direction continues to work). + This means that this setting may not be used for services + which shall be able to install mount points in the main mount + namespace.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PrivateNetwork=</varname></term> + + <listitem><para>Takes a boolean argument. If true, sets up a + new network namespace for the executed processes and + configures only the loopback network device + <literal>lo</literal> inside it. No other network devices will + be available to the executed process. This is useful to + securely turn off network access by the executed process. + Defaults to false. It is possible to run two or more units + within the same private network namespace by using the + <varname>JoinsNamespaceOf=</varname> directive, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Note that this option will disconnect all socket + families from the host, this includes AF_NETLINK and AF_UNIX. + The latter has the effect that AF_UNIX sockets in the abstract + socket namespace will become unavailable to the processes + (however, those located in the file system will continue to be + accessible).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectSystem=</varname></term> + + <listitem><para>Takes a boolean argument or + <literal>full</literal>. If true, mounts the + <filename>/usr</filename> and <filename>/boot</filename> + directories read-only for processes invoked by this unit. If + set to <literal>full</literal>, the <filename>/etc</filename> + directory is mounted read-only, too. This setting ensures that + any modification of the vendor supplied operating system (and + optionally its configuration) is prohibited for the service. + It is recommended to enable this setting for all long-running + services, unless they are involved with system updates or need + to modify the operating system in other ways. Note however + that processes retaining the CAP_SYS_ADMIN capability can undo + the effect of this setting. This setting is hence particularly + useful for daemons which have this capability removed, for + example with <varname>CapabilityBoundingSet=</varname>. + Defaults to off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectHome=</varname></term> + + <listitem><para>Takes a boolean argument or + <literal>read-only</literal>. If true, the directories + <filename>/home</filename> and <filename>/run/user</filename> + are made inaccessible and empty for processes invoked by this + unit. If set to <literal>read-only</literal>, the two + directories are made read-only instead. It is recommended to + enable this setting for all long-running services (in + particular network-facing ones), to ensure they cannot get + access to private user data, unless the services actually + require access to the user's private data. Note however that + processes retaining the CAP_SYS_ADMIN capability can undo the + effect of this setting. This setting is hence particularly + useful for daemons which have this capability removed, for + example with <varname>CapabilityBoundingSet=</varname>. + Defaults to off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MountFlags=</varname></term> + + <listitem><para>Takes a mount propagation flag: + <option>shared</option>, <option>slave</option> or + <option>private</option>, which control whether mounts in the + file system namespace set up for this unit's processes will + receive or propagate mounts or unmounts. See + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. Defaults to <option>shared</option>. Use + <option>shared</option> to ensure that mounts and unmounts are + propagated from the host to the container and vice versa. Use + <option>slave</option> to run processes so that none of their + mounts and unmounts will propagate to the host. Use + <option>private</option> to also ensure that no mounts and + unmounts from the host will propagate into the unit processes' + namespace. Note that <option>slave</option> means that file + systems mounted on the host might stay mounted continuously in + the unit's namespace, and thus keep the device busy. Note that + the file system namespace related options + (<varname>PrivateTmp=</varname>, + <varname>PrivateDevices=</varname>, + <varname>ProtectSystem=</varname>, + <varname>ProtectHome=</varname>, + <varname>ReadOnlyDirectories=</varname>, + <varname>InaccessibleDirectories=</varname> and + <varname>ReadWriteDirectories=</varname>) require that mount + and unmount propagation from the unit's file system namespace + is disabled, and hence downgrade <option>shared</option> to + <option>slave</option>. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>UtmpIdentifier=</varname></term> + + <listitem><para>Takes a four character identifier string for + an utmp/wtmp entry for this service. This should only be set + for services such as <command>getty</command> implementations + where utmp/wtmp entries must be created and cleared before and + after execution. If the configured string is longer than four + characters, it is truncated and the terminal four characters + are used. This setting interprets %I style string + replacements. This setting is unset by default, i.e. no + utmp/wtmp entries are created or cleaned up for this + service.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SELinuxContext=</varname></term> + + <listitem><para>Set the SELinux security context of the + executed process. If set, this will override the automated + domain transition. However, the policy still needs to + authorize the transition. This directive is ignored if SELinux + is disabled. If prefixed by <literal>-</literal>, all errors + will be ignored. See + <citerefentry><refentrytitle>setexeccon</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AppArmorProfile=</varname></term> + + <listitem><para>Takes a profile name as argument. The process + executed by the unit will switch to this profile when started. + Profiles must already be loaded in the kernel, or the unit + will fail. This result in a non operation if AppArmor is not + enabled. If prefixed by <literal>-</literal>, all errors will + be ignored. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SmackProcessLabel=</varname></term> + + <listitem><para>Takes a <option>SMACK64</option> security + label as argument. The process executed by the unit will be + started under this label and SMACK will decide whether the + processes is allowed to run or not based on it. The process + will continue to run under the label specified here unless the + executable has its own <option>SMACK64EXEC</option> label, in + which case the process will transition to run under that + label. When not specified, the label that systemd is running + under is used. This directive is ignored if SMACK is + disabled.</para> + + <para>The value may be prefixed by <literal>-</literal>, in + which case all errors will be ignored. An empty value may be + specified to unset previous assignments.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>IgnoreSIGPIPE=</varname></term> + + <listitem><para>Takes a boolean argument. If true, causes + <constant>SIGPIPE</constant> to be ignored in the executed + process. Defaults to true because <constant>SIGPIPE</constant> + generally is useful only in shell pipelines.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>NoNewPrivileges=</varname></term> + + <listitem><para>Takes a boolean argument. If true, ensures + that the service process and all its children can never gain + new privileges. This option is more powerful than the + respective secure bits flags (see above), as it also prohibits + UID changes of any kind. This is the simplest, most effective + way to ensure that a process and its children can never + elevate privileges again.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemCallFilter=</varname></term> + + <listitem><para>Takes a space-separated list of system call + names. If this setting is used, all system calls executed by + the unit processes except for the listed ones will result in + immediate process termination with the + <constant>SIGSYS</constant> signal (whitelisting). If the + first character of the list is <literal>~</literal>, the + effect is inverted: only the listed system calls will result + in immediate process termination (blacklisting). If running in + user mode and this option is used, + <varname>NoNewPrivileges=yes</varname> is implied. This + feature makes use of the Secure Computing Mode 2 interfaces of + the kernel ('seccomp filtering') and is useful for enforcing a + minimal sandboxing environment. Note that the + <function>execve</function>, + <function>rt_sigreturn</function>, + <function>sigreturn</function>, + <function>exit_group</function>, <function>exit</function> + system calls are implicitly whitelisted and do not need to be + listed explicitly. This option may be specified more than once + in which case the filter masks are merged. If the empty string + is assigned, the filter is reset, all prior assignments will + have no effect.</para> + + <para>If you specify both types of this option (i.e. + whitelisting and blacklisting), the first encountered will + take precedence and will dictate the default action + (termination or approval of a system call). Then the next + occurrences of this option will add or delete the listed + system calls from the set of the filtered system calls, + depending of its type and the default action. (For example, if + you have started with a whitelisting of + <function>read</function> and <function>write</function>, and + right after it add a blacklisting of + <function>write</function>, then <function>write</function> + will be removed from the set.) </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemCallErrorNumber=</varname></term> + + <listitem><para>Takes an <literal>errno</literal> error number + name to return when the system call filter configured with + <varname>SystemCallFilter=</varname> is triggered, instead of + terminating the process immediately. Takes an error name such + as <constant>EPERM</constant>, <constant>EACCES</constant> or + <constant>EUCLEAN</constant>. When this setting is not used, + or when the empty string is assigned, the process will be + terminated immediately when the filter is + triggered.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SystemCallArchitectures=</varname></term> + + <listitem><para>Takes a space separated list of architecture + identifiers to include in the system call filter. The known + architecture identifiers are <constant>x86</constant>, + <constant>x86-64</constant>, <constant>x32</constant>, + <constant>arm</constant> as well as the special identifier + <constant>native</constant>. Only system calls of the + specified architectures will be permitted to processes of this + unit. This is an effective way to disable compatibility with + non-native architectures for processes, for example to + prohibit execution of 32-bit x86 binaries on 64-bit x86-64 + systems. The special <constant>native</constant> identifier + implicitly maps to the native architecture of the system (or + more strictly: to the architecture the system manager is + compiled for). If running in user mode and this option is + used, <varname>NoNewPrivileges=yes</varname> is implied. Note + that setting this option to a non-empty list implies that + <constant>native</constant> is included too. By default, this + option is set to the empty list, i.e. no architecture system + call filtering is applied.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestrictAddressFamilies=</varname></term> + + <listitem><para>Restricts the set of socket address families + accessible to the processes of this unit. Takes a + space-separated list of address family names to whitelist, + such as + <constant>AF_UNIX</constant>, + <constant>AF_INET</constant> or + <constant>AF_INET6</constant>. When + prefixed with <constant>~</constant> the listed address + families will be applied as blacklist, otherwise as whitelist. + Note that this restricts access to the + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system call only. Sockets passed into the process by other + means (for example, by using socket activation with socket + units, see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>) + are unaffected. Also, sockets created with + <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 + default, no restriction applies, all address families are + accessible to processes. If assigned the empty string, any + previous list changes are undone.</para> + + <para>Use this option to limit exposure of processes to remote + systems, in particular via exotic network protocols. Note that + in most cases, the local <constant>AF_UNIX</constant> address + family should be included in the configured whitelist as it is + frequently used for local communication, including for + <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry> + logging.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Personality=</varname></term> + + <listitem><para>Controls which kernel architecture + <citerefentry><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> + </varlistentry> + + <varlistentry> + <term><varname>RuntimeDirectory=</varname></term> + <term><varname>RuntimeDirectoryMode=</varname></term> + + <listitem><para>Takes a list of directory names. If set, one + or more directories by the specified names will be created + below <filename>/run</filename> (for system services) or below + <varname>$XDG_RUNTIME_DIR</varname> (for user services) when + the unit is started, and removed when the unit is stopped. The + directories will have the access mode specified in + <varname>RuntimeDirectoryMode=</varname>, and will be owned by + the user and group specified in <varname>User=</varname> and + <varname>Group=</varname>. Use this to manage one or more + runtime directories of the unit and bind their lifetime to the + daemon runtime. The specified directory names must be + relative, and may not include a <literal>/</literal>, i.e. + must refer to simple directories to create or remove. This is + particularly useful for unprivileged daemons that cannot + create runtime directories in <filename>/run</filename> due to + lack of privileges, and to make sure the runtime directory is + cleaned up automatically after use. For runtime directories + that require more complex or different configuration or + lifetime guarantees, please consider using + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Environment variables in spawned processes</title> + + <para>Processes started by the system are executed in a clean + environment in which select variables listed below are set. System + processes started by systemd do not inherit variables from PID 1, + but processes started by user systemd instances inherit all + environment variables from the user systemd instance. + </para> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$PATH</varname></term> + + <listitem><para>Colon-separated list of directories to use + when launching executables. Systemd uses a fixed value of + <filename>/usr/local/sbin</filename>:<filename>/usr/local/bin</filename>:<filename>/usr/sbin</filename>:<filename>/usr/bin</filename>:<filename>/sbin</filename>:<filename>/bin</filename>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$LANG</varname></term> + + <listitem><para>Locale. Can be set in + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + or on the kernel command line (see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$USER</varname></term> + <term><varname>$LOGNAME</varname></term> + <term><varname>$HOME</varname></term> + <term><varname>$SHELL</varname></term> + + <listitem><para>User name (twice), home directory, and the + login shell. The variables are set for the units that have + <varname>User=</varname> set, which includes user + <command>systemd</command> instances. See + <citerefentry><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_RUNTIME_DIR</varname></term> + + <listitem><para>The directory for volatile state. Set for the + user <command>systemd</command> instance, and also in user + sessions. See + <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_SESSION_ID</varname></term> + <term><varname>$XDG_SEAT</varname></term> + <term><varname>$XDG_VTNR</varname></term> + + <listitem><para>The identifier of the session, the seat name, + and virtual terminal of the session. Set by + <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for login sessions. <varname>$XDG_SEAT</varname> and + <varname>$XDG_VTNR</varname> will only be set when attached to + a seat and a tty.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$MAINPID</varname></term> + + <listitem><para>The PID of the units main process if it is + known. This is only set for control processes as invoked by + <varname>ExecReload=</varname> and similar. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$MANAGERPID</varname></term> + + <listitem><para>The PID of the user <command>systemd</command> + instance, set for processes spawned by it. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$LISTEN_FDS</varname></term> + <term><varname>$LISTEN_PID</varname></term> + + <listitem><para>Information about file descriptors passed to a + service for socket activation. See + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$TERM</varname></term> + + <listitem><para>Terminal type, set only for units connected to + a terminal (<varname>StandardInput=tty</varname>, + <varname>StandardOutput=tty</varname>, or + <varname>StandardError=tty</varname>). See + <citerefentry project='man-pages'><refentrytitle>termcap</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <para>Additional variables may be configured by the following + means: for processes spawned in specific units, use the + <varname>Environment=</varname> and + <varname>EnvironmentFile=</varname> options above; to specify + variables globally, use <varname>DefaultEnvironment=</varname> + (see + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>) + or the kernel option <varname>systemd.setenv=</varname> (see + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>). + Additional variables may also be set through PAM, + cf. <citerefentry project='man-pages'><refentrytitle>pam_env</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>exec</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml index 154b95ac7e..1fd46de31f 100644 --- a/man/systemd.journal-fields.xml +++ b/man/systemd.journal-fields.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,583 +23,494 @@ <refentry id="systemd.journal-fields"> - <refentryinfo> - <title>systemd.journal-fields</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd.journal-fields</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.journal-fields</refname> - <refpurpose>Special journal fields</refpurpose> - </refnamediv> - - <refsect1> - <title>Description</title> - - <para>Entries in the journal resemble an environment - block in their syntax but with fields that can - include binary data. Primarily, fields are formatted - UTF-8 text strings, and binary formatting is used only - where formatting as UTF-8 text strings makes little - sense. New fields may freely be defined by - applications, but a few fields have special - meaning. All fields with special meanings are - optional. In some cases, fields may appear more than - once per entry.</para> - </refsect1> - - <refsect1> - <title>User Journal Fields</title> - - <para>User fields are fields that are directly passed - from clients and stored in the journal.</para> - - <variablelist class='journal-directives'> - <varlistentry> - <term><varname>MESSAGE=</varname></term> - <listitem> - <para>The human-readable - message string for this - entry. This is supposed to be - the primary text shown to the - user. It is usually not - translated (but might be in - some cases), and is not - supposed to be parsed for meta - data.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>MESSAGE_ID=</varname></term> - <listitem> - <para>A 128-bit message - identifier ID for recognizing - certain message types, if this - is desirable. This should - contain a 128-bit ID formatted - as a lower-case hexadecimal - string, without any separating - dashes or suchlike. This is - recommended to be a - UUID-compatible ID, but this is not - enforced, and formatted - differently. Developers can - generate a new ID for this - purpose with <command>journalctl - <option>--new-id</option></command>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>PRIORITY=</varname></term> - <listitem> - <para>A priority value between - 0 (<literal>emerg</literal>) - and 7 - (<literal>debug</literal>) - formatted as a decimal - string. This field is - compatible with syslog's - priority concept.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>CODE_FILE=</varname></term> - <term><varname>CODE_LINE=</varname></term> - <term><varname>CODE_FUNC=</varname></term> - <listitem> - <para>The code location - generating this message, if - known. Contains the source - filename, the line number and - the function name.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ERRNO=</varname></term> - <listitem> - <para>The low-level Unix error - number causing this entry, if - any. Contains the numeric - value of - <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> - formatted as a decimal - string.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>SYSLOG_FACILITY=</varname></term> - <term><varname>SYSLOG_IDENTIFIER=</varname></term> - <term><varname>SYSLOG_PID=</varname></term> - <listitem> - <para>Syslog compatibility - fields containing the facility - (formatted as decimal string), - the identifier string - (i.e. "tag"), and the client - PID. (Note that the tag is - usually derived from glibc's - <varname>program_invocation_short_name</varname> - variable, see <citerefentry><refentrytitle>program_invocation_short_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)</para> - </listitem> - - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Trusted Journal Fields</title> - - <para>Fields prefixed with an underscore are trusted - fields, i.e. fields that are implicitly added by the - journal and cannot be altered by client code.</para> - - <variablelist class='journal-directives'> - <varlistentry> - <term><varname>_PID=</varname></term> - <term><varname>_UID=</varname></term> - <term><varname>_GID=</varname></term> - <listitem> - <para>The process, user, and - group ID of the process the - journal entry originates from - formatted as a decimal - string.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>_COMM=</varname></term> - <term><varname>_EXE=</varname></term> - <term><varname>_CMDLINE=</varname></term> - <listitem> - <para>The name, the executable - path, and the command line of - the process the journal entry - originates from.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>_CAP_EFFECTIVE=</varname></term> - <listitem> - <para>The effective <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> of - the process the journal entry - originates from.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>_AUDIT_SESSION=</varname></term> - <term><varname>_AUDIT_LOGINUID=</varname></term> - <listitem> - <para>The session and login - UID of the process the journal - entry originates from, as - maintained by the kernel audit - subsystem.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>_SYSTEMD_CGROUP=</varname></term> - <term><varname>_SYSTEMD_SESSION=</varname></term> - <term><varname>_SYSTEMD_UNIT=</varname></term> - <term><varname>_SYSTEMD_USER_UNIT=</varname></term> - <term><varname>_SYSTEMD_OWNER_UID=</varname></term> - <term><varname>_SYSTEMD_SLICE=</varname></term> - - <listitem> - <para>The control group path - in the systemd hierarchy, the - systemd session ID (if any), - the systemd unit name (if - any), the systemd user session - unit name (if any), the owner - UID of the systemd session (if - any) and the systemd slice - unit of the process the - journal entry originates - from.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>_SELINUX_CONTEXT=</varname></term> - <listitem> - <para>The SELinux security - context (label) of the process - the journal entry originates - from.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term> - <listitem> - <para>The earliest trusted - timestamp of the message, if - any is known that is different - from the reception time of the - journal. This is the time in - microseconds since the epoch UTC, - formatted as a decimal - string.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>_BOOT_ID=</varname></term> - <listitem> - <para>The kernel boot ID for - the boot the message was - generated in, formatted as - a 128-bit hexadecimal - string.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>_MACHINE_ID=</varname></term> - <listitem> - <para>The machine ID of the - originating host, as available - in - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>_HOSTNAME=</varname></term> - <listitem> - <para>The name of the - originating host.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>_TRANSPORT=</varname></term> - <listitem> - <para>How the entry was - received by the journal - service. Valid transports are: - </para> - <variablelist> - <varlistentry> - <term> - <option>driver</option> - </term> - <listitem> - <para>for - internally - generated - messages - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>syslog</option> - </term> - <listitem> - <para>for those - received via the - local syslog - socket with the - syslog protocol - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>journal</option> - </term> - <listitem> - <para>for those - received via the - native journal - protocol - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>stdout</option> - </term> - <listitem> - <para>for those - read from a - service's - standard output - or error output - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <option>kernel</option> - </term> - <listitem> - <para>for those - read from the - kernel - </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Kernel Journal Fields</title> - - <para>Kernel fields are fields that are used by - messages originating in the kernel and stored in the - journal.</para> - - <variablelist class='journal-directives'> - <varlistentry> - <term><varname>_KERNEL_DEVICE=</varname></term> - <listitem> - <para>The kernel device - name. If the entry is - associated to a block device, - the major and minor of the - device node, separated by <literal>:</literal> - and prefixed by <literal>b</literal>. Similar - for character devices but - prefixed by <literal>c</literal>. For network - devices, this is the interface index - prefixed by <literal>n</literal>. For all other - devices, this is the subsystem name - prefixed by <literal>+</literal>, followed by - <literal>:</literal>, followed by the kernel - device name.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>_KERNEL_SUBSYSTEM=</varname></term> - <listitem> - <para>The kernel subsystem name.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>_UDEV_SYSNAME=</varname></term> - <listitem> - <para>The kernel device name - as it shows up in the device - tree below - <filename>/sys</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>_UDEV_DEVNODE=</varname></term> - <listitem> - <para>The device node path of - this device in - <filename>/dev</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>_UDEV_DEVLINK=</varname></term> - <listitem> - <para>Additional symlink names - pointing to the device node in - <filename>/dev</filename>. This - field is frequently set more - than once per entry.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Fields to log on behalf of a different program</title> - - <para>Fields in this section are used by programs - to specify that they are logging on behalf of another - program or unit. + <refentryinfo> + <title>systemd.journal-fields</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.journal-fields</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.journal-fields</refname> + <refpurpose>Special journal fields</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>Entries in the journal resemble an environment block in + their syntax but with fields that can include binary data. + Primarily, fields are formatted UTF-8 text strings, and binary + formatting is used only where formatting as UTF-8 text strings + makes little sense. New fields may freely be defined by + applications, but a few fields have special meaning. All fields + with special meanings are optional. In some cases, fields may + appear more than once per entry.</para> + </refsect1> + + <refsect1> + <title>User Journal Fields</title> + + <para>User fields are fields that are directly passed from clients + and stored in the journal.</para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>MESSAGE=</varname></term> + <listitem> + <para>The human-readable message string for this entry. This + is supposed to be the primary text shown to the user. It is + usually not translated (but might be in some cases), and is + not supposed to be parsed for meta data.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MESSAGE_ID=</varname></term> + <listitem> + <para>A 128-bit message identifier ID for recognizing + certain message types, if this is desirable. This should + contain a 128-bit ID formatted as a lower-case hexadecimal + string, without any separating dashes or suchlike. This is + recommended to be a UUID-compatible ID, but this is not + enforced, and formatted differently. Developers can generate + a new ID for this purpose with <command>journalctl + <option>--new-id</option></command>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>PRIORITY=</varname></term> + <listitem> + <para>A priority value between 0 (<literal>emerg</literal>) + and 7 (<literal>debug</literal>) formatted as a decimal + string. This field is compatible with syslog's priority + concept.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>CODE_FILE=</varname></term> + <term><varname>CODE_LINE=</varname></term> + <term><varname>CODE_FUNC=</varname></term> + <listitem> + <para>The code location generating this message, if known. + Contains the source filename, the line number and the + function name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ERRNO=</varname></term> + <listitem> + <para>The low-level Unix error number causing this entry, if + any. Contains the numeric value of + <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry> + formatted as a decimal string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSLOG_FACILITY=</varname></term> + <term><varname>SYSLOG_IDENTIFIER=</varname></term> + <term><varname>SYSLOG_PID=</varname></term> + <listitem> + <para>Syslog compatibility fields containing the facility + (formatted as decimal string), the identifier string (i.e. + "tag"), and the client PID. (Note that the tag is usually + derived from glibc's + <varname>program_invocation_short_name</varname> variable, + see + <citerefentry><refentrytitle>program_invocation_short_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>.)</para> + </listitem> + + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Trusted Journal Fields</title> + + <para>Fields prefixed with an underscore are trusted fields, i.e. + fields that are implicitly added by the journal and cannot be + altered by client code.</para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>_PID=</varname></term> + <term><varname>_UID=</varname></term> + <term><varname>_GID=</varname></term> + <listitem> + <para>The process, user, and group ID of the process the + journal entry originates from formatted as a decimal + string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_COMM=</varname></term> + <term><varname>_EXE=</varname></term> + <term><varname>_CMDLINE=</varname></term> + <listitem> + <para>The name, the executable path, and the command line of + the process the journal entry originates from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_CAP_EFFECTIVE=</varname></term> + <listitem> + <para>The effective + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + of the process the journal entry originates from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_AUDIT_SESSION=</varname></term> + <term><varname>_AUDIT_LOGINUID=</varname></term> + <listitem> + <para>The session and login UID of the process the journal + entry originates from, as maintained by the kernel audit + subsystem.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_SYSTEMD_CGROUP=</varname></term> + <term><varname>_SYSTEMD_SESSION=</varname></term> + <term><varname>_SYSTEMD_UNIT=</varname></term> + <term><varname>_SYSTEMD_USER_UNIT=</varname></term> + <term><varname>_SYSTEMD_OWNER_UID=</varname></term> + <term><varname>_SYSTEMD_SLICE=</varname></term> + + <listitem> + <para>The control group path in the systemd hierarchy, the + systemd session ID (if any), the systemd unit name (if any), + the systemd user session unit name (if any), the owner UID + of the systemd session (if any) and the systemd slice unit + of the process the journal entry originates from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_SELINUX_CONTEXT=</varname></term> + <listitem> + <para>The SELinux security context (label) of the process + the journal entry originates from.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_SOURCE_REALTIME_TIMESTAMP=</varname></term> + <listitem> + <para>The earliest trusted timestamp of the message, if any + is known that is different from the reception time of the + journal. This is the time in microseconds since the epoch + UTC, formatted as a decimal string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_BOOT_ID=</varname></term> + <listitem> + <para>The kernel boot ID for the boot the message was + generated in, formatted as a 128-bit hexadecimal + string.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_MACHINE_ID=</varname></term> + <listitem> + <para>The machine ID of the originating host, as available + in + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_HOSTNAME=</varname></term> + <listitem> + <para>The name of the originating host.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>_TRANSPORT=</varname></term> + <listitem> + <para>How the entry was received by the journal service. + Valid transports are: + </para> + <variablelist> + <varlistentry> + <term> + <option>driver</option> + </term> + <listitem> + <para>for internally generated messages </para> - - <para>Fields used by the <command>systemd-coredump</command> - coredump kernel helper: + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>syslog</option> + </term> + <listitem> + <para>for those received via the local syslog socket + with the syslog protocol </para> - - <variablelist class='journal-directives'> - <varlistentry> - <term><varname>COREDUMP_UNIT=</varname></term> - <term><varname>COREDUMP_USER_UNIT=</varname></term> - <listitem> - <para>Used to annotate - messages containing coredumps from - system and session units. - See - <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para>Priviledged programs (currently UID 0) may - attach <varname>OBJECT_PID=</varname> to a - message. This will instruct - <command>systemd-journald</command> to attach - additional fields on behalf of the caller:</para> - - <variablelist class='journal-directives'> - <varlistentry> - <term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term> - <listitem> - <para>PID of the program that this - message pertains to. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>OBJECT_UID=</varname></term> - <term><varname>OBJECT_GID=</varname></term> - <term><varname>OBJECT_COMM=</varname></term> - <term><varname>OBJECT_EXE=</varname></term> - <term><varname>OBJECT_CMDLINE=</varname></term> - <term><varname>OBJECT_AUDIT_SESSION=</varname></term> - <term><varname>OBJECT_AUDIT_LOGINUID=</varname></term> - <term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term> - <term><varname>OBJECT_SYSTEMD_SESSION=</varname></term> - <term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term> - <term><varname>OBJECT_SYSTEMD_UNIT=</varname></term> - <term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term> - <listitem> - <para>These are additional fields added automatically - by <command>systemd-journald</command>. - Their meaning is the same as - <varname>_UID=</varname>, - <varname>_GID=</varname>, - <varname>_COMM=</varname>, - <varname>_EXE=</varname>, - <varname>_CMDLINE=</varname>, - <varname>_AUDIT_SESSION=</varname>, - <varname>_AUDIT_LOGINUID=</varname>, - <varname>_SYSTEMD_CGROUP=</varname>, - <varname>_SYSTEMD_SESSION=</varname>, - <varname>_SYSTEMD_UNIT=</varname>, - <varname>_SYSTEMD_USER_UNIT=</varname>, and - <varname>_SYSTEMD_OWNER_UID=</varname> - as described above, except that the - process identified by <replaceable>PID</replaceable> - is described, instead of the process - which logged the message.</para> - </listitem> - </varlistentry> - </variablelist> - - - </refsect1> - - <refsect1> - <title>Address Fields</title> - - <para>During serialization into external formats, such - as the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal - Export Format</ulink> or the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal - JSON Format</ulink>, the addresses of journal entries - are serialized into fields prefixed with double - underscores. Note that these are not proper fields when - stored in the journal but for addressing metadata of - entries. They cannot be written as part of structured - log entries via calls such as - <citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. They - may also not be used as matches for - <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para> - - <variablelist class='journal-directives'> - <varlistentry> - <term><varname>__CURSOR=</varname></term> - <listitem> - <para>The cursor for the - entry. A cursor is an opaque - text string that uniquely - describes the position of an - entry in the journal and is - portable across machines, - platforms and journal files. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>__REALTIME_TIMESTAMP=</varname></term> - <listitem> - <para>The wallclock time - (<constant>CLOCK_REALTIME</constant>) - at the point in time the entry - was received by the journal, - in microseconds since the epoch - UTC, formatted as a decimal - string. This has different - properties from - <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>, - as it is usually a bit later - but more likely to be monotonic. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>__MONOTONIC_TIMESTAMP=</varname></term> - <listitem> - <para>The monotonic time - (<constant>CLOCK_MONOTONIC</constant>) - at the point in time the entry - was received by the journal in - microseconds, formatted as a decimal - string. To be useful as an - address for the entry, this - should be combined with the - boot ID in <literal>_BOOT_ID=</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>journal</option> + </term> + <listitem> + <para>for those received via the native journal + protocol + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>stdout</option> + </term> + <listitem> + <para>for those read from a service's standard output + or error output + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>kernel</option> + </term> + <listitem> + <para>for those read from the kernel + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Kernel Journal Fields</title> + + <para>Kernel fields are fields that are used by messages + originating in the kernel and stored in the journal.</para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>_KERNEL_DEVICE=</varname></term> + <listitem> + <para>The kernel device name. If the entry is associated to + a block device, the major and minor of the device node, + separated by <literal>:</literal> and prefixed by + <literal>b</literal>. Similar for character devices but + prefixed by <literal>c</literal>. For network devices, this + is the interface index prefixed by <literal>n</literal>. For + all other devices, this is the subsystem name prefixed by + <literal>+</literal>, followed by <literal>:</literal>, + followed by the kernel device name.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>_KERNEL_SUBSYSTEM=</varname></term> + <listitem> + <para>The kernel subsystem name.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>_UDEV_SYSNAME=</varname></term> + <listitem> + <para>The kernel device name as it shows up in the device + tree below <filename>/sys</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>_UDEV_DEVNODE=</varname></term> + <listitem> + <para>The device node path of this device in + <filename>/dev</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>_UDEV_DEVLINK=</varname></term> + <listitem> + <para>Additional symlink names pointing to the device node + in <filename>/dev</filename>. This field is frequently set + more than once per entry.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Fields to log on behalf of a different program</title> + + <para>Fields in this section are used by programs to specify that + they are logging on behalf of another program or unit. + </para> + + <para>Fields used by the <command>systemd-coredump</command> + coredump kernel helper: + </para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>COREDUMP_UNIT=</varname></term> + <term><varname>COREDUMP_USER_UNIT=</varname></term> + <listitem> + <para>Used to annotate messages containing coredumps from + system and session units. See + <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para>Priviledged programs (currently UID 0) may attach + <varname>OBJECT_PID=</varname> to a message. This will instruct + <command>systemd-journald</command> to attach additional fields on + behalf of the caller:</para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>OBJECT_PID=<replaceable>PID</replaceable></varname></term> + <listitem> + <para>PID of the program that this message pertains to. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>OBJECT_UID=</varname></term> + <term><varname>OBJECT_GID=</varname></term> + <term><varname>OBJECT_COMM=</varname></term> + <term><varname>OBJECT_EXE=</varname></term> + <term><varname>OBJECT_CMDLINE=</varname></term> + <term><varname>OBJECT_AUDIT_SESSION=</varname></term> + <term><varname>OBJECT_AUDIT_LOGINUID=</varname></term> + <term><varname>OBJECT_SYSTEMD_CGROUP=</varname></term> + <term><varname>OBJECT_SYSTEMD_SESSION=</varname></term> + <term><varname>OBJECT_SYSTEMD_OWNER_UID=</varname></term> + <term><varname>OBJECT_SYSTEMD_UNIT=</varname></term> + <term><varname>OBJECT_SYSTEMD_USER_UNIT=</varname></term> + <listitem> + <para>These are additional fields added automatically by + <command>systemd-journald</command>. Their meaning is the + same as + <varname>_UID=</varname>, + <varname>_GID=</varname>, + <varname>_COMM=</varname>, + <varname>_EXE=</varname>, + <varname>_CMDLINE=</varname>, + <varname>_AUDIT_SESSION=</varname>, + <varname>_AUDIT_LOGINUID=</varname>, + <varname>_SYSTEMD_CGROUP=</varname>, + <varname>_SYSTEMD_SESSION=</varname>, + <varname>_SYSTEMD_UNIT=</varname>, + <varname>_SYSTEMD_USER_UNIT=</varname>, and + <varname>_SYSTEMD_OWNER_UID=</varname> + as described above, except that the process identified by + <replaceable>PID</replaceable> is described, instead of the + process which logged the message.</para> + </listitem> + </varlistentry> + </variablelist> + + + </refsect1> + + <refsect1> + <title>Address Fields</title> + + <para>During serialization into external formats, such as the + <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/export">Journal + Export Format</ulink> or the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/json">Journal + JSON Format</ulink>, the addresses of journal entries are + serialized into fields prefixed with double underscores. Note that + these are not proper fields when stored in the journal but for + addressing metadata of entries. They cannot be written as part of + structured log entries via calls such as + <citerefentry><refentrytitle>sd_journal_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + They may also not be used as matches for + <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry></para> + + <variablelist class='journal-directives'> + <varlistentry> + <term><varname>__CURSOR=</varname></term> + <listitem> + <para>The cursor for the entry. A cursor is an opaque text + string that uniquely describes the position of an entry in + the journal and is portable across machines, platforms and + journal files. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>__REALTIME_TIMESTAMP=</varname></term> + <listitem> + <para>The wallclock time + (<constant>CLOCK_REALTIME</constant>) at the point in time + the entry was received by the journal, in microseconds since + the epoch UTC, formatted as a decimal string. This has + different properties from + <literal>_SOURCE_REALTIME_TIMESTAMP=</literal>, as it is + usually a bit later but more likely to be monotonic. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>__MONOTONIC_TIMESTAMP=</varname></term> + <listitem> + <para>The monotonic time + (<constant>CLOCK_MONOTONIC</constant>) at the point in time + the entry was received by the journal in microseconds, + formatted as a decimal string. To be useful as an address + for the entry, this should be combined with the boot ID in + <literal>_BOOT_ID=</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.kill.xml b/man/systemd.kill.xml index caee371c81..3a9ddec559 100644 --- a/man/systemd.kill.xml +++ b/man/systemd.kill.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,194 +23,162 @@ --> <refentry id="systemd.kill"> - <refentryinfo> - <title>systemd.kill</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.kill</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.kill</refname> - <refpurpose>Process killing procedure - configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>service</replaceable>.service</filename>, - <filename><replaceable>socket</replaceable>.socket</filename>, - <filename><replaceable>mount</replaceable>.mount</filename>, - <filename><replaceable>swap</replaceable>.swap</filename>, - <filename><replaceable>scope</replaceable>.scope</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>Unit configuration files for services, sockets, - mount points, swap devices and scopes share a subset - of configuration options which define the - killing procedure of processes belonging to the unit.</para> - - <para>This man page lists the configuration options - shared by these five unit types. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the common options shared by all unit - configuration files, and - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information on the configuration file options - specific to each unit type.</para> - - <para>The kill procedure - configuration options are configured in the [Service], - [Socket], [Mount] or [Swap] section, depending on the - unit type.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <variablelist class='unit-directives'> - - <varlistentry> - <term><varname>KillMode=</varname></term> - <listitem><para>Specifies how - processes of this unit shall be - killed. One of - <option>control-group</option>, - <option>process</option>, - <option>mixed</option>, - <option>none</option>.</para> - - <para>If set to - <option>control-group</option>, all - remaining processes in the control - group of this unit will be killed on - unit stop (for services: after the - stop command is executed, as - configured with - <varname>ExecStop=</varname>). If set - to <option>process</option>, only the - main process itself is killed. If set - to <option>mixed</option>, the - <constant>SIGTERM</constant> signal - (see below) is sent to the main - process while the subsequent - <constant>SIGKILL</constant> signal - (see below) is sent to all remaining - processes of the unit's control - group. If set to - <option>none</option>, no process is - killed. In this case, only the stop - command will be executed on unit stop, - but no process be killed - otherwise. Processes remaining alive - after stop are left in their control - group and the control group continues - to exist after stop unless it is - empty.</para> - - <para>Processes will first be - terminated via - <constant>SIGTERM</constant> (unless - the signal to send is changed via - <varname>KillSignal=</varname>). Optionally, - this is immediately followed by a - <constant>SIGHUP</constant> (if - enabled with - <varname>SendSIGHUP=</varname>). If - then, after a delay (configured via the - <varname>TimeoutStopSec=</varname> option), - processes still remain, the - termination request is repeated with - the <constant>SIGKILL</constant> - signal (unless this is disabled via - the <varname>SendSIGKILL=</varname> - option). See - <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for more - information.</para> - - <para>Defaults to - <option>control-group</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>KillSignal=</varname></term> - <listitem><para>Specifies which signal - to use when killing a service. This - controls the signal that is sent as - first step of shutting down a unit - (see above), and is usually followed - by <constant>SIGKILL</constant> (see - above and below). For a list of valid - signals, see - <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Defaults - to <constant>SIGTERM</constant>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SendSIGHUP=</varname></term> - <listitem><para>Specifies whether to - send <constant>SIGHUP</constant> to - remaining processes immediately after - sending the signal configured with - <varname>KillSignal=</varname>. This - is useful to indicate to shells and - shell-like programs that their - connection has been severed. Takes a - boolean value. Defaults to "no". - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SendSIGKILL=</varname></term> - <listitem><para>Specifies whether to - send <constant>SIGKILL</constant> to remaining processes - after a timeout, if the normal - shutdown procedure left processes of - the service around. Takes a boolean - value. Defaults to "yes". - </para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd.kill</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.kill</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.kill</refname> + <refpurpose>Process killing procedure + configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>service</replaceable>.service</filename>, + <filename><replaceable>socket</replaceable>.socket</filename>, + <filename><replaceable>mount</replaceable>.mount</filename>, + <filename><replaceable>swap</replaceable>.swap</filename>, + <filename><replaceable>scope</replaceable>.scope</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Unit configuration files for services, sockets, mount + points, swap devices and scopes share a subset of configuration + options which define the killing procedure of processes belonging + to the unit.</para> + + <para>This man page lists the configuration options shared by + these five unit types. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options shared by all unit configuration files, and + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information on the configuration file options specific to + each unit type.</para> + + <para>The kill procedure configuration options are configured in + the [Service], [Socket], [Mount] or [Swap] section, depending on + the unit type.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>KillMode=</varname></term> + <listitem><para>Specifies how processes of this unit shall be + killed. One of + <option>control-group</option>, + <option>process</option>, + <option>mixed</option>, + <option>none</option>.</para> + + <para>If set to <option>control-group</option>, all remaining + processes in the control group of this unit will be killed on + unit stop (for services: after the stop command is executed, + as configured with <varname>ExecStop=</varname>). If set to + <option>process</option>, only the main process itself is + killed. If set to <option>mixed</option>, the + <constant>SIGTERM</constant> signal (see below) is sent to the + main process while the subsequent <constant>SIGKILL</constant> + signal (see below) is sent to all remaining processes of the + unit's control group. If set to <option>none</option>, no + process is killed. In this case, only the stop command will be + executed on unit stop, but no process be killed otherwise. + Processes remaining alive after stop are left in their control + group and the control group continues to exist after stop + unless it is empty.</para> + + <para>Processes will first be terminated via + <constant>SIGTERM</constant> (unless the signal to send is + changed via <varname>KillSignal=</varname>). Optionally, this + is immediately followed by a <constant>SIGHUP</constant> (if + enabled with <varname>SendSIGHUP=</varname>). If then, after a + delay (configured via the <varname>TimeoutStopSec=</varname> + option), processes still remain, the termination request is + repeated with the <constant>SIGKILL</constant> signal (unless + this is disabled via the <varname>SendSIGKILL=</varname> + option). See + <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information.</para> + + <para>Defaults to + <option>control-group</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KillSignal=</varname></term> + <listitem><para>Specifies which signal to use when killing a + service. This controls the signal that is sent as first step + of shutting down a unit (see above), and is usually followed + by <constant>SIGKILL</constant> (see above and below). For a + list of valid signals, see + <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + Defaults to <constant>SIGTERM</constant>. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SendSIGHUP=</varname></term> + <listitem><para>Specifies whether to send + <constant>SIGHUP</constant> to remaining processes immediately + after sending the signal configured with + <varname>KillSignal=</varname>. This is useful to indicate to + shells and shell-like programs that their connection has been + severed. Takes a boolean value. Defaults to "no". + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SendSIGKILL=</varname></term> + <listitem><para>Specifies whether to send + <constant>SIGKILL</constant> to remaining processes after a + timeout, if the normal shutdown procedure left processes of + the service around. Takes a boolean value. Defaults to "yes". + </para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.link.xml b/man/systemd.link.xml index ecf7954d1b..2cfe7107f8 100644 --- a/man/systemd.link.xml +++ b/man/systemd.link.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,371 +23,364 @@ --> <refentry id="systemd.link"> - <refentryinfo> - <title>systemd.link</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd.link</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd.link</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd.link</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd.link</refname> - <refpurpose>Network device configuration</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd.link</refname> + <refpurpose>Network device configuration</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename><replaceable>link</replaceable>.link</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename><replaceable>link</replaceable>.link</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para>Network link configuration is performed by the <command>net_setup_link</command> - udev builtin.</para> + <para>Network link configuration is performed by the + <command>net_setup_link</command> udev builtin.</para> - <para>The link files are read from the files located in the - system network directory <filename>/usr/lib/systemd/network</filename>, - the volatile runtime network directory <filename>/run/systemd/network</filename>, - and the local administration network directory <filename>/etc/systemd/network</filename>. - Link files must have the extension <filename>.link</filename>; other extensions are ignored. - All link files are collectively sorted and processed in lexical order, - regardless of the directories in which they live. However, files with - identical filenames replace each other. Files in <filename>/etc</filename> - have the highest priority, files in <filename>/run</filename> take precedence - over files with the same name in <filename>/usr/lib</filename>. This can be - used to override a system-supplied link file with a local file if needed; - a symlink in <filename>/etc</filename> with the same name as a link file in - <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>, - disables the link file entirely.</para> + <para>The link files are read from the files located in the system + network directory <filename>/usr/lib/systemd/network</filename>, + the volatile runtime network directory + <filename>/run/systemd/network</filename>, and the local + administration network directory + <filename>/etc/systemd/network</filename>. Link files must have + the extension <filename>.link</filename>; other extensions are + ignored. All link files are collectively sorted and processed in + lexical order, regardless of the directories in which they live. + However, files with identical filenames replace each other. Files + in <filename>/etc</filename> have the highest priority, files in + <filename>/run</filename> take precedence over files with the same + name in <filename>/usr/lib</filename>. This can be used to + override a system-supplied link file with a local file if needed; + a symlink in <filename>/etc</filename> with the same name as a + link file in <filename>/usr/lib</filename>, pointing to + <filename>/dev/null</filename>, disables the link file + entirely.</para> - <para>The link file contains a - <literal>[Match]</literal> section, which determines - if a given link file may be applied to a given device, - as well as a <literal>[Link]</literal> section specifying how - the device should be configured. The first (in lexical - order) of the link files that matches a given device - is applied. Note that a default file - <filename>99-default.link</filename> is shipped by the - system, any user-supplied <filename>.link</filename> - should hence have a lexically earlier name to be - considered at all.</para> - </refsect1> + <para>The link file contains a <literal>[Match]</literal> section, + which determines if a given link file may be applied to a given + device, as well as a <literal>[Link]</literal> section specifying + how the device should be configured. The first (in lexical order) + of the link files that matches a given device is applied. Note + that a default file <filename>99-default.link</filename> is + shipped by the system, any user-supplied + <filename>.link</filename> should hence have a lexically earlier + name to be considered at all.</para> + </refsect1> - <refsect1> - <title>[Match] Section Options</title> + <refsect1> + <title>[Match] Section Options</title> - <para>A link file is said to match a device if each of the entries in the - <literal>[Match]</literal> section matches, or if the section is empty. - The following keys are accepted:</para> + <para>A link file is said to match a device if each of the entries + in the <literal>[Match]</literal> section matches, or if the + section is empty. The following keys are accepted:</para> - <variablelist class='network-directives'> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The hardware address.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>OriginalName=</varname></term> - <listitem> - <para>The device name, as exposed by the udev - property "INTERFACE". May contain shell style - globs. This can not be used to match on names - that have already been changed from userspace. - Caution is advised when matching on - kernel-assigned names, as they are known to - be unstable between reboots.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Path=</varname></term> - <listitem> - <para>The persistent path, as exposed by the - udev property <literal>ID_PATH</literal>. May - contain shell style globs.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Driver=</varname></term> - <listitem> - <para>The driver currently bound to the device, - as exposed by the udev property <literal>DRIVER</literal> - of its parent device, or if that is not set, the - driver as exposed by <literal>ethtool -i</literal> - of the device itself.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Type=</varname></term> - <listitem> - <para>The device type, as exposed by the udev - property <literal>DEVTYPE</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Host=</varname></term> - <listitem> - <para>Matches against the hostname or machine - ID of the host. See <literal>ConditionHost=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Virtualization=</varname></term> - <listitem> - <para>Checks whether the system is executed in - a virtualized environment and optionally test - whether it is a specific implementation. See - <literal>ConditionVirtualization=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>KernelCommandLine=</varname></term> - <listitem> - <para>Checks whether a specific kernel command - line option is set (or if prefixed with the - exclamation mark unset). See - <literal>ConditionKernelCommandLine=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Architecture=</varname></term> - <listitem> - <para>Checks whether the system is running on a - specific architecture. See - <literal>ConditionArchitecture=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - </variablelist> + <variablelist class='network-directives'> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The hardware address.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>OriginalName=</varname></term> + <listitem> + <para>The device name, as exposed by the udev property + "INTERFACE". May contain shell style globs. This can not be + used to match on names that have already been changed from + userspace. Caution is advised when matching on + kernel-assigned names, as they are known to be unstable + between reboots.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Path=</varname></term> + <listitem> + <para>The persistent path, as exposed by the + udev property <literal>ID_PATH</literal>. May + contain shell style globs.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Driver=</varname></term> + <listitem> + <para>The driver currently bound to the device, + as exposed by the udev property <literal>DRIVER</literal> + of its parent device, or if that is not set, the + driver as exposed by <literal>ethtool -i</literal> + of the device itself.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Type=</varname></term> + <listitem> + <para>The device type, as exposed by the udev + property <literal>DEVTYPE</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Host=</varname></term> + <listitem> + <para>Matches against the hostname or machine + ID of the host. See <literal>ConditionHost=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Virtualization=</varname></term> + <listitem> + <para>Checks whether the system is executed in + a virtualized environment and optionally test + whether it is a specific implementation. See + <literal>ConditionVirtualization=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>KernelCommandLine=</varname></term> + <listitem> + <para>Checks whether a specific kernel command line option + is set (or if prefixed with the exclamation mark unset). See + <literal>ConditionKernelCommandLine=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Architecture=</varname></term> + <listitem> + <para>Checks whether the system is running on a specific + architecture. See <literal>ConditionArchitecture=</literal> + in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </listitem> + </varlistentry> + </variablelist> - </refsect1> + </refsect1> - <refsect1> - <title>[Link] Section Options</title> + <refsect1> + <title>[Link] Section Options</title> - <para>The <literal>[Link]</literal> section accepts the following - keys:</para> + <para>The <literal>[Link]</literal> section accepts the following + keys:</para> - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Description=</varname></term> - <listitem> - <para>A description of the device.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Alias=</varname></term> - <listitem> - <para>The <literal>ifalias</literal> is set to - this value.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MACAddressPolicy=</varname></term> - <listitem> - <para>The policy by which the MAC address - should be set. The available policies are: - </para> + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Description=</varname></term> + <listitem> + <para>A description of the device.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Alias=</varname></term> + <listitem> + <para>The <literal>ifalias</literal> is set to this + value.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACAddressPolicy=</varname></term> + <listitem> + <para>The policy by which the MAC address should be set. The + available policies are: + </para> - <variablelist> - <varlistentry> - <term><literal>persistent</literal></term> - <listitem> - <para>If the hardware has a persistent - MAC address, as most hardware should, - and if it is used by the kernel, nothing - is done. Otherwise, a new MAC address - is generated which is guaranteed to be - the same on every boot for the given - machine and the given device, but which - is otherwise random.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>random</literal></term> - <listitem> - <para>If the kernel is using a random MAC - address, nothing is done. Otherwise, a new - address is randomly generated each time the - device appears, typically at boot.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The MAC address to use, if no - <literal>MACAddressPolicy=</literal> - is specified.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>NamePolicy=</varname></term> - <listitem> - <para>An ordered, space-separated list of - policies by which the interface name should - be set. <literal>NamePolicy</literal> may be - disabled by specifying - <literal>net.ifnames=0</literal> on the kernel - command line. Each of the policies may fail, and - the first successful one is used. The name is - not set directly, but is exported to udev as - the property <literal>ID_NET_NAME</literal>, - which is, by default, used by a udev rule to set - <literal>NAME</literal>. If the name has already - been set by userspace, no renaming is performed. - The available policies are:</para> + <variablelist> + <varlistentry> + <term><literal>persistent</literal></term> + <listitem> + <para>If the hardware has a persistent MAC address, as + most hardware should, and if it is used by the kernel, + nothing is done. Otherwise, a new MAC address is + generated which is guaranteed to be the same on every + boot for the given machine and the given device, but + which is otherwise random.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>random</literal></term> + <listitem> + <para>If the kernel is using a random MAC address, + nothing is done. Otherwise, a new address is randomly + generated each time the device appears, typically at + boot.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The MAC address to use, if no + <literal>MACAddressPolicy=</literal> + is specified.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>NamePolicy=</varname></term> + <listitem> + <para>An ordered, space-separated list of policies by which + the interface name should be set. + <literal>NamePolicy</literal> may be disabled by specifying + <literal>net.ifnames=0</literal> on the kernel command line. + Each of the policies may fail, and the first successful one + is used. The name is not set directly, but is exported to + udev as the property <literal>ID_NET_NAME</literal>, which + is, by default, used by a udev rule to set + <literal>NAME</literal>. If the name has already been set by + userspace, no renaming is performed. The available policies + are:</para> - <variablelist> - <varlistentry> - <term><literal>kernel</literal></term> - <listitem> - <para>If the kernel claims that the name it - has set for a device is predictable, then - no renaming is performed. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>database</literal></term> - <listitem> - <para>The name is set based on entries in - the udev's Hardware Database with the key - <literal>ID_NET_NAME_FROM_DATABASE</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>onboard</literal></term> - <listitem> - <para>The name is set based on information given by - the firmware for on-board devices, as exported by - the udev property <literal>ID_NET_NAME_ONBOARD</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>slot</literal></term> - <listitem> - <para>The name is set based on information given by - the firmware for hot-plug devices, as exported by - the udev property <literal>ID_NET_NAME_SLOT</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>path</literal></term> - <listitem> - <para>The name is set based on the device's physical - location, as exported by the udev property - <literal>ID_NET_NAME_PATH</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>mac</literal></term> - <listitem> - <para>The name is set based on the device's - persistent MAC address, as exported by the udev - property <literal>ID_NET_NAME_MAC</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Name=</varname></term> - <listitem> - <para>The interface name to use in case all the - policies specified in - <varname>NamePolicy=</varname> fail, or in case - <varname>NamePolicy=</varname> is missing or - disabled.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MTUBytes=</varname></term> - <listitem> - <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> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>BitsPerSecond=</varname></term> - <listitem> - <para>The speed to set for the device, the - value is rounded down to the nearest Mbps. - The usual suffixes K, M, G, are supported and - are understood to the base of 1000.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Duplex=</varname></term> - <listitem> - <para>The duplex mode to set for the device. - The accepted values are <literal>half</literal> - and <literal>full</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>WakeOnLan=</varname></term> - <listitem> - <para>The Wake-on-LAN policy to set for the - device. The supported values are:</para> + <variablelist> + <varlistentry> + <term><literal>kernel</literal></term> + <listitem> + <para>If the kernel claims that the name it has set + for a device is predictable, then no renaming is + performed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>database</literal></term> + <listitem> + <para>The name is set based on entries in the udev's + Hardware Database with the key + <literal>ID_NET_NAME_FROM_DATABASE</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>onboard</literal></term> + <listitem> + <para>The name is set based on information given by + the firmware for on-board devices, as exported by the + udev property <literal>ID_NET_NAME_ONBOARD</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>slot</literal></term> + <listitem> + <para>The name is set based on information given by + the firmware for hot-plug devices, as exported by the + udev property <literal>ID_NET_NAME_SLOT</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>path</literal></term> + <listitem> + <para>The name is set based on the device's physical + location, as exported by the udev property + <literal>ID_NET_NAME_PATH</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>mac</literal></term> + <listitem> + <para>The name is set based on the device's persistent + MAC address, as exported by the udev property + <literal>ID_NET_NAME_MAC</literal>.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Name=</varname></term> + <listitem> + <para>The interface name to use in case all the + policies specified in + <varname>NamePolicy=</varname> fail, or in case + <varname>NamePolicy=</varname> is missing or + disabled.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MTUBytes=</varname></term> + <listitem> + <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> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>BitsPerSecond=</varname></term> + <listitem> + <para>The speed to set for the device, the value is rounded + down to the nearest Mbps. The usual suffixes K, M, G, are + supported and are understood to the base of 1000.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Duplex=</varname></term> + <listitem> + <para>The duplex mode to set for the device. The accepted + values are <literal>half</literal> and + <literal>full</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>WakeOnLan=</varname></term> + <listitem> + <para>The Wake-on-LAN policy to set for the device. The + supported values are:</para> - <variablelist> - <varlistentry> - <term><literal>phy</literal></term> - <listitem> - <para>Wake on PHY activity.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>magic</literal></term> - <listitem> - <para>Wake on receipt of a magic packet. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>off</literal></term> - <listitem> - <para>Never wake.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> - </refsect1> + <variablelist> + <varlistentry> + <term><literal>phy</literal></term> + <listitem> + <para>Wake on PHY activity.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>magic</literal></term> + <listitem> + <para>Wake on receipt of a magic packet. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>off</literal></term> + <listitem> + <para>Never wake.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </refsect1> - <refsect1> - <title>Example</title> - <example> - <title>/etc/systemd/network/wireless.link</title> + <refsect1> + <title>Example</title> + <example> + <title>/etc/systemd/network/wireless.link</title> - <programlisting>[Match] + <programlisting>[Match] MACAddress=12:34:56:78:9a:bc Driver=brcmsmac Path=pci-0000:02:00.0-* @@ -402,25 +395,25 @@ MTUBytes=1450 BitsPerSecond=10M WakeOnLan=magic MACAddress=cb:a9:87:65:43:21</programlisting> - </example> - </refsect1> + </example> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry> - <refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum> - </citerefentry>, - <citerefentry> - <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum> - </citerefentry>, - <citerefentry> - <refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum> - </citerefentry>, - <citerefentry> - <refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum> - </citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry> + <refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum> + </citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml index 8527386594..bef66a3c0b 100644 --- a/man/systemd.mount.xml +++ b/man/systemd.mount.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,345 +23,309 @@ --> <refentry id="systemd.mount"> - <refentryinfo> - <title>systemd.mount</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd.mount</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.mount</refname> - <refpurpose>Mount unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>mount</replaceable>.mount</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.mount</literal> encodes information about - a file system mount point controlled and supervised by - systemd.</para> - - <para>This man page lists the configuration options - specific to this unit type. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the common options of all unit configuration - files. The common configuration items are configured - in the generic [Unit] and [Install] sections. The - mount specific configuration options are configured - in the [Mount] section.</para> - - <para>Additional options are listed in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the execution environment the - <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> - binary is executed in, and in - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the way the processes are terminated, and - in - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which configure resource control settings for the - processes of the service. Note that the User= and - Group= options are not particularly useful for mount - units specifying a <literal>Type=</literal> option or - using configuration not specified in - <filename>/etc/fstab</filename>; - <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> - 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>.</para> - - <para>Optionally, a mount unit may be accompanied by - an automount unit, to allow on-demand or parallelized - mounting. See - <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>If a mount point is beneath another mount point - in the file system hierarchy, a dependency between both - units is created automatically.</para> - - <para>Mount points created at runtime (independently of - unit files or <filename>/etc/fstab</filename>) will be - monitored by systemd and appear like any other mount - unit in systemd. - See <filename>/proc/self/mountinfo</filename> description - in <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para>Some file systems have special semantics as API - file systems for kernel-to-userspace and - userspace-to-userpace interfaces. Some of them may not - be changed via mount units, and cannot be disabled. - For a longer discussion see <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API - File Systems</ulink>.</para> - </refsect1> - - <refsect1> - <title><filename>fstab</filename></title> - - <para>Mount units may either be configured via unit - files, or via <filename>/etc/fstab</filename> (see - <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). Mounts listed in - <filename>/etc/fstab</filename> will be converted into - native units dynamically at boot and when the - configuration of the system manager is reloaded. In - general, configuring mount points through - <filename>/etc/fstab</filename> is the preferred - approach. See - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details about the conversion.</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 dependency of type - <option>Wants</option> or <option>Requires</option> - (see option <option>nofail</option> below), from - either <filename>local-fs.target</filename> or - <filename>remote-fs.target</filename>, depending - whether the file system is local or remote.</para> - - <variablelist class='fstab-options'> - - <varlistentry> - <term><option>x-systemd.automount</option></term> - - <listitem><para>An automount unit will be created - for the file system. See - <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>x-systemd.device-timeout=</option></term> - - <listitem><para>Configure how long systemd should - wait for a device to show up before giving up on - an entry from - <filename>/etc/fstab</filename>. Specify a time in - seconds or explicitly append a unit as - <literal>s</literal>, <literal>min</literal>, - <literal>h</literal>, - <literal>ms</literal>.</para> - - <para>Note that this option can only be used in - <filename>/etc/fstab</filename>, and will be - ignored when part of <varname>Options=</varname> - setting in a unit file.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>noauto</option></term> - <term><option>auto</option></term> - - <listitem><para>With <option>noauto</option>, this - mount will not be added as a dependency for - <filename>local-fs.target</filename> or - <filename>remote-fs.target</filename>. This means - that it will not be mounted automatically during - boot, unless it is pulled in by some other - unit. Option <option>auto</option> has the - opposite meaning and is the default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>nofail</option></term> - - <listitem><para>With <option>nofail</option> this - mount will be only wanted, not required, by - <filename>local-fs.target</filename> or - <filename>remote-fs.target</filename>. This means - that the boot will continue even if this mount - point is not mounted successfully.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>x-initrd.mount</option></term> - - <listitem><para>An additional filesystem to be - mounted in the initramfs. See - <filename>initrd-fs.target</filename> description - in - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - </variablelist> - - <para>If a mount point is configured in both - <filename>/etc/fstab</filename> and a unit file that - is stored below <filename>/usr</filename>, the former - will take precedence. If the unit file is stored below - <filename>/etc</filename>, it will take - precedence. This means: native unit files take - precedence over traditional configuration files, but - this is superseded by the rule that configuration in - <filename>/etc</filename> will always take precedence - over configuration in - <filename>/usr</filename>.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>Mount files must include a [Mount] section, - which carries information about the file system mount points it - supervises. A number of options that may be used in - this section are shared with other unit types. These - options are documented in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The - options specific to the [Mount] section of mount - units are the following:</para> - - <variablelist class='unit-directives'> - - <varlistentry> - <term><varname>What=</varname></term> - <listitem><para>Takes an absolute path - of a device node, file or other - resource to mount. See - <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details. If this refers to a - device node, a dependency on the - respective device unit is - automatically created. (See - <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.) - This option is - mandatory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Where=</varname></term> - <listitem><para>Takes an absolute path - of a directory of the mount point. If - the mount point does not exist at the - time of mounting, it is created. This - string must be reflected in the unit - filename. (See above.) This option is - mandatory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Type=</varname></term> - <listitem><para>Takes a string for the - file system type. See - <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details. This setting is - optional.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Options=</varname></term> - - <listitem><para>Mount options to use - when mounting. This takes a - comma-separated list of options. This - setting is optional.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SloppyOptions=</varname></term> - - <listitem><para>Takes a boolean - argument. If true, parsing of the - options specified in - <varname>Options=</varname> is - relaxed, and unknown mount options are - tolerated. This corresponds with - <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s - <parameter>-s</parameter> - switch. Defaults to - off.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DirectoryMode=</varname></term> - <listitem><para>Directories of mount - points (and any parent directories) - are automatically created if - needed. This option specifies the file - system access mode used when creating - these directories. Takes an access - mode in octal notation. Defaults to - 0755.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TimeoutSec=</varname></term> - <listitem><para>Configures the time to - wait for the mount command to - finish. If a command does not exit - within the configured time, the mount - will be considered failed and be shut - down again. All commands still running - will be terminated forcibly via - <constant>SIGTERM</constant>, and after another delay of - this time with <constant>SIGKILL</constant>. (See - <option>KillMode=</option> in - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) - Takes a unit-less value in seconds, or - a time span value such as "5min - 20s". Pass 0 to disable the timeout - logic. The default value is set from the manager configuration - file's <varname>DefaultTimeoutStart=</varname> variable.</para></listitem> - </varlistentry> - </variablelist> - - <para>Check - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more settings.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd.mount</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.mount</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.mount</refname> + <refpurpose>Mount unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>mount</replaceable>.mount</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.mount</literal> encodes information about a file system + mount point controlled and supervised by systemd.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. The mount specific configuration options are + configured in the [Mount] section.</para> + + <para>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + binary is executed in, and in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the way the processes are terminated, and in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which configure resource control settings for the processes of the + service. Note that the User= and Group= options are not + particularly useful for mount units specifying a + <literal>Type=</literal> option or using configuration not + specified in <filename>/etc/fstab</filename>; + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + 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>.</para> + + <para>Optionally, a mount unit may be accompanied by an automount + unit, to allow on-demand or parallelized mounting. See + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>If a mount point is beneath another mount point in the file + system hierarchy, a dependency between both units is created + automatically.</para> + + <para>Mount points created at runtime (independently of unit files + or <filename>/etc/fstab</filename>) will be monitored by systemd + and appear like any other mount unit in systemd. See + <filename>/proc/self/mountinfo</filename> description in + <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>Some file systems have special semantics as API file systems + for kernel-to-userspace and userspace-to-userpace interfaces. Some + of them may not be changed via mount units, and cannot be + disabled. For a longer discussion see <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API + File Systems</ulink>.</para> + </refsect1> + + <refsect1> + <title><filename>fstab</filename></title> + + <para>Mount units may either be configured via unit files, or via + <filename>/etc/fstab</filename> (see + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Mounts listed in <filename>/etc/fstab</filename> + will be converted into native units dynamically at boot and when + the configuration of the system manager is reloaded. In general, + configuring mount points through <filename>/etc/fstab</filename> + is the preferred approach. See + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details about the conversion.</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 + dependency of type <option>Wants</option> or + <option>Requires</option> (see option <option>nofail</option> + below), from either <filename>local-fs.target</filename> or + <filename>remote-fs.target</filename>, depending whether the file + system is local or remote.</para> + + <variablelist class='fstab-options'> + + <varlistentry> + <term><option>x-systemd.automount</option></term> + + <listitem><para>An automount unit will be created for the file + system. See + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.device-timeout=</option></term> + + <listitem><para>Configure how long systemd should wait for a + device to show up before giving up on an entry from + <filename>/etc/fstab</filename>. Specify a time in seconds or + explicitly append a unit as <literal>s</literal>, + <literal>min</literal>, <literal>h</literal>, + <literal>ms</literal>.</para> + + <para>Note that this option can only be used in + <filename>/etc/fstab</filename>, and will be + ignored when part of <varname>Options=</varname> + setting in a unit file.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>noauto</option></term> + <term><option>auto</option></term> + + <listitem><para>With <option>noauto</option>, this mount will + not be added as a dependency for + <filename>local-fs.target</filename> or + <filename>remote-fs.target</filename>. This means that it will + not be mounted automatically during boot, unless it is pulled + in by some other unit. Option <option>auto</option> has the + opposite meaning and is the default.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>nofail</option></term> + + <listitem><para>With <option>nofail</option> this mount will + be only wanted, not required, by + <filename>local-fs.target</filename> or + <filename>remote-fs.target</filename>. This means that the + boot will continue even if this mount point is not mounted + successfully.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>x-initrd.mount</option></term> + + <listitem><para>An additional filesystem to be mounted in the + initramfs. See <filename>initrd-fs.target</filename> + description in + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <para>If a mount point is configured in both + <filename>/etc/fstab</filename> and a unit file that is stored + below <filename>/usr</filename>, the former will take precedence. + If the unit file is stored below <filename>/etc</filename>, it + will take precedence. This means: native unit files take + precedence over traditional configuration files, but this is + superseded by the rule that configuration in + <filename>/etc</filename> will always take precedence over + configuration in <filename>/usr</filename>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Mount files must include a [Mount] section, which carries + information about the file system mount points it supervises. A + number of options that may be used in this section are shared with + other unit types. These options are documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + The options specific to the [Mount] section of mount units are the + following:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>What=</varname></term> + <listitem><para>Takes an absolute path of a device node, file + or other resource to mount. See + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details. If this refers to a device node, a dependency on + the respective device unit is automatically created. (See + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.) This option is + mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Where=</varname></term> + <listitem><para>Takes an absolute path of a directory of the + mount point. If the mount point does not exist at the time of + mounting, it is created. This string must be reflected in the + unit filename. (See above.) This option is + mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Type=</varname></term> + <listitem><para>Takes a string for the file system type. See + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details. This setting is optional.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Options=</varname></term> + + <listitem><para>Mount options to use when mounting. This takes + a comma-separated list of options. This setting is + optional.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SloppyOptions=</varname></term> + + <listitem><para>Takes a boolean argument. If true, parsing of + the options specified in <varname>Options=</varname> is + relaxed, and unknown mount options are tolerated. This + corresponds with + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <parameter>-s</parameter> switch. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + <listitem><para>Directories of mount points (and any parent + directories) are automatically created if needed. This option + specifies the file system access mode used when creating these + directories. Takes an access mode in octal notation. Defaults + to 0755.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>Configures the time to wait for the mount + command to finish. If a command does not exit within the + configured time, the mount will be considered failed and be + shut down again. All commands still running will be terminated + forcibly via <constant>SIGTERM</constant>, and after another + delay of this time with <constant>SIGKILL</constant>. (See + <option>KillMode=</option> in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Pass 0 to disable the timeout logic. The + default value is set from the manager configuration file's + <varname>DefaultTimeoutStart=</varname> + variable.</para></listitem> + </varlistentry> + </variablelist> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index e278aa1a80..4480e1999d 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,609 +23,647 @@ <refentry id="systemd.netdev" conditional='ENABLE_NETWORKD'> - <refentryinfo> - <title>systemd.network</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd.netdev</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.netdev</refname> - <refpurpose>Virtual Network Device configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>netdev</replaceable>.netdev</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>Network setup is performed by - <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para> - - <para>Virtual Network Device files must have the extension - <filename>.netdev</filename>; other extensions are ignored. Virtual - network devices are created as soon as networkd is started. If a netdev - with the specified name already exists, networkd will use that as-is - rather than create its own. Note that the settings of the pre-existing - netdev will not be changed by networkd.</para> - - <para>The <filename>.netdev</filename> files are read from the files located in the - system network directory <filename>/usr/lib/systemd/network</filename>, - the volatile runtime network directory - <filename>/run/systemd/network</filename> and the local administration - network directory <filename>/etc/systemd/network</filename>. - All configuration files are collectively sorted and processed in lexical order, - regardless of the directories in which they live. However, files with - identical filenames replace each other. Files in - <filename>/etc</filename> have the highest priority, files in - <filename>/run</filename> take precedence over files with the same - name in <filename>/usr/lib</filename>. This can be used to override a - system-supplied configuration file with a local file if needed; a symlink in - <filename>/etc</filename> with the same name as a configuration file in - <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>, - disables the configuration file entirely.</para> - - </refsect1> - - <refsect1> - <title>Supported netdev kinds</title> - - <para>The following kinds of virtual network devices may be configured in <filename>.netdev</filename> files:</para> - - <table> - <title>Supported kinds of virtual network devices</title> - - <tgroup cols='2'> - <colspec colname='kind' /> - <colspec colname='explanation' /> - <thead><row> - <entry>Kind</entry> - <entry>Description</entry> - </row></thead> - <tbody> - <row><entry><varname>bond</varname></entry> - <entry>A bond device is an aggregation of all its slave devices. See <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">Linux Ethernet Bonding Driver HOWTO</ulink> for details.Local configuration</entry></row> - - <row><entry><varname>bridge</varname></entry> - <entry>A bridge devcie is a software switch, each of its slave devices and the bridge itself are ports of the switch.</entry></row> - - <row><entry><varname>dummy</varname></entry> - <entry>A dummy device drops all packets sent to it.</entry></row> - - <row><entry><varname>gre</varname></entry> - <entry>A Level 3 GRE tunnel over IPv4. See <ulink url="https://tools.ietf.org/html/rfc2784">RFC 2784</ulink> for details.</entry></row> - - <row><entry><varname>gretap</varname></entry> - <entry>A Level 2 GRE tunnel over IPv4.</entry></row> - - <row><entry><varname>ip6gre</varname></entry> - <entry>A Level 3 GRE tunnel over IPv6.</entry></row> - - <row><entry><varname>ip6tnl</varname></entry> - <entry>An IPv4 or IPv6 tunnel over IPv6</entry></row> - - <row><entry><varname>ip6gretap</varname></entry> - <entry>An Level 2 GRE tunnel over IPv6.</entry></row> - - <row><entry><varname>ipip</varname></entry> - <entry>An IPv4 over IPv4 tunnel.</entry></row> - - <row><entry><varname>ipvlan</varname></entry> - <entry>An ipvlan device is a stacked device which receives packets from its underlying device based on IP address filtering.</entry></row> - - <row><entry><varname>macvlan</varname></entry> - <entry>A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row> - - <row><entry><varname>sit</varname></entry> - <entry>An IPv6 over IPv4 tunnel.</entry></row> - - <row><entry><varname>tap</varname></entry> - <entry>A persistent Level 2 tunnel between a network device and a device node.</entry></row> - - <row><entry><varname>tun</varname></entry> - <entry>A persistent Level 3 tunnel between a network device and a device node.</entry></row> - - <row><entry><varname>veth</varname></entry> - <entry>An ethernet tunnel between a pair of network devices.</entry></row> - - <row><entry><varname>vlan</varname></entry> - <entry>A VLAN is a stacked device which receives packets from its underlying device based on VLAN tagging. See <ulink url="http://www.ieee802.org/1/pages/802.1Q.html">IEEE 802.1Q</ulink> for details.</entry></row> - - <row><entry><varname>vti</varname></entry> - <entry>An IPv4 over IPSec tunnel.</entry></row> - - <row><entry><varname>vxlan</varname></entry> - <entry>A virtual extensible LAN (vxlan), for connecting Cloud computing deployments.</entry></row> - </tbody> - </tgroup> - </table> - - </refsect1> - - <refsect1> - <title>[Match] Section Options</title> - - <para>A virtual network device is only created if the - <literal>[Match]</literal> section matches the current - environment, or if the section is empty. The following keys are accepted:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Host=</varname></term> - <listitem> - <para>Matches against the hostname or machine ID of the - host. See <literal>ConditionHost=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Virtualization=</varname></term> - <listitem> - <para>Checks whether the system is executed in a virtualized - environment and optionally test whether it is a specific - implementation. See <literal>ConditionVirtualization=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>KernelCommandLine=</varname></term> - <listitem> - <para>Checks whether a specific kernel command line option is - set (or if prefixed with the exclamation mark unset). See - <literal>ConditionKernelCommandLine=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Architecture=</varname></term> - <listitem> - <para>Checks whether the system is running on a specific - architecture. See <literal>ConditionArchitecture=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[NetDev] Section Options</title> - - <para>The <literal>[NetDev]</literal> section accepts the following - keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Description=</varname></term> - <listitem> - <para>A free-form description of the netdev. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Name=</varname></term> - <listitem> - <para>The interface name used when creating the - netdev. This option is compulsory.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Kind=</varname></term> - <listitem> - <para>The netdev kind. This option is compulsory. See the <literal>Supported netdev kinds</literal> section - for the valid keys.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MTUBytes=</varname></term> - <listitem> - <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. This key is not currently suported for - <literal>tun</literal> or <literal>tap</literal> devices. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The MAC address to use for the device. - If none is given, one is generated based on - the interface name and the - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - This key is not currently suported for <literal>tun</literal> or <literal>tap</literal> devices. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>[VLAN] Section Options</title> - - <para>The <literal>[VLAN]</literal> section only applies for netdevs of kind <literal>vlan</literal>, - and accepts the following key:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Id=</varname></term> - <listitem> - <para>The VLAN ID to use. An integer in the range 0–4094. - This option is compulsory.</para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[MACVLAN] Section Options</title> - - <para>The <literal>[MACVLAN]</literal> section only applies for netdevs of kind - <literal>macvlan</literal>, and accepts the following key:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Mode=</varname></term> - <listitem> - <para>The MACVLAN mode to use. The supported options are - <literal>private</literal>, <literal>vepa</literal>, - <literal>bridge</literal> and <literal>passthru</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[IPVLAN] Section Options</title> - - <para>The <literal>[IPVLAN]</literal> section only applies for netdevs of kind - <literal>ipvlan</literal>, and accepts the following key:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Mode=</varname></term> - <listitem> - <para>The IPVLAN mode to use. The supported options are - <literal>L2</literal> and <literal>L3</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[VXLAN] Section Options</title> - <para>The <literal>[VXLAN]</literal> section only applies for netdevs of kind - <literal>vxlan</literal>, and accepts the following key:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Id=</varname></term> - <listitem> - <para>The VXLAN ID to use.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Group=</varname></term> - <listitem> - <para>An assigned multicast group IP address.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>TOS=</varname></term> - <listitem> - <para>The Type Of Service byte value for a vxlan interface.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>TTL=</varname></term> - <listitem> - <para>A fixed Time To Live N on Virtual eXtensible Local Area Network packets. - N is a number in the range 1-255. 0 is a special value meaning that packets - inherit the TTL value.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MacLearning=</varname></term> - <listitem> - <para>A boolean. When true, enables dynamic MAC learning - to discover remote MAC addresses.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>FDBAgeingSec=</varname></term> - <listitem> - <para>The lifetime of Forwarding Database entry learnt by the kernel in seconds.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>ARPProxy=</varname></term> - <listitem> - <para>A boolean. When true, enables ARP proxy.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>L2MissNotification=</varname></term> - <listitem> - <para>A boolean. When true, enables netlink LLADDR miss notifications.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>L3MissNotification=</varname></term> - <listitem> - <para>A boolean. When true, enables netlink IP ADDR miss notifications.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>RouteShortCircuit=</varname></term> - <listitem> - <para>A boolean. When true route short circuit is turned on.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> - <title>[Tunnel] Section Options</title> - - <para>The <literal>[Tunnel]</literal> section only applies for netdevs of kind - <literal>ipip</literal>, <literal>sit</literal>, <literal>gre</literal>, <literal>gretap</literal>, - <literal>ip6gre</literal>, <literal>ip6gretap</literal>, <literal>vti</literal> and <literal>ip6tnl</literal> - and accepts the following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Local=</varname></term> - <listitem> - <para>A static local address for tunneled packets. - It must be an address on another interface of this host.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Remote=</varname></term> - <listitem> - <para>The remote endpoint of the tunnel.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>TOS=</varname></term> - <listitem> - <para>The Type Of Service byte value for a tunnel interface. - For details about the TOS see the - <ulink url="http://tools.ietf.org/html/rfc1349"> - Type of Service in the Internet Protocol Suite - </ulink> document. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>TTL=</varname></term> - <listitem> - <para>A fixed Time To Live N on tunneled packets. - N is a number in the range 1-255. 0 is a special value meaning that packets - inherit the TTL value. The default value for IPv4 tunnels is: inherit. - The default value for IPv6 tunnels is: 64.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DiscoverPathMTU=</varname></term> - <listitem> - <para>A boolean. When true, enables Path MTU Discovery on the tunnel.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Mode=</varname></term> - <listitem> - <para>An <literal>ip6tnl</literal> tunnels can have three modes - <literal>ip6ip6</literal> for IPv6 over IPv6, - <literal>ipip6</literal> for IPv4 over IPv6 or - <literal>any</literal> for either. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> - <title>[Peer] Section Options</title> - - <para>The <literal>[Peer]</literal> section only applies for netdevs of kind <literal>veth</literal> - and accepts the following key:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Name=</varname></term> - <listitem> - <para>The interface name used when creating the netdev. - This option is compulsory.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The peer MACAddress, if not set it is generated in the same - way as the MAC address of the main interface.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> - <title>[Tun] Section Options</title> - - <para>The <literal>[Tun]</literal> section only applies for netdevs of kind - <literal>tun</literal>, and accepts the following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>OneQueue=</varname></term> - <listitem><para>Takes a boolean argument. Configures whether - all packets are queued at the device (enabled), or a fixed number - of packets are queued at the device and the rest at the - <literal>qdisc</literal>. Defaults to <literal>no</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MultiQueue=</varname></term> - <listitem><para>Takes a boolean argument. Configures whether to - use multiple file descriptors (queues) to parallelize packets - sending and receiving. Defaults to <literal>no</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>PacketInfo=</varname></term> - <listitem><para>Takes a boolean argument. Configures whether packets - should be prepened with four extra bytes (two flag bytes and two - protocol bytes). If disabled it indicates that the packets will be - pure IP packets. Defaults to <literal>no</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>User=</varname></term> - <listitem><para>User to grant access to the <filename>/dev/net/tun</filename> - device.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Group=</varname></term> - <listitem><para>Group to grant access to the <filename>/dev/net/tun</filename> - device.</para> - </listitem> - </varlistentry> - - </variablelist> - - </refsect1> - - <refsect1> - <title>[Tap] Section Options</title> - - <para>The <literal>[Tap]</literal> section only applies for netdevs of kind - <literal>tap</literal>, and accepts the same keys as the - <literal>[Tun]</literal> section.</para> - </refsect1> - - <refsect1> - <title>[Bond] Section Options</title> - - <para>The <literal>[Bond]</literal> section accepts the following - key:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Mode=</varname></term> - <listitem> - <para>Specifies one of the bonding policies. The default is - <literal>balance-rr</literal> (round robin). Possible values are - <literal>balance-rr</literal>, - <literal>active-backup</literal>, - <literal>balance-xor</literal>, - <literal>broadcast</literal>, - <literal>802.3ad</literal>, - <literal>balance-tlb</literal>, and - <literal>balance-alb</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>TransmitHashPolicy=</varname></term> - <listitem> - <para>Selects the transmit hash policy to use for slave selection in - balance-xor, 802.3ad, and tlb modes. Possible values are - <literal>layer2</literal>, - <literal>layer3+4</literal>, - <literal>layer2+3</literal>, - <literal>encap2+3</literal>, - <literal>802.3ad</literal>, and - <literal>encap3+4</literal>. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>LACPTransmitRate=</varname></term> - <listitem> - <para>Specifies the rate with which link partner - transmits Link Aggregation Control Protocol Data Unit packets - in 802.3ad mode. Possible values are - <literal>slow</literal>, which requests partner to transmit LACPDUs every 30 seconds, and - <literal>fast</literal>, which requests partner to transmit LACPDUs every second. - The default value is <literal>slow</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>MIIMonitorSec=</varname></term> - <listitem> - <para>Specifies the frequency that Media Independent Interface link - monitoring will occur. A value of zero disables MII link monitoring. - This values is rounded down to the nearest millisecond. The default - value is 0.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>UpDelaySec=</varname></term> - <listitem> - <para>Specifies the delay before a link is enabled after a link up - status has been detected. This value is rounded down to a multiple of - MIIMonitorSec. The default value is 0.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>DownDelaySec=</varname></term> - <listitem> - <para>Specifies the delay before a link is disabled after a link down - status has been detected. This value is rounded down to a multiple of - MIIMonitorSec. The default value is 0.</para> - </listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Example</title> - <example> - <title>/etc/systemd/network/bridge.netdev</title> - - <programlisting>[NetDev] + <refentryinfo> + <title>systemd.network</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + <email>teg@jklm.no</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.netdev</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.netdev</refname> + <refpurpose>Virtual Network Device configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>netdev</replaceable>.netdev</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Network setup is performed by + <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> + + <para>Virtual Network Device files must have the extension + <filename>.netdev</filename>; other extensions are ignored. + Virtual network devices are created as soon as networkd is + started. If a netdev with the specified name already exists, + networkd will use that as-is rather than create its own. Note that + the settings of the pre-existing netdev will not be changed by + networkd.</para> + + <para>The <filename>.netdev</filename> files are read from the + files located in the system network directory + <filename>/usr/lib/systemd/network</filename>, the volatile + runtime network directory + <filename>/run/systemd/network</filename> and the local + administration network directory + <filename>/etc/systemd/network</filename>. All configuration files + are collectively sorted and processed in lexical order, regardless + of the directories in which they live. However, files with + identical filenames replace each other. Files in + <filename>/etc</filename> have the highest priority, files in + <filename>/run</filename> take precedence over files with the same + name in <filename>/usr/lib</filename>. This can be used to + override a system-supplied configuration file with a local file if + needed; a symlink in <filename>/etc</filename> with the same name + as a configuration file in <filename>/usr/lib</filename>, pointing + to <filename>/dev/null</filename>, disables the configuration file + entirely.</para> + + </refsect1> + + <refsect1> + <title>Supported netdev kinds</title> + + <para>The following kinds of virtual network devices may be + configured in <filename>.netdev</filename> files:</para> + + <table> + <title>Supported kinds of virtual network devices</title> + + <tgroup cols='2'> + <colspec colname='kind' /> + <colspec colname='explanation' /> + <thead><row> + <entry>Kind</entry> + <entry>Description</entry> + </row></thead> + <tbody> + <row><entry><varname>bond</varname></entry> + <entry>A bond device is an aggregation of all its slave devices. See <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">Linux Ethernet Bonding Driver HOWTO</ulink> for details.Local configuration</entry></row> + + <row><entry><varname>bridge</varname></entry> + <entry>A bridge devcie is a software switch, each of its slave devices and the bridge itself are ports of the switch.</entry></row> + + <row><entry><varname>dummy</varname></entry> + <entry>A dummy device drops all packets sent to it.</entry></row> + + <row><entry><varname>gre</varname></entry> + <entry>A Level 3 GRE tunnel over IPv4. See <ulink url="https://tools.ietf.org/html/rfc2784">RFC 2784</ulink> for details.</entry></row> + + <row><entry><varname>gretap</varname></entry> + <entry>A Level 2 GRE tunnel over IPv4.</entry></row> + + <row><entry><varname>ip6gre</varname></entry> + <entry>A Level 3 GRE tunnel over IPv6.</entry></row> + + <row><entry><varname>ip6tnl</varname></entry> + <entry>An IPv4 or IPv6 tunnel over IPv6</entry></row> + + <row><entry><varname>ip6gretap</varname></entry> + <entry>An Level 2 GRE tunnel over IPv6.</entry></row> + + <row><entry><varname>ipip</varname></entry> + <entry>An IPv4 over IPv4 tunnel.</entry></row> + + <row><entry><varname>ipvlan</varname></entry> + <entry>An ipvlan device is a stacked device which receives packets from its underlying device based on IP address filtering.</entry></row> + + <row><entry><varname>macvlan</varname></entry> + <entry>A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row> + + <row><entry><varname>sit</varname></entry> + <entry>An IPv6 over IPv4 tunnel.</entry></row> + + <row><entry><varname>tap</varname></entry> + <entry>A persistent Level 2 tunnel between a network device and a device node.</entry></row> + + <row><entry><varname>tun</varname></entry> + <entry>A persistent Level 3 tunnel between a network device and a device node.</entry></row> + + <row><entry><varname>veth</varname></entry> + <entry>An ethernet tunnel between a pair of network devices.</entry></row> + + <row><entry><varname>vlan</varname></entry> + <entry>A VLAN is a stacked device which receives packets from its underlying device based on VLAN tagging. See <ulink url="http://www.ieee802.org/1/pages/802.1Q.html">IEEE 802.1Q</ulink> for details.</entry></row> + + <row><entry><varname>vti</varname></entry> + <entry>An IPv4 over IPSec tunnel.</entry></row> + + <row><entry><varname>vxlan</varname></entry> + <entry>A virtual extensible LAN (vxlan), for connecting Cloud computing deployments.</entry></row> + </tbody> + </tgroup> + </table> + + </refsect1> + + <refsect1> + <title>[Match] Section Options</title> + + <para>A virtual network device is only created if the + <literal>[Match]</literal> section matches the current + environment, or if the section is empty. The following keys are + accepted:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Host=</varname></term> + <listitem> + <para>Matches against the hostname or machine ID of the + host. See <literal>ConditionHost=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Virtualization=</varname></term> + <listitem> + <para>Checks whether the system is executed in a virtualized + environment and optionally test whether it is a specific + implementation. See + <literal>ConditionVirtualization=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>KernelCommandLine=</varname></term> + <listitem> + <para>Checks whether a specific kernel command line option + is set (or if prefixed with the exclamation mark unset). See + <literal>ConditionKernelCommandLine=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Architecture=</varname></term> + <listitem> + <para>Checks whether the system is running on a specific + architecture. See <literal>ConditionArchitecture=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[NetDev] Section Options</title> + + <para>The <literal>[NetDev]</literal> section accepts the + following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Description=</varname></term> + <listitem> + <para>A free-form description of the netdev.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Name=</varname></term> + <listitem> + <para>The interface name used when creating the netdev. + This option is compulsory.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Kind=</varname></term> + <listitem> + <para>The netdev kind. This option is compulsory. See the + <literal>Supported netdev kinds</literal> section for the + valid keys.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MTUBytes=</varname></term> + <listitem> + <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. This key is not + currently suported for <literal>tun</literal> or + <literal>tap</literal> devices. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The MAC address to use for the device. If none is + given, one is generated based on the interface name and + the + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + This key is not currently suported for + <literal>tun</literal> or <literal>tap</literal> devices. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[VLAN] Section Options</title> + + <para>The <literal>[VLAN]</literal> section only applies for + netdevs of kind <literal>vlan</literal>, and accepts the + following key:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Id=</varname></term> + <listitem> + <para>The VLAN ID to use. An integer in the range 0–4094. + This option is compulsory.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[MACVLAN] Section Options</title> + + <para>The <literal>[MACVLAN]</literal> section only applies for + netdevs of kind <literal>macvlan</literal>, and accepts the + following key:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Mode=</varname></term> + <listitem> + <para>The MACVLAN mode to use. The supported options are + <literal>private</literal>, + <literal>vepa</literal>, + <literal>bridge</literal>, and + <literal>passthru</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[IPVLAN] Section Options</title> + + <para>The <literal>[IPVLAN]</literal> section only applies for + netdevs of kind <literal>ipvlan</literal>, and accepts the + following key:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Mode=</varname></term> + <listitem> + <para>The IPVLAN mode to use. The supported options are + <literal>L2</literal> and <literal>L3</literal>. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[VXLAN] Section Options</title> + <para>The <literal>[VXLAN]</literal> section only applies for + netdevs of kind <literal>vxlan</literal>, and accepts the + following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Id=</varname></term> + <listitem> + <para>The VXLAN ID to use.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Group=</varname></term> + <listitem> + <para>An assigned multicast group IP address.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>TOS=</varname></term> + <listitem> + <para>The Type Of Service byte value for a vxlan interface.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>TTL=</varname></term> + <listitem> + <para>A fixed Time To Live N on Virtual eXtensible Local + Area Network packets. N is a number in the range 1-255. 0 + is a special value meaning that packets inherit the TTL + value.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MacLearning=</varname></term> + <listitem> + <para>A boolean. When true, enables dynamic MAC learning + to discover remote MAC addresses.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>FDBAgeingSec=</varname></term> + <listitem> + <para>The lifetime of Forwarding Database entry learnt by + the kernel in seconds.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ARPProxy=</varname></term> + <listitem> + <para>A boolean. When true, enables ARP proxy.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>L2MissNotification=</varname></term> + <listitem> + <para>A boolean. When true, enables netlink LLADDR miss + notifications.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>L3MissNotification=</varname></term> + <listitem> + <para>A boolean. When true, enables netlink IP ADDR miss + notifications.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>RouteShortCircuit=</varname></term> + <listitem> + <para>A boolean. When true route short circuit is turned + on.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>[Tunnel] Section Options</title> + + <para>The <literal>[Tunnel]</literal> section only applies for + netdevs of kind + <literal>ipip</literal>, + <literal>sit</literal>, + <literal>gre</literal>, + <literal>gretap</literal>, + <literal>ip6gre</literal>, + <literal>ip6gretap</literal>, + <literal>vti</literal>, and + <literal>ip6tnl</literal> and accepts + the following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Local=</varname></term> + <listitem> + <para>A static local address for tunneled packets. It must + be an address on another interface of this host.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Remote=</varname></term> + <listitem> + <para>The remote endpoint of the tunnel.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>TOS=</varname></term> + <listitem> + <para>The Type Of Service byte value for a tunnel interface. + For details about the TOS see the + <ulink url="http://tools.ietf.org/html/rfc1349"> Type of + Service in the Internet Protocol Suite </ulink> document. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>TTL=</varname></term> + <listitem> + <para>A fixed Time To Live N on tunneled packets. N is a + number in the range 1-255. 0 is a special value meaning that + packets inherit the TTL value. The default value for IPv4 + tunnels is: inherit. The default value for IPv6 tunnels is: + 64.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DiscoverPathMTU=</varname></term> + <listitem> + <para>A boolean. When true, enables Path MTU Discovery on + the tunnel.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Mode=</varname></term> + <listitem> + <para>An <literal>ip6tnl</literal> tunnels can have three + modes + <literal>ip6ip6</literal> for IPv6 over IPv6, + <literal>ipip6</literal> for IPv4 over IPv6 or + <literal>any</literal> for either. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>[Peer] Section Options</title> + + <para>The <literal>[Peer]</literal> section only applies for + netdevs of kind <literal>veth</literal> and accepts the + following key:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Name=</varname></term> + <listitem> + <para>The interface name used when creating the netdev. + This option is compulsory.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The peer MACAddress, if not set it is generated in + the same way as the MAC address of the main + interface.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>[Tun] Section Options</title> + + <para>The <literal>[Tun]</literal> section only applies for + netdevs of kind <literal>tun</literal>, and accepts the following + keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>OneQueue=</varname></term> + <listitem><para>Takes a boolean argument. Configures whether + all packets are queued at the device (enabled), or a fixed + number of packets are queued at the device and the rest at the + <literal>qdisc</literal>. Defaults to + <literal>no</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MultiQueue=</varname></term> + <listitem><para>Takes a boolean argument. Configures whether + to use multiple file descriptors (queues) to parallelize + packets sending and receiving. Defaults to + <literal>no</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PacketInfo=</varname></term> + <listitem><para>Takes a boolean argument. Configures whether + packets should be prepened with four extra bytes (two flag + bytes and two protocol bytes). If disabled it indicates that + the packets will be pure IP packets. Defaults to + <literal>no</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>User=</varname></term> + <listitem><para>User to grant access to the + <filename>/dev/net/tun</filename> device.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Group=</varname></term> + <listitem><para>Group to grant access to the + <filename>/dev/net/tun</filename> device.</para> + </listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>[Tap] Section Options</title> + + <para>The <literal>[Tap]</literal> section only applies for + netdevs of kind <literal>tap</literal>, and accepts the same keys + as the <literal>[Tun]</literal> section.</para> + </refsect1> + + <refsect1> + <title>[Bond] Section Options</title> + + <para>The <literal>[Bond]</literal> section accepts the following + key:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Mode=</varname></term> + <listitem> + <para>Specifies one of the bonding policies. The default is + <literal>balance-rr</literal> (round robin). Possible values are + <literal>balance-rr</literal>, + <literal>active-backup</literal>, + <literal>balance-xor</literal>, + <literal>broadcast</literal>, + <literal>802.3ad</literal>, + <literal>balance-tlb</literal>, and + <literal>balance-alb</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>TransmitHashPolicy=</varname></term> + <listitem> + <para>Selects the transmit hash policy to use for slave + selection in balance-xor, 802.3ad, and tlb modes. Possible + values are + <literal>layer2</literal>, + <literal>layer3+4</literal>, + <literal>layer2+3</literal>, + <literal>encap2+3</literal>, + <literal>802.3ad</literal>, and + <literal>encap3+4</literal>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>LACPTransmitRate=</varname></term> + <listitem> + <para>Specifies the rate with which link partner transmits + Link Aggregation Control Protocol Data Unit packets in + 802.3ad mode. Possible values are <literal>slow</literal>, + which requests partner to transmit LACPDUs every 30 seconds, + and <literal>fast</literal>, which requests partner to + transmit LACPDUs every second. The default value is + <literal>slow</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>MIIMonitorSec=</varname></term> + <listitem> + <para>Specifies the frequency that Media Independent + Interface link monitoring will occur. A value of zero + disables MII link monitoring. This values is rounded down to + the nearest millisecond. The default value is 0.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>UpDelaySec=</varname></term> + <listitem> + <para>Specifies the delay before a link is enabled after a + link up status has been detected. This value is rounded down + to a multiple of MIIMonitorSec. The default value is + 0.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>DownDelaySec=</varname></term> + <listitem> + <para>Specifies the delay before a link is disabled after a + link down status has been detected. This value is rounded + down to a multiple of MIIMonitorSec. The default value is + 0.</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/systemd/network/bridge.netdev</title> + + <programlisting>[NetDev] Name=bridge0 Kind=bridge</programlisting> - </example> + </example> - <example> - <title>/etc/systemd/network/vlan1.netdev</title> + <example> + <title>/etc/systemd/network/vlan1.netdev</title> - <programlisting>[Match] + <programlisting>[Match] Virtualization=no [NetDev] @@ -634,10 +672,10 @@ Kind=vlan [VLAN] Id=1</programlisting> - </example> - <example> - <title>/etc/systemd/network/ipip.netdev</title> - <programlisting>[NetDev] + </example> + <example> + <title>/etc/systemd/network/ipip.netdev</title> + <programlisting>[NetDev] Name=ipip-tun Kind=ipip MTUBytes=1480 @@ -646,10 +684,10 @@ MTUBytes=1480 Local=192.168.223.238 Remote=192.169.224.239 TTL=64</programlisting> - </example> - <example> - <title>/etc/systemd/network/tap.netdev</title> - <programlisting>[NetDev] + </example> + <example> + <title>/etc/systemd/network/tap.netdev</title> + <programlisting>[NetDev] Name=tap-test Kind=tap @@ -657,9 +695,9 @@ Kind=tap MultiQueue=true PacketInfo=true</programlisting> </example> - <example> - <title>/etc/systemd/network/sit.netdev</title> - <programlisting>[NetDev] + <example> + <title>/etc/systemd/network/sit.netdev</title> + <programlisting>[NetDev] Name=sit-tun Kind=sit MTUBytes=1480 @@ -667,11 +705,11 @@ MTUBytes=1480 [Tunnel] Local=10.65.223.238 Remote=10.65.223.239</programlisting> - </example> + </example> - <example> - <title>/etc/systemd/network/gre.netdev</title> - <programlisting>[NetDev] + <example> + <title>/etc/systemd/network/gre.netdev</title> + <programlisting>[NetDev] Name=gre-tun Kind=gre MTUBytes=1480 @@ -679,12 +717,12 @@ MTUBytes=1480 [Tunnel] Local=10.65.223.238 Remote=10.65.223.239</programlisting> - </example> + </example> - <example> - <title>/etc/systemd/network/vti.netdev</title> + <example> + <title>/etc/systemd/network/vti.netdev</title> - <programlisting>[NetDev] + <programlisting>[NetDev] Name=vti-tun Kind=vti MTUBytes=1480 @@ -692,35 +730,35 @@ MTUBytes=1480 [Tunnel] Local=10.65.223.238 Remote=10.65.223.239</programlisting> - </example> + </example> - <example> - <title>/etc/systemd/network/veth.netdev</title> - <programlisting>[NetDev] + <example> + <title>/etc/systemd/network/veth.netdev</title> + <programlisting>[NetDev] Name=veth-test Kind=veth [Peer] Name=veth-peer</programlisting> - </example> + </example> - <example> - <title>/etc/systemd/network/dummy.netdev</title> - <programlisting>[NetDev] + <example> + <title>/etc/systemd/network/dummy.netdev</title> + <programlisting>[NetDev] Name=dummy-test Kind=dummy MACAddress=12:34:56:78:9a:bc</programlisting> - </example> - - </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + </example> + + </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.network.xml b/man/systemd.network.xml index c072f08f61..b8facdc0af 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,682 +23,679 @@ <refentry id="systemd.network" conditional='ENABLE_NETWORKD'> - <refentryinfo> - <title>systemd.network</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd.network</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.network</refname> - <refpurpose>Network configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>network</replaceable>.network</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>Network setup is performed by - <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. - </para> - - <para>Network files must have the extension <filename>.network</filename>; - other extensions are ignored. Networks are applied to links whenever the links - appear.</para> - - <para>The <filename>.network</filename> files are read from the files located in the - system network directory <filename>/usr/lib/systemd/network</filename>, - the volatile runtime network directory - <filename>/run/systemd/network</filename> and the local administration - network directory <filename>/etc/systemd/network</filename>. - All configuration files are collectively sorted and processed in lexical order, - regardless of the directories in which they live. However, files with - identical filenames replace each other. Files in - <filename>/etc</filename> have the highest priority, files in - <filename>/run</filename> take precedence over files with the same - name in <filename>/usr/lib</filename>. This can be used to override a - system-supplied configuration file with a local file if needed; a symlink in - <filename>/etc</filename> with the same name as a configuration file in - <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>, - disables the configuration file entirely.</para> - - </refsect1> - - <refsect1> - <title>[Match] Section Options</title> - - <para>The network file contains a <literal>[Match]</literal> section, - which determines if a given network file may be applied to a given device; - and a <literal>[Network]</literal> section specifying how the device should - be configured. The first (in lexical order) of the network files that - matches a given device is applied.</para> - - <para>A network file is said to match a device if each of the entries in the - <literal>[Match]</literal> section matches, or if the section is empty. - The following keys are accepted:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The hardware address.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Path=</varname></term> - <listitem> - <para>The persistent path, as exposed by the udev - property <literal>ID_PATH</literal>. May contain shell - style globs.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Driver=</varname></term> - <listitem> - <para>The driver currently bound to the device, as - exposed by the udev property <literal>DRIVER</literal> - of its parent device, or if that is not set the driver - as exposed by <literal>ethtool -i</literal> of the - device itself.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Type=</varname></term> - <listitem> - <para>The device type, as exposed by the udev property - <literal>DEVTYPE</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Name=</varname></term> - <listitem> - <para>The device name, as exposed by the udev property - <literal>INTERFACE</literal>. May contain shell style - globs.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Host=</varname></term> - <listitem> - <para>Matches against the hostname or machine ID of the - host. See <literal>ConditionHost=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Virtualization=</varname></term> - <listitem> - <para>Checks whether the system is executed in a virtualized - environment and optionally test whether it is a specific - implementation. See <literal>ConditionVirtualization=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>KernelCommandLine=</varname></term> - <listitem> - <para>Checks whether a specific kernel command line option is - set (or if prefixed with the exclamation mark unset). See - <literal>ConditionKernelCommandLine=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Architecture=</varname></term> - <listitem> - <para>Checks whether the system is running on a specific - architecture. See <literal>ConditionArchitecture=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. - </para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[Link] Section Options</title> - - <para> The <literal>[Link]</literal> section accepts the following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The hardware address.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MTUBytes=</varname></term> - <listitem> - <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> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>[Network] Section Options</title> - - <para>The <literal>[Network]</literal> section accepts the following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Description=</varname></term> - <listitem> - <para>A description of the device. This is only used for - presentation purposes.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DHCP=</varname></term> - <listitem> - <para>Enables DHCPv4 and/or DHCPv6 support. Accepts - <literal>yes</literal>, <literal>no</literal>, - <literal>ipv4</literal> or <literal>ipv6</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DHCPServer=</varname></term> - <listitem> - <para>A boolean. Enables a basic DHCPv4 server on the - device. Mostly useful for handing out leases to container - instances.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>IPv4LL=</varname></term> - <listitem> - <para>A boolean. When true, enables IPv4 link-local support. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>IPv4LLRoute=</varname></term> - <listitem> - <para>A boolean. When true, sets up the route needed for - non-IPv4LL hosts to communicate with IPv4LL-only hosts. Defaults - to false. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>LLMNR=</varname></term> - <listitem> - <para>A boolean or <literal>resolve</literal>. When true, enables - Link-Local Multicast Name Resolution on the link, when set to - <literal>resolve</literal> only resolution is enabled, but not - announcement. Defaults to true.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>LLDP=</varname></term> - <listitem> - <para>A boolean. When true, enables LLDP link receive support. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Address=</varname></term> - <listitem> - <para>A static IPv4 or IPv6 address and its prefix length, - separated by a <literal>/</literal> character. Specify this - key more than once to configure several addresses. - The format of the address must be as described in - <citerefentry><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - This is a short-hand for an [Address] section only containing - an Address key (see below). This option may be specified - more than once. - </para> - - <para>If the specified - address is 0.0.0.0 - (for IPv4) or [::] - (for IPv6), a new - address range of the - requested size is - automatically - allocated from a - system-wide pool of - unused ranges. The - allocated range is - checked against all - current network - interfaces and all - known network - configuration files to - avoid address range - conflicts. The default - system-wide pool - consists of - 192.168.0.0/16, - 172.16.0.0/12 and - 10.0.0.0/8 for IPv4, - and fc00::/7 for - IPv6. This - functionality is - useful to manage a - large number of - dynamically created - network interfaces - with the same network - configuration and - automatic address - range - assignment.</para> - - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Gateway=</varname></term> - <listitem> - <para>The gateway address, which must be in the format described in - <citerefentry><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - This is a short-hand for a [Route] section only containing a Gateway - key. This option may be specified more than once.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DNS=</varname></term> - <listitem> - <para>A DNS server address, which must be in the format described in - <citerefentry><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - This option may be specified more than once.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Domains=</varname></term> - <listitem> - <para>The domains used for DNS resolution over this link.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>NTP=</varname></term> - <listitem> - <para>An NTP server address. This option may be specified more than once.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>IPForward=</varname></term> - <listitem><para>Configures IP - forwarding for the network - interface. If enabled incoming - packets on the network - interface will be forwarded to - other interfaces according to - the routing table. Takes - either a boolean argument, or - the values - <literal>ipv4</literal> or - <literal>ipv6</literal>, which - only enables IP forwarding for - the specified address - family.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>IPMasquerade=</varname></term> - <listitem><para>Configures IP - masquerading for the network - interface. If enabled packets - forwarded from the network - interface will be appear as - coming from the local - host. Takes a boolean - argument. Implies - <varname>IPForward=yes</varname>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>Bridge=</varname></term> - <listitem> - <para>The name of the bridge to add the link to.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Bond=</varname></term> - <listitem> - <para>The name of the bond to add the link to.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>VLAN=</varname></term> - <listitem> - <para>The name of a VLAN to create on the link. This option - may be specified more than once.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MACVLAN=</varname></term> - <listitem> - <para>The name of a MACVLAN to create on the link. This option - may be specified more than once.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>VXLAN=</varname></term> - <listitem> - <para>The name of a VXLAN to create on the link. This option - may be specified more than once.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Tunnel=</varname></term> - <listitem> - <para>The name of a Tunnel to create on the link. This option - may be specified more than once.</para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[Address] Section Options</title> - - <para>An <literal>[Address]</literal> section accepts the following keys. - Specify several <literal>[Address]</literal> sections to configure several - addresses.</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Address=</varname></term> - <listitem> - <para>As in the <literal>[Network]</literal> section. This key is mandatory.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Peer=</varname></term> - <listitem> - <para>The peer address in a point-to-point connection. Accepts the same format as - the <literal>Address</literal> key.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Broadcast=</varname></term> - <listitem> - <para>The broadcast address, which must be in the format described in - <citerefentry><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - This key only applies to IPv4 addresses. If it is not given, it is - derived from the <literal>Address</literal> key.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Label=</varname></term> - <listitem> - <para>An address label.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>[Route] Section Options</title> - <para>The <literal>[Route]</literal> section accepts the following keys. Specify - several <literal>[Route]</literal> sections to configure several routes.</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Gateway=</varname></term> - <listitem> - <para>As in the <literal>[Network]</literal> section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Destination=</varname></term> - <listitem> - <para>The destination prefix of the route. Possibly followed by a slash and the - prefixlength. If omitted, a full-length host route is assumed.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Source=</varname></term> - <listitem> - <para>The source prefix of the route. Possibly followed by a slash and the - prefixlength. If omitted, a full-length host route is assumed.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Metric=</varname></term> - <listitem> - <para>The metric of the route. An unsigned integer</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>[DHCP] Section Options</title> - <para>The <literal>[DHCP]</literal> section accepts the following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>UseDNS=</varname></term> - <listitem> - <para>When true (the default), the DNS servers received from the DHCP server will - be used and take precedence over any statically configured ones.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UseMTU=</varname></term> - <listitem> - <para>When true, the interface maximum transmission unit from the DHCP server will - be used on the current link. Defaults to false.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>SendHostname=</varname></term> - <listitem> - <para>When true (the default), the machine's hostname will be sent to the DHCP - server</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UseHostname=</varname></term> - <listitem> - <para>When true (the default), the hostname received from the DHCP server - will be used as the transient hostname.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UseDomains=</varname></term> - <listitem> - <para>When true (not the default), the domain name received from the DHCP server - will be used for DNS resolution over this link.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UseRoutes=</varname></term> - <listitem> - <para>When true (the default), the static routes will be requested from the DHCP server - and added to the routing table with metric of 1024.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>CriticalConnection=</varname></term> - <listitem> - <para>When true, the connection will never be torn down even if the DHCP lease - expires. This is contrary to the DHCP specification, but may be the best choice - if, say, the root filesystem relies on this connection. Defaults to false.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>VendorClassIdentifier=</varname></term> - <listitem> - <para>The vendor class identifier used to identify vendor type and configuration.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>RequestBroadcast=</varname></term> - <listitem> - <para>Request the server to use broadcast messages before the IP address has been - configured. This is necessary for devices that cannot receive RAW packets, or that - cannot receive packets at all before an IP address has been configured. On the other - hand, this must not be enabled on networks where broadcasts are filtered out.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>RouteMetric=</varname></term> - <listitem> - <para>Set the routing metric for routes specified by the DHCP server.</para> - </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[Bridge] Section Options</title> - <para>The <literal>[Bridge]</literal> section accepts the following keys.</para> - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Cost=</varname></term> - <listitem> - <para>Each port in a bridge may have different speed. Cost is used to decide which link to use. Faster interfaces should have lower costs</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>[BridgeFDB] Section Options</title> - <para>The <literal>[BridgeFDB]</literal> section manages the forwarding database table of a port and accepts the following keys. Specify - several <literal>[BridgeFDB]</literal> sections to configure several static MAC table entries.</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>As in the <literal>[Network]</literal> section. This key is mandatory.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>VLANId=</varname></term> - <listitem> - <para>The VLAN Id for the new static MAC table entry. - If omitted, no VLAN Id info is appended to the new static MAC table entry.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Example</title> - <example> - <title>/etc/systemd/network/50-static.network</title> - - <programlisting>[Match] + <refentryinfo> + <title>systemd.network</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + <email>teg@jklm.no</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.network</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.network</refname> + <refpurpose>Network configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>network</replaceable>.network</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Network setup is performed by + <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> + + <para>Network files must have the extension + <filename>.network</filename>; other extensions are ignored. + Networks are applied to links whenever the links appear.</para> + + <para>The <filename>.network</filename> files are read from the + files located in the system network directory + <filename>/usr/lib/systemd/network</filename>, the volatile + runtime network directory + <filename>/run/systemd/network</filename> and the local + administration network directory + <filename>/etc/systemd/network</filename>. All configuration files + are collectively sorted and processed in lexical order, regardless + of the directories in which they live. However, files with + identical filenames replace each other. Files in + <filename>/etc</filename> have the highest priority, files in + <filename>/run</filename> take precedence over files with the same + name in <filename>/usr/lib</filename>. This can be used to + override a system-supplied configuration file with a local file if + needed; a symlink in <filename>/etc</filename> with the same name + as a configuration file in <filename>/usr/lib</filename>, pointing + to <filename>/dev/null</filename>, disables the configuration file + entirely.</para> + + </refsect1> + + <refsect1> + <title>[Match] Section Options</title> + + <para>The network file contains a <literal>[Match]</literal> + section, which determines if a given network file may be applied + to a given device; and a <literal>[Network]</literal> section + specifying how the device should be configured. The first (in + lexical order) of the network files that matches a given device + is applied.</para> + + <para>A network file is said to match a device if each of the + entries in the <literal>[Match]</literal> section matches, or if + the section is empty. The following keys are accepted:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The hardware address.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Path=</varname></term> + <listitem> + <para>The persistent path, as exposed by the udev + property <literal>ID_PATH</literal>. May contain shell + style globs.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Driver=</varname></term> + <listitem> + <para>The driver currently bound to the device, as + exposed by the udev property <literal>DRIVER</literal> + of its parent device, or if that is not set the driver + as exposed by <literal>ethtool -i</literal> of the + device itself.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Type=</varname></term> + <listitem> + <para>The device type, as exposed by the udev property + <literal>DEVTYPE</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Name=</varname></term> + <listitem> + <para>The device name, as exposed by the udev property + <literal>INTERFACE</literal>. May contain shell style + globs.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Host=</varname></term> + <listitem> + <para>Matches against the hostname or machine ID of the + host. See <literal>ConditionHost=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Virtualization=</varname></term> + <listitem> + <para>Checks whether the system is executed in a virtualized + environment and optionally test whether it is a specific + implementation. See <literal>ConditionVirtualization=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>KernelCommandLine=</varname></term> + <listitem> + <para>Checks whether a specific kernel command line option is + set (or if prefixed with the exclamation mark unset). See + <literal>ConditionKernelCommandLine=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Architecture=</varname></term> + <listitem> + <para>Checks whether the system is running on a specific + architecture. See <literal>ConditionArchitecture=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[Link] Section Options</title> + + <para> The <literal>[Link]</literal> section accepts the following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The hardware address.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MTUBytes=</varname></term> + <listitem> + <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> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[Network] Section Options</title> + + <para>The <literal>[Network]</literal> section accepts the following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Description=</varname></term> + <listitem> + <para>A description of the device. This is only used for + presentation purposes.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DHCP=</varname></term> + <listitem> + <para>Enables DHCPv4 and/or DHCPv6 support. Accepts + <literal>yes</literal>, <literal>no</literal>, + <literal>ipv4</literal>, or <literal>ipv6</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DHCPServer=</varname></term> + <listitem> + <para>A boolean. Enables a basic DHCPv4 server on the + device. Mostly useful for handing out leases to container + instances.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>IPv4LL=</varname></term> + <listitem> + <para>A boolean. When true, enables IPv4 link-local support. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>IPv4LLRoute=</varname></term> + <listitem> + <para>A boolean. When true, sets up the route needed for + non-IPv4LL hosts to communicate with IPv4LL-only hosts. Defaults + to false. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>LLMNR=</varname></term> + <listitem> + <para>A boolean or <literal>resolve</literal>. When true, enables + Link-Local Multicast Name Resolution on the link, when set to + <literal>resolve</literal> only resolution is enabled, but not + announcement. Defaults to true.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>LLDP=</varname></term> + <listitem> + <para>A boolean. When true, enables LLDP link receive support. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Address=</varname></term> + <listitem> + <para>A static IPv4 or IPv6 address and its prefix length, + separated by a <literal>/</literal> character. Specify + this key more than once to configure several addresses. + The format of the address must be as described in + <citerefentry><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This is a short-hand for an [Address] section only + containing an Address key (see below). This option may be + specified more than once. + </para> + + <para>If the specified address is 0.0.0.0 (for IPv4) or + [::] (for IPv6), a new address range of the requested size + is automatically allocated from a system-wide pool of + unused ranges. The allocated range is checked against all + current network interfaces and all known network + configuration files to avoid address range conflicts. The + default system-wide pool consists of 192.168.0.0/16, + 172.16.0.0/12 and 10.0.0.0/8 for IPv4, and fc00::/7 for + IPv6. This functionality is useful to manage a large + number of dynamically created network interfaces with the + same network configuration and automatic address range + assignment.</para> + + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Gateway=</varname></term> + <listitem> + <para>The gateway address, which must be in the format + described in + <citerefentry><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This is a short-hand for a [Route] section only containing + a Gateway key. This option may be specified more than + once.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DNS=</varname></term> + <listitem> + <para>A DNS server address, which must be in the format + described in + <citerefentry><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This option may be specified more than once.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Domains=</varname></term> + <listitem> + <para>The domains used for DNS resolution over this link.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>NTP=</varname></term> + <listitem> + <para>An NTP server address. This option may be specified more than once.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>IPForward=</varname></term> + <listitem><para>Configures IP forwarding for the network + interface. If enabled incoming packets on the network + interface will be forwarded to other interfaces according to + the routing table. Takes either a boolean argument, or the + values <literal>ipv4</literal> or <literal>ipv6</literal>, + which only enables IP forwarding for the specified address + family.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>IPMasquerade=</varname></term> + <listitem><para>Configures IP masquerading for the network + interface. If enabled packets forwarded from the network + interface will be appear as coming from the local host. + Takes a boolean argument. Implies + <varname>IPForward=yes</varname>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>Bridge=</varname></term> + <listitem> + <para>The name of the bridge to add the link to.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Bond=</varname></term> + <listitem> + <para>The name of the bond to add the link to.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VLAN=</varname></term> + <listitem> + <para>The name of a VLAN to create on the link. This + option may be specified more than once.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACVLAN=</varname></term> + <listitem> + <para>The name of a MACVLAN to create on the link. This + option may be specified more than once.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VXLAN=</varname></term> + <listitem> + <para>The name of a VXLAN to create on the link. This + option may be specified more than once.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Tunnel=</varname></term> + <listitem> + <para>The name of a Tunnel to create on the link. This + option may be specified more than once.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[Address] Section Options</title> + + <para>An <literal>[Address]</literal> section accepts the + following keys. Specify several <literal>[Address]</literal> + sections to configure several addresses.</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Address=</varname></term> + <listitem> + <para>As in the <literal>[Network]</literal> section. This + key is mandatory.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Peer=</varname></term> + <listitem> + <para>The peer address in a point-to-point connection. + Accepts the same format as the <literal>Address</literal> + key.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Broadcast=</varname></term> + <listitem> + <para>The broadcast address, which must be in the format + described in + <citerefentry><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This key only applies to IPv4 addresses. If it is not + given, it is derived from the <literal>Address</literal> + key.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Label=</varname></term> + <listitem> + <para>An address label.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[Route] Section Options</title> + <para>The <literal>[Route]</literal> section accepts the + following keys. Specify several <literal>[Route]</literal> + sections to configure several routes.</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Gateway=</varname></term> + <listitem> + <para>As in the <literal>[Network]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Destination=</varname></term> + <listitem> + <para>The destination prefix of the route. Possibly + followed by a slash and the prefixlength. If omitted, a + full-length host route is assumed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Source=</varname></term> + <listitem> + <para>The source prefix of the route. Possibly followed by + a slash and the prefixlength. If omitted, a full-length + host route is assumed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Metric=</varname></term> + <listitem> + <para>The metric of the route. An unsigned integer</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[DHCP] Section Options</title> + <para>The <literal>[DHCP]</literal> section accepts the following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>UseDNS=</varname></term> + <listitem> + <para>When true (the default), the DNS servers received + from the DHCP server will be used and take precedence over + any statically configured ones.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UseMTU=</varname></term> + <listitem> + <para>When true, the interface maximum transmission unit + from the DHCP server will be used on the current link. + Defaults to false.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>SendHostname=</varname></term> + <listitem> + <para>When true (the default), the machine's hostname will be sent to the DHCP + server</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UseHostname=</varname></term> + <listitem> + <para>When true (the default), the hostname received from + the DHCP server will be used as the transient + hostname.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UseDomains=</varname></term> + <listitem> + <para>When true (not the default), the domain name + received from the DHCP server will be used for DNS + resolution over this link.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UseRoutes=</varname></term> + <listitem> + <para>When true (the default), the static routes will be + requested from the DHCP server and added to the routing + table with metric of 1024.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>CriticalConnection=</varname></term> + <listitem> + <para>When true, the connection will never be torn down + even if the DHCP lease expires. This is contrary to the + DHCP specification, but may be the best choice if, say, + the root filesystem relies on this connection. Defaults to + false.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VendorClassIdentifier=</varname></term> + <listitem> + <para>The vendor class identifier used to identify vendor + type and configuration.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>RequestBroadcast=</varname></term> + <listitem> + <para>Request the server to use broadcast messages before + the IP address has been configured. This is necessary for + devices that cannot receive RAW packets, or that cannot + receive packets at all before an IP address has been + configured. On the other hand, this must not be enabled on + networks where broadcasts are filtered out.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>RouteMetric=</varname></term> + <listitem> + <para>Set the routing metric for routes specified by the + DHCP server.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[Bridge] Section Options</title> + <para>The <literal>[Bridge]</literal> section accepts the + following keys.</para> + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Cost=</varname></term> + <listitem> + <para>Each port in a bridge may have different speed. Cost + is used to decide which link to use. Faster interfaces + should have lower costs</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>[BridgeFDB] Section Options</title> + <para>The <literal>[BridgeFDB]</literal> section manages the + forwarding database table of a port and accepts the following + keys. Specify several <literal>[BridgeFDB]</literal> sections to + configure several static MAC table entries.</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>As in the <literal>[Network]</literal> section. This + key is mandatory.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VLANId=</varname></term> + <listitem> + <para>The VLAN Id for the new static MAC table entry. If + omitted, no VLAN Id info is appended to the new static MAC + table entry.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/systemd/network/50-static.network</title> + + <programlisting>[Match] Name=enp2s0 [Network] Address=192.168.0.15/24 Gateway=192.168.0.1</programlisting> - </example> + </example> - <example> - <title>/etc/systemd/network/80-dhcp.network</title> + <example> + <title>/etc/systemd/network/80-dhcp.network</title> - <programlisting>[Match] + <programlisting>[Match] Name=en* [Network] DHCP=both</programlisting> - </example> + </example> - <example> - <title>/etc/systemd/network/bridge-static.network</title> + <example> + <title>/etc/systemd/network/bridge-static.network</title> - <programlisting>[Match] + <programlisting>[Match] Name=bridge0 [Network] Address=192.168.0.15/24 Gateway=192.168.0.1 DNS=192.168.0.1</programlisting> - </example> + </example> - <example> - <title>/etc/systemd/network/bridge-slave-interface.network</title> + <example> + <title>/etc/systemd/network/bridge-slave-interface.network</title> - <programlisting>[Match] + <programlisting>[Match] Name=enp2s0 [Network] Bridge=bridge0</programlisting> - </example> - <example> - <title>/etc/systemd/network/ipip.network</title> + </example> + <example> + <title>/etc/systemd/network/ipip.network</title> - <programlisting>[Match] + <programlisting>[Match] Name=em1 [Network] Tunnel=ipip-tun</programlisting> - </example> + </example> - <example> - <title>/etc/systemd/network/sit.network</title> + <example> + <title>/etc/systemd/network/sit.network</title> - <programlisting>[Match] + <programlisting>[Match] Name=em1 [Network] Tunnel=sit-tun</programlisting> - </example> + </example> - <example> - <title>/etc/systemd/network/gre.network</title> + <example> + <title>/etc/systemd/network/gre.network</title> - <programlisting>[Match] + <programlisting>[Match] Name=em1 [Network] Tunnel=gre-tun</programlisting> - </example> + </example> - <example> - <title>/etc/systemd/network/vti.network</title> + <example> + <title>/etc/systemd/network/vti.network</title> - <programlisting>[Match] + <programlisting>[Match] Name=em1 [Network] Tunnel=vti-tun</programlisting> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.path.xml b/man/systemd.path.xml index c6d61cf2b1..71f74d94d6 100644 --- a/man/systemd.path.xml +++ b/man/systemd.path.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,213 +23,174 @@ --> <refentry id="systemd.path"> - <refentryinfo> - <title>systemd.path</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.path</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.path</refname> - <refpurpose>Path unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>path</replaceable>.path</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.path</literal> encodes information about - a path monitored by systemd, for - path-based activation.</para> - - <para>This man page lists the configuration options - specific to this unit type. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the common options of all unit configuration - files. The common configuration items are configured - in the generic [Unit] and [Install] sections. The - path specific configuration options are configured in - the [Path] section.</para> - - <para>For each path file, a matching unit file must - exist, describing the unit to activate when the path - changes. By default, a service by the same name as the - path (except for the suffix) is activated. Example: a - path file <filename>foo.path</filename> activates a - matching service <filename>foo.service</filename>. The - unit to activate may be controlled by - <varname>Unit=</varname> (see below).</para> - - <para>Internally, path units use the - <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> - API to monitor file systems. Due to that, it suffers by the - same limitations as inotify, and for example cannot be - used to monitor files or directories changed by other - machines on remote NFS file systems.</para> - - <para>If a path unit is beneath another mount - point in the file system hierarchy, a dependency - between both units is created automatically.</para> - - <para>Unless <varname>DefaultDependencies=false</varname> - is used, path units will implicitly 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> - - <refsect1> - <title>Options</title> - - <para>Path files must include a [Path] section, - which carries information about the path(s) it - monitors. The options specific to the [Path] section - of path units are the following:</para> - - <variablelist class='unit-directives'> - <varlistentry> - <term><varname>PathExists=</varname></term> - <term><varname>PathExistsGlob=</varname></term> - <term><varname>PathChanged=</varname></term> - <term><varname>PathModified=</varname></term> - <term><varname>DirectoryNotEmpty=</varname></term> - - <listitem><para>Defines paths to - monitor for certain changes: - <varname>PathExists=</varname> may be - used to watch the mere existence of a - file or directory. If the file - specified exists, the configured unit - is - activated. <varname>PathExistsGlob=</varname> - works similar, but checks for the - existence of at least one file - matching the globbing pattern - specified. <varname>PathChanged=</varname> - may be used to watch a file or - directory and activate the configured - unit whenever it changes. It is not - activated on every write to the - watched file but it is activated if - the file which was open for writing - gets - closed. <varname>PathModified=</varname> - is similar, but additionally it is - activated also on simple writes to the - watched file. - <varname>DirectoryNotEmpty=</varname> - may be used to watch a directory and - activate the configured unit whenever - it contains at least one file.</para> - - <para>The arguments of these - directives must be absolute file - system paths.</para> - - <para>Multiple directives may be - combined, of the same and of different - types, to watch multiple paths. If the - empty string is assigned to any of - these options, the list of paths to - watch is reset, and any prior - assignments of these options will not - have any effect.</para> - - <para>If a path already exists - (in case of - <varname>PathExists=</varname> and - <varname>PathExistsGlob=</varname>) or - a directory already is not empty (in - case of - <varname>DirectoryNotEmpty=</varname>) - at the time the path unit is - activated, then the configured unit is - immediately activated as - well. Something similar does not apply - to <varname>PathChanged=</varname> and - <varname>PathModified=</varname>.</para> - - <para>If the path itself or any of the - containing directories are not - accessible, <command>systemd</command> - will watch for permission changes and - notice that conditions are satisfied - when permissions allow that. - </para></listitem> - </varlistentry> - <varlistentry> - <term><varname>Unit=</varname></term> - - <listitem><para>The unit to activate - when any of the configured paths - changes. The argument is a unit name, - whose suffix is not - <literal>.path</literal>. If not - specified, this value defaults to a - service that has the same name as the - path unit, except for the suffix. (See - above.) It is recommended that the - unit name that is activated and the - unit name of the path unit are named - identical, except for the - suffix.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>MakeDirectory=</varname></term> - - <listitem><para>Takes a boolean - argument. If true, the directories to - watch are created before - watching. This option is ignored for - <varname>PathExists=</varname> - settings. Defaults to - <option>false</option>.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>DirectoryMode=</varname></term> - - <listitem><para>If - <varname>MakeDirectory=</varname> is - enabled, use the mode specified here to - create the directories in - question. Takes an access mode in - octal notation. Defaults to - <option>0755</option>.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd.path</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.path</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.path</refname> + <refpurpose>Path unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>path</replaceable>.path</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.path</literal> encodes information about a path + monitored by systemd, for path-based activation.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. The path specific configuration options are + configured in the [Path] section.</para> + + <para>For each path file, a matching unit file must exist, + describing the unit to activate when the path changes. By default, + a service by the same name as the path (except for the suffix) is + activated. Example: a path file <filename>foo.path</filename> + activates a matching service <filename>foo.service</filename>. The + unit to activate may be controlled by <varname>Unit=</varname> + (see below).</para> + + <para>Internally, path units use the + <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> + API to monitor file systems. Due to that, it suffers by the same + limitations as inotify, and for example cannot be used to monitor + files or directories changed by other machines on remote NFS file + systems.</para> + + <para>If a path unit is beneath another mount point in the file + system hierarchy, a dependency between both units is created + automatically.</para> + + <para>Unless <varname>DefaultDependencies=false</varname> is used, + path units will implicitly 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> + + <refsect1> + <title>Options</title> + + <para>Path files must include a [Path] section, which carries + information about the path(s) it monitors. The options specific to + the [Path] section of path units are the following:</para> + + <variablelist class='unit-directives'> + <varlistentry> + <term><varname>PathExists=</varname></term> + <term><varname>PathExistsGlob=</varname></term> + <term><varname>PathChanged=</varname></term> + <term><varname>PathModified=</varname></term> + <term><varname>DirectoryNotEmpty=</varname></term> + + <listitem><para>Defines paths to monitor for certain changes: + <varname>PathExists=</varname> may be used to watch the mere + existence of a file or directory. If the file specified + exists, the configured unit is activated. + <varname>PathExistsGlob=</varname> works similar, but checks + for the existence of at least one file matching the globbing + pattern specified. <varname>PathChanged=</varname> may be used + to watch a file or directory and activate the configured unit + whenever it changes. It is not activated on every write to the + watched file but it is activated if the file which was open + for writing gets closed. <varname>PathModified=</varname> is + similar, but additionally it is activated also on simple + writes to the watched file. + <varname>DirectoryNotEmpty=</varname> may be used to watch a + directory and activate the configured unit whenever it + contains at least one file.</para> + + <para>The arguments of these directives must be absolute file + system paths.</para> + + <para>Multiple directives may be combined, of the same and of + different types, to watch multiple paths. If the empty string + is assigned to any of these options, the list of paths to + watch is reset, and any prior assignments of these options + will not have any effect.</para> + + <para>If a path already exists (in case of + <varname>PathExists=</varname> and + <varname>PathExistsGlob=</varname>) or a directory already is + not empty (in case of <varname>DirectoryNotEmpty=</varname>) + at the time the path unit is activated, then the configured + unit is immediately activated as well. Something similar does + not apply to <varname>PathChanged=</varname> and + <varname>PathModified=</varname>.</para> + + <para>If the path itself or any of the containing directories + are not accessible, <command>systemd</command> will watch for + permission changes and notice that conditions are satisfied + when permissions allow that. </para></listitem> + </varlistentry> + <varlistentry> + <term><varname>Unit=</varname></term> + + <listitem><para>The unit to activate when any of the + configured paths changes. The argument is a unit name, whose + suffix is not <literal>.path</literal>. If not specified, this + value defaults to a service that has the same name as the path + unit, except for the suffix. (See above.) It is recommended + that the unit name that is activated and the unit name of the + path unit are named identical, except for the + suffix.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>MakeDirectory=</varname></term> + + <listitem><para>Takes a boolean argument. If true, the + directories to watch are created before watching. This option + is ignored for <varname>PathExists=</varname> settings. + Defaults to <option>false</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + + <listitem><para>If <varname>MakeDirectory=</varname> is + enabled, use the mode specified here to create the directories + in question. Takes an access mode in octal notation. Defaults + to <option>0755</option>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.preset.xml b/man/systemd.preset.xml index 55cb4de174..2f9add8d6c 100644 --- a/man/systemd.preset.xml +++ b/man/systemd.preset.xml @@ -21,183 +21,169 @@ --> <refentry id="systemd.preset"> - <refentryinfo> - <title>systemd.preset</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.preset</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.preset</refname> - <refpurpose>Service enablement presets</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/system-preset/*.preset</filename></para> - <para><filename>/run/systemd/system-preset/*.preset</filename></para> - <para><filename>/usr/lib/systemd/system-preset/*.preset</filename></para> - <para><filename>/etc/systemd/user-preset/*.preset</filename></para> - <para><filename>/run/systemd/user-preset/*.preset</filename></para> - <para><filename>/usr/lib/systemd/user-preset/*.preset</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>Preset files may be used to encode policy which - units shall be enabled by default and which ones - shall be disabled. They are read by <command>systemctl - preset</command> (for more information see - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>) - which uses this information to enable or disable a - unit according to preset policy. <command>systemctl - preset</command> is used by the post install - scriptlets of RPM packages (or other OS package formats), - to enable/disable specific units by default on package - installation, enforcing distribution, spin or - administrator preset policy. This allows choosing a certain - set of units to be enabled/disabled even before - installing the actual package.</para> - - <para>For more information on the preset logic please - have a look at the <ulink - url="http://freedesktop.org/wiki/Software/systemd/Preset">Presets</ulink> - document.</para> - - <para>It is not recommended to ship preset files - within the respective software packages implementing - the units, but rather centralize them in a - distribution or spin default policy, which can be - amended by administrator policy.</para> - - <para>If no preset files exist, <command>systemctl - preset</command> will enable all units that are - installed by default. If this is not desired and all - units shall rather be disabled, it is necessary to ship - a preset file with a single, catchall - "<filename>disable *</filename>" line. (See example 1, - below.)</para> - </refsect1> - - <refsect1> - <title>Preset File Format</title> - - <para>The preset files contain a list of - directives consisting of either the word - <literal>enable</literal> or - <literal>disable</literal> followed by a space and a - unit name (possibly with shell style wildcards), - separated by newlines. Empty lines and lines whose - first non-whitespace character is # or ; are - ignored.</para> - - <para>Two different directives are understood: - <literal>enable</literal> may be used to enable units - by default, <literal>disable</literal> to disable - units by default.</para> - - <para>If multiple lines apply to a unit name, the - first matching one takes precedence over all - others.</para> - - <para>Each preset file shall be named in the style of - <filename><priority>-<program>.conf</filename>. - Files in <filename>/etc/</filename> override files - with the same name in <filename>/usr/lib/</filename> - and <filename>/run/</filename>. Files in - <filename>/run/</filename> override files with the - same name in <filename>/usr/lib/</filename>. Packages - should install their preset files in - <filename>/usr/lib/</filename>. Files in - <filename>/etc/</filename> are reserved for the local - administrator, who may use this logic to override the - preset files installed by vendor packages. All preset - files are sorted by their filename in lexicographic - order, regardless of which of the directories they - reside in. If multiple files specify the same unit name, - the entry in the file with the lexicographically earliest - name will be applied. It is recommended to prefix all - filenames with a two-digit number and a dash, to simplify - the ordering of the files.</para> - - <para>If the administrator wants to disable a preset - file supplied by the vendor, the recommended way is to - place a symlink to <filename>/dev/null</filename> in - <filename>/etc/systemd/system-preset/</filename> - bearing the same filename.</para> - </refsect1> - - <refsect1> - <title>Example</title> - - <example> - <title>Default off example <filename>/usr/lib/systemd/system-preset/99-default.preset</filename>:</title> - - <programlisting>disable *</programlisting> - </example> - - <para>This disables all units. Due to the filename - prefix <literal>99-</literal>, it will be read last and - hence can easily be overridden by spin or - administrator preset policy or suchlike.</para> - - <example> - <title>A GNOME spin example <filename>/usr/lib/systemd/system-preset/50-gnome.preset</filename>:</title> - - <programlisting>enable gdm.service + <refentryinfo> + <title>systemd.preset</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.preset</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.preset</refname> + <refpurpose>Service enablement presets</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/system-preset/*.preset</filename></para> + <para><filename>/run/systemd/system-preset/*.preset</filename></para> + <para><filename>/usr/lib/systemd/system-preset/*.preset</filename></para> + <para><filename>/etc/systemd/user-preset/*.preset</filename></para> + <para><filename>/run/systemd/user-preset/*.preset</filename></para> + <para><filename>/usr/lib/systemd/user-preset/*.preset</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Preset files may be used to encode policy which units shall + be enabled by default and which ones shall be disabled. They are + read by <command>systemctl preset</command> (for more information + see + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>) + which uses this information to enable or disable a unit according + to preset policy. <command>systemctl preset</command> is used by + the post install scriptlets of RPM packages (or other OS package + formats), to enable/disable specific units by default on package + installation, enforcing distribution, spin or administrator preset + policy. This allows choosing a certain set of units to be + enabled/disabled even before installing the actual package.</para> + + <para>For more information on the preset logic please have a look + at the <ulink + url="http://freedesktop.org/wiki/Software/systemd/Preset">Presets</ulink> + document.</para> + + <para>It is not recommended to ship preset files within the + respective software packages implementing the units, but rather + centralize them in a distribution or spin default policy, which + can be amended by administrator policy.</para> + + <para>If no preset files exist, <command>systemctl + preset</command> will enable all units that are installed by + default. If this is not desired and all units shall rather be + disabled, it is necessary to ship a preset file with a single, + catchall "<filename>disable *</filename>" line. (See example 1, + below.)</para> + </refsect1> + + <refsect1> + <title>Preset File Format</title> + + <para>The preset files contain a list of directives consisting of + either the word <literal>enable</literal> or + <literal>disable</literal> followed by a space and a unit name + (possibly with shell style wildcards), separated by newlines. + Empty lines and lines whose first non-whitespace character is # or + ; are ignored.</para> + + <para>Two different directives are understood: + <literal>enable</literal> may be used to enable units by default, + <literal>disable</literal> to disable units by default.</para> + + <para>If multiple lines apply to a unit name, the first matching + one takes precedence over all others.</para> + + <para>Each preset file shall be named in the style of + <filename><priority>-<program>.conf</filename>. Files + in <filename>/etc/</filename> override files with the same name in + <filename>/usr/lib/</filename> and <filename>/run/</filename>. + Files in <filename>/run/</filename> override files with the same + name in <filename>/usr/lib/</filename>. Packages should install + their preset files in <filename>/usr/lib/</filename>. Files in + <filename>/etc/</filename> are reserved for the local + administrator, who may use this logic to override the preset files + installed by vendor packages. All preset files are sorted by their + filename in lexicographic order, regardless of which of the + directories they reside in. If multiple files specify the same + unit name, the entry in the file with the lexicographically + earliest name will be applied. It is recommended to prefix all + filenames with a two-digit number and a dash, to simplify the + ordering of the files.</para> + + <para>If the administrator wants to disable a preset file supplied + by the vendor, the recommended way is to place a symlink to + <filename>/dev/null</filename> in + <filename>/etc/systemd/system-preset/</filename> bearing the same + filename.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <example> + <title>Default off example <filename>/usr/lib/systemd/system-preset/99-default.preset</filename>:</title> + + <programlisting>disable *</programlisting> + </example> + + <para>This disables all units. Due to the filename prefix + <literal>99-</literal>, it will be read last and hence can easily + be overridden by spin or administrator preset policy or + suchlike.</para> + + <example> + <title>A GNOME spin example <filename>/usr/lib/systemd/system-preset/50-gnome.preset</filename>:</title> + + <programlisting>enable gdm.service enable colord.service enable accounts-daemon.service enable avahi-daemon.*</programlisting> - </example> + </example> - <para>This enables the three mentioned units, plus all - <filename>avahi-daemon</filename> regardless of which - unit type. A file like this could be useful for - inclusion in a GNOME spin of a distribution. It will - ensure that the units necessary for GNOME are properly - enabled as they are installed. It leaves all other - units untouched, and subject to other (later) preset - files, for example like the one from the first example - above.</para> + <para>This enables the three mentioned units, plus all + <filename>avahi-daemon</filename> regardless of which unit type. A + file like this could be useful for inclusion in a GNOME spin of a + distribution. It will ensure that the units necessary for GNOME + are properly enabled as they are installed. It leaves all other + units untouched, and subject to other (later) preset files, for + example like the one from the first example above.</para> - <example> - <title>Administrator policy <filename>/etc/systemd/system-preset/00-lennart.preset</filename>:</title> + <example> + <title>Administrator policy <filename>/etc/systemd/system-preset/00-lennart.preset</filename>:</title> - <programlisting>enable httpd.service + <programlisting>enable httpd.service enable sshd.service enable postfix.service disable *</programlisting> - </example> - - <para>This enables three specific services and - disables all others. This is useful for administrators - to specifically select the units to enable, and - disable all others. Due to the filename prefix - <literal>00-</literal> it will be read early and hence - overrides all other preset policy files.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + </example> + + <para>This enables three specific services and disables all + others. This is useful for administrators to specifically select + the units to enable, and disable all others. Due to the filename + prefix <literal>00-</literal> it will be read early and hence + overrides all other preset policy files.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.service.xml b/man/systemd.service.xml index f33e8df056..37d9e98219 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,1357 +23,1069 @@ --> <refentry id="systemd.service"> - <refentryinfo> - <title>systemd.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.service</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.service</refname> - <refpurpose>Service unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>service</replaceable>.service</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <filename>.service</filename> encodes information - about a process controlled and supervised by - systemd.</para> - - <para>This man page lists the configuration options - specific to this unit type. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the common options of all unit configuration - files. The common configuration items are configured - in the generic <literal>[Unit]</literal> and - <literal>[Install]</literal> sections. The service - specific configuration options are configured in the - <literal>[Service]</literal> section.</para> - - <para>Additional options are listed in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the execution environment the commands - are executed in, and in - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the way the processes of the service are - terminated, and in - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which configure resource control settings for the - processes of the service.</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>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>If a service is requested under a certain name - but no unit configuration file is found, systemd looks - for a SysV init script by the same name (with the - <filename>.service</filename> suffix removed) and - dynamically creates a service unit from that - script. This is useful for compatibility with - SysV. Note that this compatibility is quite - comprehensive but not 100%. For details about the - incompatibilities, see the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities - with SysV</ulink> document. - </para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>Service files must include a - <literal>[Service]</literal> section, which carries - information about the service and the process it - supervises. A number of options that may be used in - this section are shared with other unit types. These - options are documented in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The - options specific to the <literal>[Service]</literal> - section of service units are the following:</para> - - <variablelist class='unit-directives'> - <varlistentry> - <term><varname>Type=</varname></term> - - <listitem><para>Configures the process - start-up type for this service - unit. One of <option>simple</option>, - <option>forking</option>, - <option>oneshot</option>, - <option>dbus</option>, - <option>notify</option> or - <option>idle</option>.</para> - - <para>If set to - <option>simple</option> (the default - if neither - <varname>Type=</varname> nor - <varname>BusName=</varname>, but - <varname>ExecStart=</varname> are - specified), it is expected that the - process configured with - <varname>ExecStart=</varname> is the - main process of the service. In this - mode, if the process offers - functionality to other processes on - the system, its communication channels - should be installed before the daemon - is started up (e.g. sockets set up by - systemd, via socket activation), as - systemd will immediately proceed - starting follow-up units.</para> - - <para>If set to - <option>forking</option>, it is - expected that the process configured - with <varname>ExecStart=</varname> - will call <function>fork()</function> - as part of its start-up. The parent process is - expected to exit when start-up is - complete and all communication - channels are set up. The child continues - to run as the main daemon - process. This is the behavior of - traditional UNIX daemons. If this - setting is used, it is recommended to - also use the - <varname>PIDFile=</varname> option, so - that systemd can identify the main - process of the daemon. systemd will - proceed with starting follow-up units - as soon as the parent process - exits.</para> - - <para>Behavior of - <option>oneshot</option> is similar to - <option>simple</option>; however, it - is expected that the process has to - exit before systemd starts follow-up - units. <varname>RemainAfterExit=</varname> - is particularly useful for this type - of service. This is the implied - default if neither - <varname>Type=</varname> or - <varname>ExecStart=</varname> are - specified.</para> - - <para>Behavior of - <option>dbus</option> is similar to - <option>simple</option>; however, it is - expected that the daemon acquires a - name on the D-Bus bus, as configured - by - <varname>BusName=</varname>. systemd - will proceed with starting follow-up - units after the D-Bus bus name has been - acquired. Service units with this - option configured implicitly gain - dependencies on the - <filename>dbus.socket</filename> - unit. This type is the default if - <varname>BusName=</varname> is - specified.</para> - - <para>Behavior of - <option>notify</option> is similar to - <option>simple</option>; however, it is - expected that the daemon sends a - notification message via - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or an equivalent call when it has finished - starting up. systemd will proceed with - starting follow-up units after this - notification message has been sent. If - this option is used, - <varname>NotifyAccess=</varname> (see - below) should be set to open access to - the notification socket provided by - systemd. If - <varname>NotifyAccess=</varname> is - not set, it will be implicitly set to - <option>main</option>. Note that - currently - <varname>Type=</varname><option>notify</option> - will not work if used in combination with - <varname>PrivateNetwork=</varname><option>yes</option>.</para> - - <para>Behavior of - <option>idle</option> is very similar - to <option>simple</option>; however, - actual execution of the service - binary is delayed until all jobs are - dispatched. This may be used to avoid - interleaving of output of shell - services with the status output on the - console.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>RemainAfterExit=</varname></term> - - <listitem><para>Takes a boolean value - that specifies whether the service - shall be considered active even when - all its processes exited. Defaults to - <option>no</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>GuessMainPID=</varname></term> - - <listitem><para>Takes a boolean value - that specifies whether systemd should - try to guess the main PID of a service - if it cannot be determined - reliably. This option is ignored - unless <option>Type=forking</option> - is set and <option>PIDFile=</option> - is unset because for the other types - or with an explicitly configured PID - file, the main PID is always known. The - guessing algorithm might come to - incorrect conclusions if a daemon - consists of more than one process. If - the main PID cannot be determined, - failure detection and automatic - restarting of a service will not work - reliably. Defaults to - <option>yes</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>PIDFile=</varname></term> - - <listitem><para>Takes an absolute file - name pointing to the PID file of this - daemon. Use of this option is - recommended for services where - <varname>Type=</varname> is set to - <option>forking</option>. systemd will - read the PID of the main process of - the daemon after start-up of the - service. systemd will not write to the - file configured here.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>BusName=</varname></term> - - <listitem><para>Takes a D-Bus bus - name that this service is reachable - as. This option is mandatory for - services where - <varname>Type=</varname> is set to - <option>dbus</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>BusPolicy=</varname></term> - - <listitem><para>If specified, a custom - <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink> - 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 zero or more command lines is - according to the rules described below - (see section "Command Lines" below). - </para> - - <para>When <varname>Type</varname> is - not <option>oneshot</option>, only one - command may and must be given. When - <varname>Type=oneshot</varname> is - used, zero or more commands may be - specified. This can be specified by - providing multiple command lines in - the same directive, or alternatively, - this directive may be specified more - than once with the same effect. If the - empty string is assigned to this - option, the list of commands to start - is reset, prior assignments of this - option will have no effect. If no - <varname>ExecStart=</varname> is - specified, then the service must have - <varname>RemainAfterExit=yes</varname> - set.</para> - - <para>For each of the specified - commands, the first argument must be - an absolute path to an executable. - Optionally, if this file name is - prefixed with <literal>@</literal>, - the second token will be passed as - <literal>argv[0]</literal> to the - executed process, followed by the - further arguments specified. If the - absolute filename is prefixed with - <literal>-</literal>, an exit code of - the command normally considered a - failure (i.e. non-zero exit status or - abnormal exit due to signal) is - ignored and considered success. If - both <literal>-</literal> and - <literal>@</literal> are used, they - can appear in either order.</para> - - <para>If more than one command is - specified, the commands are invoked - sequentially in the order they appear - in the unit file. If one of the - commands fails (and is not prefixed - with <literal>-</literal>), other - lines are not executed, and the unit - is considered failed.</para> - - <para>Unless - <varname>Type=forking</varname> is - set, the process started via this - command line will be considered the - main process of the daemon.</para> - - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ExecStartPre=</varname></term> - <term><varname>ExecStartPost=</varname></term> - <listitem><para>Additional commands - that are executed before or after - the command in - <varname>ExecStart=</varname>, respectively. - Syntax is the same as for - <varname>ExecStart=</varname>, except - that multiple command lines are allowed - and the commands are executed one - after the other, serially.</para> - - <para>If any of those commands (not - prefixed with <literal>-</literal>) - fail, the rest are not executed and - the unit is considered failed.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ExecReload=</varname></term> - <listitem><para>Commands to execute to - trigger a configuration reload in the - service. This argument takes multiple - command lines, following the same - scheme as described for - <varname>ExecStart=</varname> - above. Use of this setting is - optional. Specifier and environment - variable substitution is supported - here following the same scheme as for - <varname>ExecStart=</varname>.</para> - - <para>One additional, special - environment variable is set: if known, - <varname>$MAINPID</varname> is set to - the main process of the daemon, and - may be used for command lines like the - following:</para> - - <programlisting>/bin/kill -HUP $MAINPID</programlisting> - - <para>Note however that reloading a - daemon by sending a signal (as with - the example line above) is usually not - a good choice, because this is an - asynchronous operation and hence not - suitable to order reloads of multiple - services against each other. It is - strongly recommended to set - <varname>ExecReload=</varname> to a - command that not only triggers a - configuration reload of the daemon, - but also synchronously waits for it to - complete.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ExecStop=</varname></term> - <listitem><para>Commands to execute to - stop the service started via - <varname>ExecStart=</varname>. This - argument takes multiple command lines, - following the same scheme as described - for <varname>ExecStart=</varname> - above. Use of this setting is - optional. After the commands configured - in this option are run, all processes - remaining for a service are - terminated according to the - <varname>KillMode=</varname> setting - (see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If - this option is not specified, the - process is terminated immediately when - service stop is requested. Specifier - and environment variable substitution - is supported (including - <varname>$MAINPID</varname>, see - above).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ExecStopPost=</varname></term> - <listitem><para>Additional commands - that are executed after the service - was stopped. This includes cases where - the commands configured in - <varname>ExecStop=</varname> were used, - where the service does not have any - <varname>ExecStop=</varname> defined, or - where the service exited unexpectedly. This - argument takes multiple command lines, - following the same scheme as described - for <varname>ExecStart</varname>. Use - of these settings is - optional. Specifier and environment - variable substitution is - supported.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RestartSec=</varname></term> - <listitem><para>Configures the time to - sleep before restarting a service (as - configured with - <varname>Restart=</varname>). Takes a - unit-less value in seconds, or a time - span value such as "5min - 20s". Defaults to - 100ms.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TimeoutStartSec=</varname></term> - <listitem><para>Configures the time to - wait for start-up. If a - daemon service does not signal - start-up completion within the - configured time, the service will be - considered failed and will be shut - down again. - Takes a unit-less value in seconds, or a - time span value such as "5min - 20s". Pass <literal>0</literal> to - disable the timeout logic. Defaults to - <varname>DefaultTimeoutStartSec=</varname> from - the manager configuration file, except - when <varname>Type=oneshot</varname> is - used, in which case the timeout - is disabled by default - (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TimeoutStopSec=</varname></term> - <listitem><para>Configures the time to - wait for stop. If a service is asked - to stop, but does not terminate in the - specified time, it will be terminated - forcibly via <constant>SIGTERM</constant>, - and after another timeout of equal duration - with <constant>SIGKILL</constant> (see - <varname>KillMode=</varname> - in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - Takes a unit-less value in seconds, or a - time span value such as "5min - 20s". Pass <literal>0</literal> to disable - the timeout logic. Defaults to - <varname>DefaultTimeoutStopSec=</varname> from the - manager configuration file - (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TimeoutSec=</varname></term> - <listitem><para>A shorthand for configuring - both <varname>TimeoutStartSec=</varname> - and <varname>TimeoutStopSec=</varname> - to the specified value. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>WatchdogSec=</varname></term> - <listitem><para>Configures the - watchdog timeout for a service. The - watchdog is activated when the start-up is - completed. The service must call - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - regularly with <literal>WATCHDOG=1</literal> - (i.e. the "keep-alive ping"). If the time - between two such calls is larger than - the configured time, then the service - is placed in a failed state and it will - be terminated with <varname>SIGABRT</varname>. - By setting <varname>Restart=</varname> to - <option>on-failure</option> or - <option>always</option>, the service - will be automatically restarted. The - time configured here will be passed to - the executed service process in the - <varname>WATCHDOG_USEC=</varname> - environment variable. This allows - daemons to automatically enable the - keep-alive pinging logic if watchdog - support is enabled for the service. If - this option is used, - <varname>NotifyAccess=</varname> (see - below) should be set to open access to - the notification socket provided by - systemd. If - <varname>NotifyAccess=</varname> is - not set, it will be implicitly set to - <option>main</option>. Defaults to 0, - which disables this - feature.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Restart=</varname></term> - <listitem><para>Configures whether the - service shall be restarted when the - service process exits, is killed, - or a timeout is reached. The service - process may be the main service - process, but it may also be one of the - processes specified with - <varname>ExecStartPre=</varname>, - <varname>ExecStartPost=</varname>, - <varname>ExecStop=</varname>, - <varname>ExecStopPost=</varname>, or - <varname>ExecReload=</varname>. - When the death of the process is a - result of systemd operation (e.g. service - stop or restart), the service will not be - restarted. Timeouts include missing - the watchdog "keep-alive ping" - deadline and a service start, reload, - and stop operation timeouts.</para> - - <para>Takes one of - <option>no</option>, - <option>on-success</option>, - <option>on-failure</option>, - <option>on-abnormal</option>, - <option>on-watchdog</option>, - <option>on-abort</option>, or - <option>always</option>. If set to - <option>no</option> (the default), the - service will not be restarted. If set - to <option>on-success</option>, it - will be restarted only when the - service process exits cleanly. In - this context, a clean exit means an - exit code of 0, or one of the signals - <constant>SIGHUP</constant>, - <constant>SIGINT</constant>, - <constant>SIGTERM</constant> or - <constant>SIGPIPE</constant>, and - additionally, exit statuses and - signals specified in - <varname>SuccessExitStatus=</varname>. - If set to <option>on-failure</option>, - the service will be restarted when the - process exits with a non-zero exit - code, is terminated by a signal - (including on core dump, but excluding - the aforementiond four signals), when - an operation (such as service reload) - times out, and when the configured - watchdog timeout is triggered. If set - to <option>on-abnormal</option>, the - service will be restarted when the - process is terminated by a signal - (including on core dump, excluding the - aforementioned four signals), when an - operation times out, or when the - watchdog timeout is triggered. If set - to <option>on-abort</option>, the - service will be restarted only if the - service process exits due to an - uncaught signal not specified as a - clean exit status. If set to - <option>on-watchdog</option>, the - service will be restarted only if the - watchdog timeout for the service - expires. If set to - <option>always</option>, the service - will be restarted regardless of - whether it exited cleanly or not, got - terminated abnormally by a signal, or - hit a timeout.</para> - - <table> - <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title> - - <tgroup cols='2'> - <colspec colname='path' /> - <colspec colname='expl' /> - <thead> - <row> - <entry>Restart settings/Exit causes</entry> - <entry><option>no</option></entry> - <entry><option>always</option></entry> - <entry><option>on-success</option></entry> - <entry><option>on-failure</option></entry> - <entry><option>on-abnormal</option></entry> - <entry><option>on-abort</option></entry> - <entry><option>on-watchdog</option></entry> - </row> - </thead> - <tbody> - <row> - <entry>Clean exit code or signal</entry> - <entry/> - <entry>X</entry> - <entry>X</entry> - <entry/> - <entry/> - <entry/> - <entry/> - </row> - <row> - <entry>Unclean exit code</entry> - <entry/> - <entry>X</entry> - <entry/> - <entry>X</entry> - <entry/> - <entry/> - <entry/> - </row> - <row> - <entry>Unclean signal</entry> - <entry/> - <entry>X</entry> - <entry/> - <entry>X</entry> - <entry>X</entry> - <entry>X</entry> - <entry/> - </row> - <row> - <entry>Timeout</entry> - <entry/> - <entry>X</entry> - <entry/> - <entry>X</entry> - <entry>X</entry> - <entry/> - <entry/> - </row> - <row> - <entry>Watchdog</entry> - <entry/> - <entry>X</entry> - <entry/> - <entry>X</entry> - <entry>X</entry> - <entry/> - <entry>X</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>As exceptions to the setting - above the service will not be - restarted if the exit code or signal - is specified in - <varname>RestartPreventExitStatus=</varname> - (see below). Also, the services will - always be restarted if the exit code - or signal is specified in - <varname>RestartForceExitStatus=</varname> - (see below).</para> - - <para>Setting this to - <option>on-failure</option> is the - recommended choice for long-running - services, in order to increase - reliability by attempting automatic - recovery from errors. For services - that shall be able to terminate on - their own choice (and avoid - immediate restarting), - <option>on-abnormal</option> is an - alternative choice.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>SuccessExitStatus=</varname></term> - <listitem><para>Takes a list of exit - status definitions that when returned - by the main service process will be - considered successful termination, in - addition to the normal successful exit - code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>, - <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status - definitions can either be numeric exit - codes or termination signal names, - separated by spaces. For example: - <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting> - ensures that exit codes 1, 2, 8 and - the termination signal - <constant>SIGKILL</constant> are - considered clean service terminations. - </para> - - <para>Note that if a process has a - signal handler installed and exits by - calling - <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry> - in response to a signal, the - information about the signal is lost. - Programs should instead perform cleanup and kill themselves with the same signal instead. See - <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para> - - <para>This option may appear more than once, - in which case the list of successful - exit statuses is merged. If the empty - string is assigned to this option, the - list is reset, all prior assignments - of this option will have no - effect.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RestartPreventExitStatus=</varname></term> - <listitem><para>Takes a list of exit - status definitions that when returned - by the main service process will - prevent automatic service restarts, - regardless of the restart setting - configured with - <varname>Restart=</varname>. Exit - status definitions can either be - numeric exit codes or termination - signal names, and are separated by - spaces. Defaults to the empty list, so - that, by default, no exit status is - excluded from the configured restart - logic. For example: - <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit - codes 1 and 6 and the termination - signal <constant>SIGABRT</constant> will - not result in automatic service - restarting. This - option may appear more than once, in - which case the list of restart-preventing - statuses is merged. If the empty - string is assigned to this option, the - list is reset and all prior assignments - of this option will have no - effect.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RestartForceExitStatus=</varname></term> - <listitem><para>Takes a list of exit - status definitions that when returned - by the main service process will force - automatic service restarts, regardless - of the restart setting configured with - <varname>Restart=</varname>. The - argument format is similar to - <varname>RestartPreventExitStatus=</varname>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PermissionsStartOnly=</varname></term> - <listitem><para>Takes a boolean - argument. If true, the permission-related - execution options, as - configured with - <varname>User=</varname> and similar - options (see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information), are only applied - to the process started with - <varname>ExecStart=</varname>, and not - to the various other - <varname>ExecStartPre=</varname>, - <varname>ExecStartPost=</varname>, - <varname>ExecReload=</varname>, - <varname>ExecStop=</varname>, and - <varname>ExecStopPost=</varname> - commands. If false, the setting is - applied to all configured commands the - same way. Defaults to - false.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RootDirectoryStartOnly=</varname></term> - <listitem><para>Takes a boolean - argument. If true, the root directory, - as configured with the - <varname>RootDirectory=</varname> - option (see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information), is only applied - to the process started with - <varname>ExecStart=</varname>, and not - to the various other - <varname>ExecStartPre=</varname>, - <varname>ExecStartPost=</varname>, - <varname>ExecReload=</varname>, - <varname>ExecStop=</varname>, and - <varname>ExecStopPost=</varname> - commands. If false, the setting is - applied to all configured commands the - same way. Defaults to - false.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>NonBlocking=</varname></term> - <listitem><para>Set the - <constant>O_NONBLOCK</constant> flag - for all file descriptors passed via - socket-based activation. If true, all - file descriptors >= 3 (i.e. all except - stdin, stdout, and stderr) will have - the <constant>O_NONBLOCK</constant> flag - set and hence are in - non-blocking mode. This option is only - useful in conjunction with a socket - unit, as described in - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults - to false.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>NotifyAccess=</varname></term> - <listitem><para>Controls access to the - service status notification socket, as - accessible via the - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call. Takes one of - <option>none</option> (the default), - <option>main</option> or - <option>all</option>. If - <option>none</option>, no daemon status - updates are accepted from the service - processes, all status update messages - are ignored. If <option>main</option>, - only service updates sent from the - main process of the service are - accepted. If <option>all</option>, all - services updates from all members of - the service's control group are - accepted. This option should be set to - open access to the notification socket - when using - <varname>Type=notify</varname> or - <varname>WatchdogSec=</varname> (see - above). If those options are used but - <varname>NotifyAccess=</varname> is not - configured, it will be implicitly set - to - <option>main</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Sockets=</varname></term> - <listitem><para>Specifies the name of - the socket units this service shall - inherit socket file descriptors - from when the service is - started. Normally it should not be - necessary to use this setting as all - socket file descriptors whose unit - shares the same name as the service - (subject to the different unit name - suffix of course) are passed to the - spawned process.</para> - - <para>Note that the same socket file - descriptors may be passed to multiple - processes simultaneously. Also note - that a different service may be - activated on incoming socket traffic - than the one which is ultimately - configured to inherit the socket file - descriptors. Or in other words: the - <varname>Service=</varname> setting of - <filename>.socket</filename> units - does not have to match the inverse of - the <varname>Sockets=</varname> - setting of the - <filename>.service</filename> it - refers to.</para> - - <para>This option may appear more than - once, in which case the list of socket - units is merged. If the empty string - is assigned to this option, the list of - sockets is reset, and all prior uses of - this setting will have no - effect.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>StartLimitInterval=</varname></term> - <term><varname>StartLimitBurst=</varname></term> - - <listitem><para>Configure service - start rate limiting. By default, - services which are started more - than 5 times within 10 seconds are not - permitted to start any more times - until the 10 second interval ends. With - these two options, this rate limiting - may be modified. Use - <varname>StartLimitInterval=</varname> - to configure the checking interval (defaults to - <varname>DefaultStartLimitInterval=</varname> in - manager configuration file, set to 0 to disable - any kind of rate limiting). Use - <varname>StartLimitBurst=</varname> to - configure how many starts per interval - are allowed (defaults to - <varname>DefaultStartLimitBurst=</varname> in - manager configuration file). These - configuration options are particularly - useful in conjunction with - <varname>Restart=</varname>; however, - they apply to all kinds of starts - (including manual), not just those - triggered by the - <varname>Restart=</varname> logic. - Note that units which are configured - for <varname>Restart=</varname> and - which reach the start limit are not - attempted to be restarted anymore; - however, they may still be restarted - manually at a later point, from which - point on, the restart logic is again - activated. Note that - <command>systemctl - reset-failed</command> will cause the - restart rate counter for a service to - be flushed, which is useful if the - administrator wants to manually start - a service and the start limit - interferes with - that.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>StartLimitAction=</varname></term> - - <listitem><para>Configure the action - to take if the rate limit configured - with - <varname>StartLimitInterval=</varname> - and - <varname>StartLimitBurst=</varname> is - hit. Takes one of - <option>none</option>, - <option>reboot</option>, - <option>reboot-force</option>, - <option>reboot-immediate</option>, - <option>poweroff</option>, - <option>poweroff-force</option> or - <option>poweroff-immediate</option>. If - <option>none</option> is set, hitting - the rate limit will trigger no action - besides that the start will not be - permitted. <option>reboot</option> - causes a reboot following the normal - shutdown procedure (i.e. equivalent to - <command>systemctl reboot</command>). - <option>reboot-force</option> causes a - forced reboot which will terminate all - processes forcibly but should cause no - dirty file systems on reboot - (i.e. equivalent to <command>systemctl - reboot -f</command>) and - <option>reboot-immediate</option> - causes immediate execution of the - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call, which might result in - data loss. Similar, - <option>poweroff</option>, - <option>poweroff-force</option>, - <option>poweroff-immediate</option> - have the effect of powering down the - system with similar - semantics. Defaults to - <option>none</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>FailureAction=</varname></term> - <listitem><para>Configure the action - to take when the service enters a failed - state. Takes the same values as - <varname>StartLimitAction=</varname> - and executes the same actions. - Defaults to <option>none</option>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RebootArgument=</varname></term> - <listitem><para>Configure the optional - argument for the - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call if - <varname>StartLimitAction=</varname> - or <varname>FailureAction=</varname> - is a reboot action. This works just - like the optional argument to - <command>systemctl reboot</command> - command.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>FileDescriptorStoreMax=</varname></term> - <listitem><para>Configure how many - file descriptors may be stored in the - service manager for the service using - <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s - <literal>FDSTORE=1</literal> - messages. This is useful for - implementing service restart schemes - where the state is serialized to - <filename>/run</filename> and the file - descriptors passed to the service - manager, to allow restarts without - losing state. Defaults to 0, i.e. no - file descriptors may be stored in the - service manager by default. All file - descriptors passed to the service - manager from a specific service are - passed back to the service's main - process on the next service - restart. Any file descriptors passed - to the service manager are - automatically closed when POLLHUP or - POLLERR is seen on them, or when the - service is fully stopped and no job - queued or being executed for - it.</para></listitem> - </varlistentry> - - </variablelist> - - <para>Check - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more settings.</para> - - </refsect1> - - <refsect1> - <title>Command lines</title> - - <para>This section describes command line parsing and - variable and specifier substitions for - <varname>ExecStart=</varname>, - <varname>ExecStartPre=</varname>, - <varname>ExecStartPost=</varname>, - <varname>ExecReload=</varname>, - <varname>ExecStop=</varname>, and - <varname>ExecStopPost=</varname> options.</para> - - <para>Multiple command lines may be concatenated in a - single directive by separating them with semicolons - (these semicolons must be passed as separate words). - Lone semicolons may be escaped as - <literal>\;</literal>.</para> - - <para>Each command line is split on whitespace, with - the first item being the command to execute, and the - subsequent items being the arguments. Double quotes - ("...") and single quotes ('...') may be used, in - which case everything until the next matching quote - becomes part of the same argument. C-style escapes are - also supported, see table below. Quotes themselves are - removed after parsing and escape sequences - substituted. In addition, a trailing backslash - (<literal>\</literal>) may be used to merge lines. - </para> - - <para>This syntax is intended to be very similar to - shell syntax, but only the meta-characters and - expansions described in the following paragraphs are - understood. Specifically, redirection using - <literal><</literal>, <literal><<</literal>, - <literal>></literal>, and - <literal>>></literal>, pipes using - <literal>|</literal>, running programs in the - background using <literal>&</literal>, and - <emphasis>other elements of shell syntax are not - supported</emphasis>.</para> - - <para>The command to execute must an absolute path - name. It may contain spaces, but control characters - are not allowed.</para> - - <para>The command line accepts <literal>%</literal> - specifiers as described in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - Note that the first argument of the command line - (i.e. the program to execute) may not include - specifiers.</para> - - <para>Basic environment variable substitution is - supported. Use <literal>${FOO}</literal> as part of a - word, or as a word of its own, on the command line, in - which case it will be replaced by the value of the - environment variable including all whitespace it - contains, resulting in a single argument. Use - <literal>$FOO</literal> as a separate word on the - command line, in which case it will be replaced by the - value of the environment variable split at whitespace - resulting in zero or more arguments. For this type of - expansion, quotes and respected when splitting into - words, and afterwards removed.</para> - - <para>Example:</para> - - <programlisting>Environment="ONE=one" 'TWO=two two' + <refentryinfo> + <title>systemd.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.service</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.service</refname> + <refpurpose>Service unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>service</replaceable>.service</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <filename>.service</filename> encodes information about a process + controlled and supervised by systemd.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic + <literal>[Unit]</literal> and <literal>[Install]</literal> + sections. The service specific configuration options are + configured in the <literal>[Service]</literal> section.</para> + + <para>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the commands are executed + in, and in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the way the processes of the service are terminated, + and in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which configure resource control settings for the processes of the + service.</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>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>If a service is requested under a certain name but no unit + configuration file is found, systemd looks for a SysV init script + by the same name (with the <filename>.service</filename> suffix + removed) and dynamically creates a service unit from that script. + This is useful for compatibility with SysV. Note that this + compatibility is quite comprehensive but not 100%. For details + about the incompatibilities, see the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities + with SysV</ulink> document. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Service files must include a <literal>[Service]</literal> + section, which carries information about the service and the + process it supervises. A number of options that may be used in + this section are shared with other unit types. These options are + documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + The options specific to the <literal>[Service]</literal> section + of service units are the following:</para> + + <variablelist class='unit-directives'> + <varlistentry> + <term><varname>Type=</varname></term> + + <listitem><para>Configures the process start-up type for this + service unit. One of + <option>simple</option>, + <option>forking</option>, + <option>oneshot</option>, + <option>dbus</option>, + <option>notify</option> or + <option>idle</option>.</para> + + <para>If set to <option>simple</option> (the default if + neither <varname>Type=</varname> nor + <varname>BusName=</varname>, but <varname>ExecStart=</varname> + are specified), it is expected that the process configured + with <varname>ExecStart=</varname> is the main process of the + service. In this mode, if the process offers functionality to + other processes on the system, its communication channels + should be installed before the daemon is started up (e.g. + sockets set up by systemd, via socket activation), as systemd + will immediately proceed starting follow-up units.</para> + + <para>If set to <option>forking</option>, it is expected that + the process configured with <varname>ExecStart=</varname> will + call <function>fork()</function> as part of its start-up. The + parent process is expected to exit when start-up is complete + and all communication channels are set up. The child continues + to run as the main daemon process. This is the behavior of + traditional UNIX daemons. If this setting is used, it is + recommended to also use the <varname>PIDFile=</varname> + option, so that systemd can identify the main process of the + daemon. systemd will proceed with starting follow-up units as + soon as the parent process exits.</para> + + <para>Behavior of <option>oneshot</option> is similar to + <option>simple</option>; however, it is expected that the + process has to exit before systemd starts follow-up units. + <varname>RemainAfterExit=</varname> is particularly useful for + this type of service. This is the implied default if neither + <varname>Type=</varname> or <varname>ExecStart=</varname> are + specified.</para> + + <para>Behavior of <option>dbus</option> is similar to + <option>simple</option>; however, it is expected that the + daemon acquires a name on the D-Bus bus, as configured by + <varname>BusName=</varname>. systemd will proceed with + starting follow-up units after the D-Bus bus name has been + acquired. Service units with this option configured implicitly + gain dependencies on the <filename>dbus.socket</filename> + unit. This type is the default if <varname>BusName=</varname> + is specified.</para> + + <para>Behavior of <option>notify</option> is similar to + <option>simple</option>; however, it is expected that the + daemon sends a notification message via + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or an equivalent call when it has finished starting up. + systemd will proceed with starting follow-up units after this + notification message has been sent. If this option is used, + <varname>NotifyAccess=</varname> (see below) should be set to + open access to the notification socket provided by systemd. If + <varname>NotifyAccess=</varname> is not set, it will be + implicitly set to <option>main</option>. Note that currently + <varname>Type=</varname><option>notify</option> will not work + if used in combination with + <varname>PrivateNetwork=</varname><option>yes</option>.</para> + + <para>Behavior of <option>idle</option> is very similar to + <option>simple</option>; however, actual execution of the + service binary is delayed until all jobs are dispatched. This + may be used to avoid interleaving of output of shell services + with the status output on the console.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>RemainAfterExit=</varname></term> + + <listitem><para>Takes a boolean value that specifies whether + the service shall be considered active even when all its + processes exited. Defaults to <option>no</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>GuessMainPID=</varname></term> + + <listitem><para>Takes a boolean value that specifies whether + systemd should try to guess the main PID of a service if it + cannot be determined reliably. This option is ignored unless + <option>Type=forking</option> is set and + <option>PIDFile=</option> is unset because for the other types + or with an explicitly configured PID file, the main PID is + always known. The guessing algorithm might come to incorrect + conclusions if a daemon consists of more than one process. If + the main PID cannot be determined, failure detection and + automatic restarting of a service will not work reliably. + Defaults to <option>yes</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>PIDFile=</varname></term> + + <listitem><para>Takes an absolute file name pointing to the + PID file of this daemon. Use of this option is recommended for + services where <varname>Type=</varname> is set to + <option>forking</option>. systemd will read the PID of the + main process of the daemon after start-up of the service. + systemd will not write to the file configured here.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BusName=</varname></term> + + <listitem><para>Takes a D-Bus bus name that this service is + reachable as. This option is mandatory for services where + <varname>Type=</varname> is set to + <option>dbus</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>BusPolicy=</varname></term> + + <listitem><para>If specified, a custom + <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink> + 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 + zero or more command lines is according to the rules described + below (see section "Command Lines" below). + </para> + + <para>When <varname>Type</varname> is not + <option>oneshot</option>, only one command may and must be + given. When <varname>Type=oneshot</varname> is used, zero or + more commands may be specified. This can be specified by + providing multiple command lines in the same directive, or + alternatively, this directive may be specified more than once + with the same effect. If the empty string is assigned to this + option, the list of commands to start is reset, prior + assignments of this option will have no effect. If no + <varname>ExecStart=</varname> is specified, then the service + must have <varname>RemainAfterExit=yes</varname> set.</para> + + <para>For each of the specified commands, the first argument + must be an absolute path to an executable. Optionally, if this + file name is prefixed with <literal>@</literal>, the second + token will be passed as <literal>argv[0]</literal> to the + executed process, followed by the further arguments specified. + If the absolute filename is prefixed with + <literal>-</literal>, an exit code of the command normally + considered a failure (i.e. non-zero exit status or abnormal + exit due to signal) is ignored and considered success. If both + <literal>-</literal> and <literal>@</literal> are used, they + can appear in either order.</para> + + <para>If more than one command is specified, the commands are + invoked sequentially in the order they appear in the unit + file. If one of the commands fails (and is not prefixed with + <literal>-</literal>), other lines are not executed, and the + unit is considered failed.</para> + + <para>Unless <varname>Type=forking</varname> is set, the + process started via this command line will be considered the + main process of the daemon.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStartPre=</varname></term> + <term><varname>ExecStartPost=</varname></term> + <listitem><para>Additional commands that are executed before + or after the command in <varname>ExecStart=</varname>, + respectively. Syntax is the same as for + <varname>ExecStart=</varname>, except that multiple command + lines are allowed and the commands are executed one after the + other, serially.</para> + + <para>If any of those commands (not prefixed with + <literal>-</literal>) fail, the rest are not executed and the + unit is considered failed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecReload=</varname></term> + <listitem><para>Commands to execute to trigger a configuration + reload in the service. This argument takes multiple command + lines, following the same scheme as described for + <varname>ExecStart=</varname> above. Use of this setting is + optional. Specifier and environment variable substitution is + supported here following the same scheme as for + <varname>ExecStart=</varname>.</para> + + <para>One additional, special environment variable is set: if + known, <varname>$MAINPID</varname> is set to the main process + of the daemon, and may be used for command lines like the + following:</para> + + <programlisting>/bin/kill -HUP $MAINPID</programlisting> + + <para>Note however that reloading a daemon by sending a signal + (as with the example line above) is usually not a good choice, + because this is an asynchronous operation and hence not + suitable to order reloads of multiple services against each + other. It is strongly recommended to set + <varname>ExecReload=</varname> to a command that not only + triggers a configuration reload of the daemon, but also + synchronously waits for it to complete.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStop=</varname></term> + <listitem><para>Commands to execute to stop the service + started via <varname>ExecStart=</varname>. This argument takes + multiple command lines, following the same scheme as described + for <varname>ExecStart=</varname> above. Use of this setting + is optional. After the commands configured in this option are + run, all processes remaining for a service are terminated + according to the <varname>KillMode=</varname> setting (see + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + If this option is not specified, the process is terminated + immediately when service stop is requested. Specifier and + environment variable substitution is supported (including + <varname>$MAINPID</varname>, see above).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStopPost=</varname></term> + <listitem><para>Additional commands that are executed after + the service was stopped. This includes cases where the + commands configured in <varname>ExecStop=</varname> were used, + where the service does not have any + <varname>ExecStop=</varname> defined, or where the service + exited unexpectedly. This argument takes multiple command + lines, following the same scheme as described for + <varname>ExecStart</varname>. Use of these settings is + optional. Specifier and environment variable substitution is + supported.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestartSec=</varname></term> + <listitem><para>Configures the time to sleep before restarting + a service (as configured with <varname>Restart=</varname>). + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Defaults to 100ms.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutStartSec=</varname></term> + <listitem><para>Configures the time to wait for start-up. If a + daemon service does not signal start-up completion within the + configured time, the service will be considered failed and + will be shut down again. Takes a unit-less value in seconds, + or a time span value such as "5min 20s". Pass + <literal>0</literal> to disable the timeout logic. Defaults to + <varname>DefaultTimeoutStartSec=</varname> from the manager + configuration file, except when + <varname>Type=oneshot</varname> is used, in which case the + timeout is disabled by default (see + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutStopSec=</varname></term> + <listitem><para>Configures the time to wait for stop. If a + service is asked to stop, but does not terminate in the + specified time, it will be terminated forcibly via + <constant>SIGTERM</constant>, and after another timeout of + equal duration with <constant>SIGKILL</constant> (see + <varname>KillMode=</varname> in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Pass <literal>0</literal> to disable the + timeout logic. Defaults to + <varname>DefaultTimeoutStopSec=</varname> from the manager + configuration file (see + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>A shorthand for configuring both + <varname>TimeoutStartSec=</varname> and + <varname>TimeoutStopSec=</varname> to the specified value. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>WatchdogSec=</varname></term> + <listitem><para>Configures the watchdog timeout for a service. + The watchdog is activated when the start-up is completed. The + service must call + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + regularly with <literal>WATCHDOG=1</literal> (i.e. the + "keep-alive ping"). If the time between two such calls is + larger than the configured time, then the service is placed in + a failed state and it will be terminated with + <varname>SIGABRT</varname>. By setting + <varname>Restart=</varname> to <option>on-failure</option> or + <option>always</option>, the service will be automatically + restarted. The time configured here will be passed to the + executed service process in the + <varname>WATCHDOG_USEC=</varname> environment variable. This + allows daemons to automatically enable the keep-alive pinging + logic if watchdog support is enabled for the service. If this + option is used, <varname>NotifyAccess=</varname> (see below) + should be set to open access to the notification socket + provided by systemd. If <varname>NotifyAccess=</varname> is + not set, it will be implicitly set to <option>main</option>. + Defaults to 0, which disables this feature.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Restart=</varname></term> + <listitem><para>Configures whether the service shall be + restarted when the service process exits, is killed, or a + timeout is reached. The service process may be the main + service process, but it may also be one of the processes + specified with <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecStop=</varname>, + <varname>ExecStopPost=</varname>, or + <varname>ExecReload=</varname>. When the death of the process + is a result of systemd operation (e.g. service stop or + restart), the service will not be restarted. Timeouts include + missing the watchdog "keep-alive ping" deadline and a service + start, reload, and stop operation timeouts.</para> + + <para>Takes one of + <option>no</option>, + <option>on-success</option>, + <option>on-failure</option>, + <option>on-abnormal</option>, + <option>on-watchdog</option>, + <option>on-abort</option>, or + <option>always</option>. + If set to <option>no</option> (the default), the service will + not be restarted. If set to <option>on-success</option>, it + will be restarted only when the service process exits cleanly. + In this context, a clean exit means an exit code of 0, or one + of the signals + <constant>SIGHUP</constant>, + <constant>SIGINT</constant>, + <constant>SIGTERM</constant> or + <constant>SIGPIPE</constant>, and + additionally, exit statuses and signals specified in + <varname>SuccessExitStatus=</varname>. If set to + <option>on-failure</option>, the service will be restarted + when the process exits with a non-zero exit code, is + terminated by a signal (including on core dump, but excluding + the aforementiond four signals), when an operation (such as + service reload) times out, and when the configured watchdog + timeout is triggered. If set to <option>on-abnormal</option>, + the service will be restarted when the process is terminated + by a signal (including on core dump, excluding the + aforementioned four signals), when an operation times out, or + when the watchdog timeout is triggered. If set to + <option>on-abort</option>, the service will be restarted only + if the service process exits due to an uncaught signal not + specified as a clean exit status. If set to + <option>on-watchdog</option>, the service will be restarted + only if the watchdog timeout for the service expires. If set + to <option>always</option>, the service will be restarted + regardless of whether it exited cleanly or not, got terminated + abnormally by a signal, or hit a timeout.</para> + + <table> + <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title> + + <tgroup cols='2'> + <colspec colname='path' /> + <colspec colname='expl' /> + <thead> + <row> + <entry>Restart settings/Exit causes</entry> + <entry><option>no</option></entry> + <entry><option>always</option></entry> + <entry><option>on-success</option></entry> + <entry><option>on-failure</option></entry> + <entry><option>on-abnormal</option></entry> + <entry><option>on-abort</option></entry> + <entry><option>on-watchdog</option></entry> + </row> + </thead> + <tbody> + <row> + <entry>Clean exit code or signal</entry> + <entry/> + <entry>X</entry> + <entry>X</entry> + <entry/> + <entry/> + <entry/> + <entry/> + </row> + <row> + <entry>Unclean exit code</entry> + <entry/> + <entry>X</entry> + <entry/> + <entry>X</entry> + <entry/> + <entry/> + <entry/> + </row> + <row> + <entry>Unclean signal</entry> + <entry/> + <entry>X</entry> + <entry/> + <entry>X</entry> + <entry>X</entry> + <entry>X</entry> + <entry/> + </row> + <row> + <entry>Timeout</entry> + <entry/> + <entry>X</entry> + <entry/> + <entry>X</entry> + <entry>X</entry> + <entry/> + <entry/> + </row> + <row> + <entry>Watchdog</entry> + <entry/> + <entry>X</entry> + <entry/> + <entry>X</entry> + <entry>X</entry> + <entry/> + <entry>X</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>As exceptions to the setting above the service will not + be restarted if the exit code or signal is specified in + <varname>RestartPreventExitStatus=</varname> (see below). + Also, the services will always be restarted if the exit code + or signal is specified in + <varname>RestartForceExitStatus=</varname> (see below).</para> + + <para>Setting this to <option>on-failure</option> is the + recommended choice for long-running services, in order to + increase reliability by attempting automatic recovery from + errors. For services that shall be able to terminate on their + own choice (and avoid immediate restarting), + <option>on-abnormal</option> is an alternative choice.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>SuccessExitStatus=</varname></term> + <listitem><para>Takes a list of exit status definitions that + when returned by the main service process will be considered + successful termination, in addition to the normal successful + exit code 0 and the signals <constant>SIGHUP</constant>, + <constant>SIGINT</constant>, <constant>SIGTERM</constant>, and + <constant>SIGPIPE</constant>. Exit status definitions can + either be numeric exit codes or termination signal names, + separated by spaces. For example: + <programlisting>SuccessExitStatus=1 2 8 + SIGKILL</programlisting> ensures that exit codes 1, 2, 8 and + the termination signal <constant>SIGKILL</constant> are + considered clean service terminations. + </para> + + <para>Note that if a process has a signal handler installed + and exits by calling + <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry> + in response to a signal, the information about the signal is + lost. Programs should instead perform cleanup and kill + themselves with the same signal instead. See + <ulink url="http://www.cons.org/cracauer/sigint.html">Proper + handling of SIGINT/SIGQUIT — How to be a proper + program</ulink>.</para> + + <para>This option may appear more than once, in which case the + list of successful exit statuses is merged. If the empty + string is assigned to this option, the list is reset, all + prior assignments of this option will have no + effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestartPreventExitStatus=</varname></term> + <listitem><para>Takes a list of exit status definitions that + when returned by the main service process will prevent + automatic service restarts, regardless of the restart setting + configured with <varname>Restart=</varname>. Exit status + definitions can either be numeric exit codes or termination + signal names, and are separated by spaces. Defaults to the + empty list, so that, by default, no exit status is excluded + from the configured restart logic. For example: + <programlisting>RestartPreventExitStatus=1 6 + SIGABRT</programlisting> ensures that exit codes 1 and 6 and + the termination signal <constant>SIGABRT</constant> will not + result in automatic service restarting. This option may appear + more than once, in which case the list of restart-preventing + statuses is merged. If the empty string is assigned to this + option, the list is reset and all prior assignments of this + option will have no effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RestartForceExitStatus=</varname></term> + <listitem><para>Takes a list of exit status definitions that + when returned by the main service process will force automatic + service restarts, regardless of the restart setting configured + with <varname>Restart=</varname>. The argument format is + similar to + <varname>RestartPreventExitStatus=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PermissionsStartOnly=</varname></term> + <listitem><para>Takes a boolean argument. If true, the + permission-related execution options, as configured with + <varname>User=</varname> and similar options (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information), are only applied to the process started + with + <varname>ExecStart=</varname>, and not to the various other + <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecReload=</varname>, + <varname>ExecStop=</varname>, and + <varname>ExecStopPost=</varname> + commands. If false, the setting is applied to all configured + commands the same way. Defaults to false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RootDirectoryStartOnly=</varname></term> + <listitem><para>Takes a boolean argument. If true, the root + directory, as configured with the + <varname>RootDirectory=</varname> option (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information), is only applied to the process started + with <varname>ExecStart=</varname>, and not to the various + other <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecReload=</varname>, <varname>ExecStop=</varname>, + and <varname>ExecStopPost=</varname> commands. If false, the + setting is applied to all configured commands the same way. + Defaults to false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>NonBlocking=</varname></term> + <listitem><para>Set the <constant>O_NONBLOCK</constant> flag + for all file descriptors passed via socket-based activation. + If true, all file descriptors >= 3 (i.e. all except stdin, + stdout, and stderr) will have the + <constant>O_NONBLOCK</constant> flag set and hence are in + non-blocking mode. This option is only useful in conjunction + with a socket unit, as described in + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Defaults to false.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>NotifyAccess=</varname></term> + <listitem><para>Controls access to the service status + notification socket, as accessible via the + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call. Takes one of <option>none</option> (the default), + <option>main</option> or <option>all</option>. If + <option>none</option>, no daemon status updates are accepted + from the service processes, all status update messages are + ignored. If <option>main</option>, only service updates sent + from the main process of the service are accepted. If + <option>all</option>, all services updates from all members of + the service's control group are accepted. This option should + be set to open access to the notification socket when using + <varname>Type=notify</varname> or + <varname>WatchdogSec=</varname> (see above). If those options + are used but <varname>NotifyAccess=</varname> is not + configured, it will be implicitly set to + <option>main</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Sockets=</varname></term> + <listitem><para>Specifies the name of the socket units this + service shall inherit socket file descriptors from when the + service is started. Normally it should not be necessary to use + this setting as all socket file descriptors whose unit shares + the same name as the service (subject to the different unit + name suffix of course) are passed to the spawned + process.</para> + + <para>Note that the same socket file descriptors may be passed + to multiple processes simultaneously. Also note that a + different service may be activated on incoming socket traffic + than the one which is ultimately configured to inherit the + socket file descriptors. Or in other words: the + <varname>Service=</varname> setting of + <filename>.socket</filename> units does not have to match the + inverse of the <varname>Sockets=</varname> setting of the + <filename>.service</filename> it refers to.</para> + + <para>This option may appear more than once, in which case the + list of socket units is merged. If the empty string is + assigned to this option, the list of sockets is reset, and all + prior uses of this setting will have no + effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StartLimitInterval=</varname></term> + <term><varname>StartLimitBurst=</varname></term> + + <listitem><para>Configure service start rate limiting. By + default, services which are started more than 5 times within + 10 seconds are not permitted to start any more times until the + 10 second interval ends. With these two options, this rate + limiting may be modified. Use + <varname>StartLimitInterval=</varname> to configure the + checking interval (defaults to + <varname>DefaultStartLimitInterval=</varname> in manager + configuration file, set to 0 to disable any kind of rate + limiting). Use <varname>StartLimitBurst=</varname> to + configure how many starts per interval are allowed (defaults + to <varname>DefaultStartLimitBurst=</varname> in manager + configuration file). These configuration options are + particularly useful in conjunction with + <varname>Restart=</varname>; however, they apply to all kinds + of starts (including manual), not just those triggered by the + <varname>Restart=</varname> logic. Note that units which are + configured for <varname>Restart=</varname> and which reach the + start limit are not attempted to be restarted anymore; + however, they may still be restarted manually at a later + point, from which point on, the restart logic is again + activated. Note that <command>systemctl reset-failed</command> + will cause the restart rate counter for a service to be + flushed, which is useful if the administrator wants to + manually start a service and the start limit interferes with + that.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StartLimitAction=</varname></term> + + <listitem><para>Configure the action to take if the rate limit + configured with <varname>StartLimitInterval=</varname> and + <varname>StartLimitBurst=</varname> is hit. Takes one of + <option>none</option>, + <option>reboot</option>, + <option>reboot-force</option>, + <option>reboot-immediate</option>, + <option>poweroff</option>, + <option>poweroff-force</option> or + <option>poweroff-immediate</option>. If + <option>none</option> is set, hitting the rate limit will + trigger no action besides that the start will not be + permitted. <option>reboot</option> causes a reboot following + the normal shutdown procedure (i.e. equivalent to + <command>systemctl reboot</command>). + <option>reboot-force</option> causes a forced reboot which + will terminate all processes forcibly but should cause no + dirty file systems on reboot (i.e. equivalent to + <command>systemctl reboot -f</command>) and + <option>reboot-immediate</option> causes immediate execution + of the + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system call, which might result in data loss. Similar, + <option>poweroff</option>, <option>poweroff-force</option>, + <option>poweroff-immediate</option> have the effect of + powering down the system with similar semantics. Defaults to + <option>none</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FailureAction=</varname></term> + <listitem><para>Configure the action to take when the service + enters a failed state. Takes the same values as + <varname>StartLimitAction=</varname> and executes the same + actions. Defaults to <option>none</option>. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RebootArgument=</varname></term> + <listitem><para>Configure the optional argument for the + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system call if <varname>StartLimitAction=</varname> or + <varname>FailureAction=</varname> is a reboot action. This + works just like the optional argument to <command>systemctl + reboot</command> command.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FileDescriptorStoreMax=</varname></term> + <listitem><para>Configure how many file descriptors may be + stored in the service manager for the service using + <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s + <literal>FDSTORE=1</literal> messages. This is useful for + implementing service restart schemes where the state is + serialized to <filename>/run</filename> and the file + descriptors passed to the service manager, to allow restarts + without losing state. Defaults to 0, i.e. no file descriptors + may be stored in the service manager by default. All file + descriptors passed to the service manager from a specific + service are passed back to the service's main process on the + next service restart. Any file descriptors passed to the + service manager are automatically closed when POLLHUP or + POLLERR is seen on them, or when the service is fully stopped + and no job queued or being executed for it.</para></listitem> + </varlistentry> + + </variablelist> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</para> + + </refsect1> + + <refsect1> + <title>Command lines</title> + + <para>This section describes command line parsing and + variable and specifier substitions for + <varname>ExecStart=</varname>, + <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecReload=</varname>, + <varname>ExecStop=</varname>, and + <varname>ExecStopPost=</varname> options.</para> + + <para>Multiple command lines may be concatenated in a single + directive by separating them with semicolons (these semicolons + must be passed as separate words). Lone semicolons may be escaped + as <literal>\;</literal>.</para> + + <para>Each command line is split on whitespace, with the first + item being the command to execute, and the subsequent items being + the arguments. Double quotes ("...") and single quotes ('...') may + be used, in which case everything until the next matching quote + becomes part of the same argument. C-style escapes are also + supported, see table below. Quotes themselves are removed after + parsing and escape sequences substituted. In addition, a trailing + backslash (<literal>\</literal>) may be used to merge lines. + </para> + + <para>This syntax is intended to be very similar to shell syntax, + but only the meta-characters and expansions described in the + following paragraphs are understood. Specifically, redirection + using + <literal><</literal>, + <literal><<</literal>, + <literal>></literal>, and + <literal>>></literal>, pipes using + <literal>|</literal>, running programs in the background using + <literal>&</literal>, and <emphasis>other elements of shell + syntax are not supported</emphasis>.</para> + + <para>The command to execute must an absolute path name. It may + contain spaces, but control characters are not allowed.</para> + + <para>The command line accepts <literal>%</literal> specifiers as + described in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Note that the first argument of the command line (i.e. the program + to execute) may not include specifiers.</para> + + <para>Basic environment variable substitution is supported. Use + <literal>${FOO}</literal> as part of a word, or as a word of its + own, on the command line, in which case it will be replaced by the + value of the environment variable including all whitespace it + contains, resulting in a single argument. Use + <literal>$FOO</literal> as a separate word on the command line, in + which case it will be replaced by the value of the environment + variable split at whitespace resulting in zero or more arguments. + For this type of expansion, quotes and respected when splitting + into words, and afterwards removed.</para> + + <para>Example:</para> + + <programlisting>Environment="ONE=one" 'TWO=two two' ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> - <para>This will execute <command>/bin/echo</command> - with four arguments: <literal>one</literal>, - <literal>two</literal>, <literal>two</literal>, and - <literal>two two</literal>.</para> + <para>This will execute <command>/bin/echo</command> with four + arguments: <literal>one</literal>, <literal>two</literal>, + <literal>two</literal>, and <literal>two two</literal>.</para> - <para>Example:</para> - <programlisting>Environment=ONE='one' "TWO='two two' too" THREE= + <para>Example:</para> + <programlisting>Environment=ONE='one' "TWO='two two' too" THREE= ExecStart=/bin/echo ${ONE} ${TWO} ${THREE} ExecStart=/bin/echo $ONE $TWO $THREE</programlisting> - <para>This results in <filename>echo</filename> being - called twice, the first time with arguments - <literal>'one'</literal>, - <literal>'two two' too</literal>, <literal></literal>, - and the second time with arguments - <literal>one</literal>, <literal>two two</literal>, - <literal>too</literal>. - </para> - - <para>To pass a literal dollar sign, use - <literal>$$</literal>. Variables whose value is not - known at expansion time are treated as empty - strings. Note that the first argument (i.e. the - program to execute) may not be a variable.</para> - - <para>Variables to be used in this fashion may be - defined through <varname>Environment=</varname> and - <varname>EnvironmentFile=</varname>. In addition, - variables listed in the section "Environment variables - in spawned processes" in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which are considered "static configuration", may be - used (this includes e.g. <varname>$USER</varname>, but - not <varname>$TERM</varname>).</para> - - <para>Note that shell command lines are not directly - supported. If shell command lines are to be used, they - need to be passed explicitly to a shell implementation - of some kind. Example:</para> - <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting> - - <para>Example:</para> - - <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting> - - <para>This will execute <command>/bin/echo</command> - two times, each time with one argument: - <literal>one</literal> and <literal>two two</literal>, - respectively. Because two commands are specified, - <varname>Type=oneshot</varname> must be used.</para> - - <para>Example:</para> - - <programlisting>ExecStart=/bin/echo / >/dev/null & \; \ + <para>This results in <filename>echo</filename> being + called twice, the first time with arguments + <literal>'one'</literal>, + <literal>'two two' too</literal>, <literal></literal>, + and the second time with arguments + <literal>one</literal>, <literal>two two</literal>, + <literal>too</literal>. + </para> + + <para>To pass a literal dollar sign, use <literal>$$</literal>. + Variables whose value is not known at expansion time are treated + as empty strings. Note that the first argument (i.e. the program + to execute) may not be a variable.</para> + + <para>Variables to be used in this fashion may be defined through + <varname>Environment=</varname> and + <varname>EnvironmentFile=</varname>. In addition, variables listed + in the section "Environment variables in spawned processes" in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which are considered "static configuration", may be used (this + includes e.g. <varname>$USER</varname>, but not + <varname>$TERM</varname>).</para> + + <para>Note that shell command lines are not directly supported. If + shell command lines are to be used, they need to be passed + explicitly to a shell implementation of some kind. Example:</para> + <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting> + + <para>Example:</para> + + <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting> + + <para>This will execute <command>/bin/echo</command> two times, + each time with one argument: <literal>one</literal> and + <literal>two two</literal>, respectively. Because two commands are + specified, <varname>Type=oneshot</varname> must be used.</para> + + <para>Example:</para> + + <programlisting>ExecStart=/bin/echo / >/dev/null & \; \ /bin/ls</programlisting> - <para>This will execute <command>/bin/echo</command> - with five arguments: <literal>/</literal>, - <literal>>/dev/null</literal>, - <literal>&</literal>, <literal>;</literal>, and - <literal>/bin/ls</literal>.</para> - - <table> - <title>C escapes supported in command lines and environment variables</title> - <tgroup cols='2'> - <colspec colname='escape' /> - <colspec colname='meaning' /> - <thead> - <row> - <entry>Literal</entry> - <entry>Actual value</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>\a</literal></entry> - <entry>bell</entry> - </row> - <row> - <entry><literal>\b</literal></entry> - <entry>backspace</entry> - </row> - <row> - <entry><literal>\f</literal></entry> - <entry>form feed</entry> - </row> - <row> - <entry><literal>\n</literal></entry> - <entry>newline</entry> - </row> - <row> - <entry><literal>\r</literal></entry> - <entry>carriage return</entry> - </row> - <row> - <entry><literal>\t</literal></entry> - <entry>tab</entry> - </row> - <row> - <entry><literal>\v</literal></entry> - <entry>vertical tab</entry> - </row> - <row> - <entry><literal>\\</literal></entry> - <entry>backslash</entry> - </row> - <row> - <entry><literal>\"</literal></entry> - <entry>double quotation mark</entry> - </row> - <row> - <entry><literal>\'</literal></entry> - <entry>single quotation mark</entry> - </row> - <row> - <entry><literal>\s</literal></entry> - <entry>space</entry> - </row> - <row> - <entry><literal>\x<replaceable>xx</replaceable></literal></entry> - <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry> - </row> - <row> - <entry><literal>\<replaceable>nnn</replaceable></literal></entry> - <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry> - </row> - </tbody> - </tgroup> - </table> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Simple service</title> - - <para>The following unit file creates a service - that will execute - <filename>/usr/sbin/foo-daemon</filename>. - Since no <varname>Type=</varname> is specified, - the default - <varname>Type=</varname><option>simple</option> - will be assumed. systemd will assume the unit - to be started immediately after the program has - begun executing.</para> - - <programlisting>[Unit] + <para>This will execute <command>/bin/echo</command> + with five arguments: <literal>/</literal>, + <literal>>/dev/null</literal>, + <literal>&</literal>, <literal>;</literal>, and + <literal>/bin/ls</literal>.</para> + + <table> + <title>C escapes supported in command lines and environment variables</title> + <tgroup cols='2'> + <colspec colname='escape' /> + <colspec colname='meaning' /> + <thead> + <row> + <entry>Literal</entry> + <entry>Actual value</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>\a</literal></entry> + <entry>bell</entry> + </row> + <row> + <entry><literal>\b</literal></entry> + <entry>backspace</entry> + </row> + <row> + <entry><literal>\f</literal></entry> + <entry>form feed</entry> + </row> + <row> + <entry><literal>\n</literal></entry> + <entry>newline</entry> + </row> + <row> + <entry><literal>\r</literal></entry> + <entry>carriage return</entry> + </row> + <row> + <entry><literal>\t</literal></entry> + <entry>tab</entry> + </row> + <row> + <entry><literal>\v</literal></entry> + <entry>vertical tab</entry> + </row> + <row> + <entry><literal>\\</literal></entry> + <entry>backslash</entry> + </row> + <row> + <entry><literal>\"</literal></entry> + <entry>double quotation mark</entry> + </row> + <row> + <entry><literal>\'</literal></entry> + <entry>single quotation mark</entry> + </row> + <row> + <entry><literal>\s</literal></entry> + <entry>space</entry> + </row> + <row> + <entry><literal>\x<replaceable>xx</replaceable></literal></entry> + <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry> + </row> + <row> + <entry><literal>\<replaceable>nnn</replaceable></literal></entry> + <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Simple service</title> + + <para>The following unit file creates a service that will + execute <filename>/usr/sbin/foo-daemon</filename>. Since no + <varname>Type=</varname> is specified, the default + <varname>Type=</varname><option>simple</option> will be assumed. + systemd will assume the unit to be started immediately after the + program has begun executing.</para> + + <programlisting>[Unit] Description=Foo [Service] @@ -1382,50 +1094,42 @@ ExecStart=/usr/sbin/foo-daemon [Install] WantedBy=multi-user.target</programlisting> - <para>Note that systemd assumes here that the - process started by systemd will continue - running until the service terminates. If the - program daemonizes itself (i.e. forks), please - use - <varname>Type=</varname><option>forking</option> - instead.</para> - - <para>Since no <varname>ExecStop=</varname> was - specified, systemd will send SIGTERM to all - processes started from this service, and after - a timeout also SIGKILL. This behavior can be - modified, see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - - <para>Note that this unit type does not include - any type of notification when a service has - completed initialization. For this, you should - use other unit types, such as - <varname>Type=</varname><option>notify</option> - if the service understands systemd's - notification protocol, - <varname>Type=</varname><option>forking</option> - if the service can background itself or - <varname>Type=</varname><option>dbus</option> - if the unit acquires a DBus name once - initialization is complete. See below.</para> - </example> - - <example> - <title>Oneshot service</title> - - <para>Sometimes units should just execute an - action without keeping active processes, such - as a filesystem check or a cleanup action on - boot. For this, - <varname>Type=</varname><option>oneshot</option> - exists. Units of this type will wait until the - process specified terminates and then fall back - to being inactive. The following unit will - perform a clenaup action:</para> - - <programlisting>[Unit] + <para>Note that systemd assumes here that the process started by + systemd will continue running until the service terminates. If + the program daemonizes itself (i.e. forks), please use + <varname>Type=</varname><option>forking</option> instead.</para> + + <para>Since no <varname>ExecStop=</varname> was specified, + systemd will send SIGTERM to all processes started from this + service, and after a timeout also SIGKILL. This behavior can be + modified, see + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + + <para>Note that this unit type does not include any type of + notification when a service has completed initialization. For + this, you should use other unit types, such as + <varname>Type=</varname><option>notify</option> if the service + understands systemd's notification protocol, + <varname>Type=</varname><option>forking</option> if the service + can background itself or + <varname>Type=</varname><option>dbus</option> if the unit + acquires a DBus name once initialization is complete. See + below.</para> + </example> + + <example> + <title>Oneshot service</title> + + <para>Sometimes units should just execute an action without + keeping active processes, such as a filesystem check or a + cleanup action on boot. For this, + <varname>Type=</varname><option>oneshot</option> exists. Units + of this type will wait until the process specified terminates + and then fall back to being inactive. The following unit will + perform a clenaup action:</para> + + <programlisting>[Unit] Description=Cleanup old Foo data [Service] @@ -1435,60 +1139,50 @@ ExecStart=/usr/sbin/foo-cleanup [Install] WantedBy=multi-user.target</programlisting> - <para>Note that systemd will consider the unit - to be in the state 'starting' until the program - has terminated, so ordered dependencies will - wait for the program to finish before starting - themselves. The unit will revert to the - 'inactive' state after the execution is - done, never reaching the 'active' state. That - means another request to start the unit will - perform the action again.</para> - - <para><varname>Type=</varname><option>oneshot</option> - are the only service units that may have more - than one <varname>ExecStart=</varname> - specified. They will be executed in order until - either they are all successful or one of them - fails.</para> - </example> - - <example> - <title>Stoppable oneshot service</title> - - <para>Similarly to the oneshot services, there - are sometimes units that need to execute a - program to set up something and then execute - another to shut it down, but no process remains - active while they are considered - 'started'. Network configuration can sometimes - fall into this category. Another use case is if - a oneshot service shall not be executed a - each time when they are pulled in as a - dependency, but only the first time.</para> - - <para>For this, systemd knows the setting - <varname>RemainAfterExit=</varname><option>yes</option>, - which causes systemd to consider the unit to be - active if the start action exited successfully. - This directive can be used with all types, but - is most useful with - <varname>Type=</varname><option>oneshot</option> - and - <varname>Type=</varname><option>simple</option>. - With - <varname>Type=</varname><option>oneshot</option> - systemd waits until the start action has - completed before it considers the unit to be - active, so dependencies start only after the - start action has succeeded. With - <varname>Type=</varname><option>simple</option> - dependencies will start immediately after the - start action has been dispatched. The following - unit provides an example for a simple static - firewall.</para> - - <programlisting>[Unit] + <para>Note that systemd will consider the unit to be in the + state 'starting' until the program has terminated, so ordered + dependencies will wait for the program to finish before starting + themselves. The unit will revert to the 'inactive' state after + the execution is done, never reaching the 'active' state. That + means another request to start the unit will perform the action + again.</para> + + <para><varname>Type=</varname><option>oneshot</option> are the + only service units that may have more than one + <varname>ExecStart=</varname> specified. They will be executed + in order until either they are all successful or one of them + fails.</para> + </example> + + <example> + <title>Stoppable oneshot service</title> + + <para>Similarly to the oneshot services, there are sometimes + units that need to execute a program to set up something and + then execute another to shut it down, but no process remains + active while they are considered 'started'. Network + configuration can sometimes fall into this category. Another use + case is if a oneshot service shall not be executed a each time + when they are pulled in as a dependency, but only the first + time.</para> + + <para>For this, systemd knows the setting + <varname>RemainAfterExit=</varname><option>yes</option>, which + causes systemd to consider the unit to be active if the start + action exited successfully. This directive can be used with all + types, but is most useful with + <varname>Type=</varname><option>oneshot</option> and + <varname>Type=</varname><option>simple</option>. With + <varname>Type=</varname><option>oneshot</option> systemd waits + until the start action has completed before it considers the + unit to be active, so dependencies start only after the start + action has succeeded. With + <varname>Type=</varname><option>simple</option> dependencies + will start immediately after the start action has been + dispatched. The following unit provides an example for a simple + static firewall.</para> + + <programlisting>[Unit] Description=Simple firewall [Service] @@ -1500,56 +1194,46 @@ ExecStop=/usr/local/sbin/simple-firewall-stop [Install] WantedBy=multi-user.target</programlisting> - <para>Since the unit is considered to be - running after the start action has exited, - invoking <command>systemctl start</command> on - that unit again will cause no action to be - taken.</para> - </example> - - <example> - <title>Traditional forking services</title> - - <para>Many traditional daemons/services - background (i.e. fork, daemonize) themselves - when starting. Set - <varname>Type=</varname><option>forking</option> - in the service's unit file to support this mode - of operation. systemd will consider the service - to be in the process of initialization while - the original program is still running. Once - it exits successfully and at least a process - remains (and - <varname>RemainAfterExit=</varname><option>no</option>), - the service is considered started.</para> - - <para>Often a traditional daemon only consists - of one process. Therefore, if only one process - is left after the original process terminates, - systemd will consider that process the main - process of the service. In that case, the - <varname>$MAINPID</varname> variable will be - available in <varname>ExecReload=</varname>, - <varname>ExecStop=</varname>, etc.</para> - - <para>In case more than one process remains, - systemd will be unable to determine the main - process, so it will not assume there is one. - In that case, <varname>$MAINPID</varname> will - not expand to anything. However, if the process - decides to write a traditional PID file, - systemd will be able to read the main PID from - there. Please set <varname>PIDFile=</varname> - accordingly. Note that the daemon should write - that file before finishing with its - initialization, otherwise systemd might try to - read the file before it exists.</para> - - <para>The following example shows a simple - daemon that forks and just starts one process - in the background:</para> - - <programlisting>[Unit] + <para>Since the unit is considered to be running after the start + action has exited, invoking <command>systemctl start</command> + on that unit again will cause no action to be taken.</para> + </example> + + <example> + <title>Traditional forking services</title> + + <para>Many traditional daemons/services background (i.e. fork, + daemonize) themselves when starting. Set + <varname>Type=</varname><option>forking</option> in the + service's unit file to support this mode of operation. systemd + will consider the service to be in the process of initialization + while the original program is still running. Once it exits + successfully and at least a process remains (and + <varname>RemainAfterExit=</varname><option>no</option>), the + service is considered started.</para> + + <para>Often a traditional daemon only consists of one process. + Therefore, if only one process is left after the original + process terminates, systemd will consider that process the main + process of the service. In that case, the + <varname>$MAINPID</varname> variable will be available in + <varname>ExecReload=</varname>, <varname>ExecStop=</varname>, + etc.</para> + + <para>In case more than one process remains, systemd will be + unable to determine the main process, so it will not assume + there is one. In that case, <varname>$MAINPID</varname> will not + expand to anything. However, if the process decides to write a + traditional PID file, systemd will be able to read the main PID + from there. Please set <varname>PIDFile=</varname> accordingly. + Note that the daemon should write that file before finishing + with its initialization, otherwise systemd might try to read the + file before it exists.</para> + + <para>The following example shows a simple daemon that forks and + just starts one process in the background:</para> + + <programlisting>[Unit] Description=Some simple daemon [Service] @@ -1559,26 +1243,23 @@ ExecStart=/usr/sbin/my-simple-daemon -d [Install] WantedBy=multi-user.target</programlisting> - <para>Please see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on how you can influence the way - systemd terminates the service.</para> - </example> - - <example> - <title>DBus services</title> - - <para>For services that acquire a name on the - DBus system bus, use - <varname>Type=</varname><option>dbus</option> - and set <varname>BusName=</varname> - accordingly. The service should not fork - (daemonize). systemd will consider the service - to be initialized once the name has been - acquired on the system bus. The following - example shows a typical DBus service:</para> - - <programlisting>[Unit] + <para>Please see + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on how you can influence the way systemd terminates + the service.</para> + </example> + + <example> + <title>DBus services</title> + + <para>For services that acquire a name on the DBus system bus, + use <varname>Type=</varname><option>dbus</option> and set + <varname>BusName=</varname> accordingly. The service should not + fork (daemonize). systemd will consider the service to be + initialized once the name has been acquired on the system bus. + The following example shows a typical DBus service:</para> + + <programlisting>[Unit] Description=Simple DBus service [Service] @@ -1589,43 +1270,38 @@ ExecStart=/usr/sbin/simple-dbus-service [Install] WantedBy=multi-user.target</programlisting> - <para>For <emphasis>bus-activatable</emphasis> - services, don't include a - <literal>[Install]</literal> section in the - systemd service file, but use the - <varname>SystemdService=</varname> option in - the corresponding DBus service file, for - example - (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para> + <para>For <emphasis>bus-activatable</emphasis> services, don't + include a <literal>[Install]</literal> section in the systemd + service file, but use the <varname>SystemdService=</varname> + option in the corresponding DBus service file, for example + (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para> - <programlisting>[D-BUS Service] + <programlisting>[D-BUS Service] Name=org.example.simple-dbus-service Exec=/usr/sbin/simple-dbus-service User=root SystemdService=simple-dbus-service.service</programlisting> - <para>Please see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on how you can influence the way - systemd terminates the service.</para> - </example> - - <example> - <title>Services that notify systemd about their initialization</title> - - <para><varname>Type=</varname><option>simple</option> - services are really easy to write, but have the - major disadvantage of systemd not being able to - tell when initialization of the given service - is complete. For this reason, systemd supports - a simple notification protocol that allows - daemons to make systemd aware that they are - done initializing. Use - <varname>Type=</varname><option>notify</option> - for this. A typical service file for such a - daemon would look like this:</para> - - <programlisting>[Unit] + <para>Please see + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on how you can influence the way systemd terminates + the service.</para> + </example> + + <example> + <title>Services that notify systemd about their initialization</title> + + <para><varname>Type=</varname><option>simple</option> services + are really easy to write, but have the major disadvantage of + systemd not being able to tell when initialization of the given + service is complete. For this reason, systemd supports a simple + notification protocol that allows daemons to make systemd aware + that they are done initializing. Use + <varname>Type=</varname><option>notify</option> for this. A + typical service file for such a daemon would look like + this:</para> + + <programlisting>[Unit] Description=Simple notifying service [Service] @@ -1635,35 +1311,32 @@ ExecStart=/usr/sbin/simple-notifying-service [Install] WantedBy=multi-user.target</programlisting> - <para>Note that the daemon has to support - systemd's notification protocol, else systemd - will think the service hasn't started yet and - kill it after a timeout. For an example of how - to update daemons to support this protocol - transparently, take a look at - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. - systemd will consider the unit to be in the - 'starting' state until a readiness notification - has arrived.</para> - - <para>Please see - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details on how you can influence the way - systemd terminates the service.</para> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <para>Note that the daemon has to support systemd's notification + protocol, else systemd will think the service hasn't started yet + and kill it after a timeout. For an example of how to update + daemons to support this protocol transparently, take a look at + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + systemd will consider the unit to be in the 'starting' state + until a readiness notification has arrived.</para> + + <para>Please see + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details on how you can influence the way systemd terminates + the service.</para> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.snapshot.xml b/man/systemd.snapshot.xml index f08e38e07e..e2d67391df 100644 --- a/man/systemd.snapshot.xml +++ b/man/systemd.snapshot.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,66 +23,62 @@ --> <refentry id="systemd.snapshot"> - <refentryinfo> - <title>systemd.snapshot</title> - <productname>systemd</productname> + <refentryinfo> + <title>systemd.snapshot</title> + <productname>systemd</productname> - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> - <refmeta> - <refentrytitle>systemd.snapshot</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> + <refmeta> + <refentrytitle>systemd.snapshot</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> - <refnamediv> - <refname>systemd.snapshot</refname> - <refpurpose>Snapshot unit configuration</refpurpose> - </refnamediv> + <refnamediv> + <refname>systemd.snapshot</refname> + <refpurpose>Snapshot unit configuration</refpurpose> + </refnamediv> - <refsynopsisdiv> - <para><filename><replaceable>snapshot</replaceable>.snapshot</filename></para> - </refsynopsisdiv> + <refsynopsisdiv> + <para><filename><replaceable>snapshot</replaceable>.snapshot</filename></para> + </refsynopsisdiv> - <refsect1> - <title>Description</title> + <refsect1> + <title>Description</title> - <para>Snapshot units are not configured via unit - configuration files. Nonetheless they are named - similar to filenames. A unit whose name ends in - <literal>.snapshot</literal> refers to a dynamic - snapshot of the systemd runtime state.</para> + <para>Snapshot units are not configured via unit configuration + files. Nonetheless they are named similar to filenames. A unit + whose name ends in <literal>.snapshot</literal> refers to a + dynamic snapshot of the systemd runtime state.</para> - <para>Snapshots are not configured on disk but created - dynamically via <command>systemctl snapshot</command> - (see - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for details) or an equivalent command. When created, - they will automatically get dependencies on the - currently activated units. They act as saved - runtime state of the systemd manager. Later on, the - user may choose to return to the saved state via - <command>systemctl isolate</command>. They are - useful to roll back to a defined state after - temporarily starting/stopping services or - similar.</para> - </refsect1> + <para>Snapshots are not configured on disk but created dynamically + via <command>systemctl snapshot</command> (see + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details) or an equivalent command. When created, they will + automatically get dependencies on the currently activated units. + They act as saved runtime state of the systemd manager. Later on, + the user may choose to return to the saved state via + <command>systemctl isolate</command>. They are useful to roll back + to a defined state after temporarily starting/stopping services or + similar.</para> + </refsect1> - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 57f769f23a..c8b483c412 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,914 +23,733 @@ --> <refentry id="systemd.socket"> - <refentryinfo> - <title>systemd.socket</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.socket</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.socket</refname> - <refpurpose>Socket unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>socket</replaceable>.socket</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.socket</literal> encodes information about - an IPC or network socket or a file system FIFO - controlled and supervised by systemd, for socket-based - activation.</para> - - <para>This man page lists the configuration options - specific to this unit type. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the common options of all unit configuration - files. The common configuration items are configured - in the generic [Unit] and [Install] sections. The - socket specific configuration options are configured - in the [Socket] section.</para> - - <para>Additional options are listed in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the execution environment the - <option>ExecStartPre=</option>, - <option>ExecStartPost=</option>, - <option>ExecStopPre=</option> and - <option>ExecStopPost=</option> commands are executed - in, and in - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the way the processes are terminated, and - in - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which configure resource control settings for the - processes of the socket.</para> - - <para>For each socket file, a matching service file - must exist, describing the service to start on - incoming traffic on the socket (see - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about .service files). The name - of the .service unit is by default the same as the - name of the .socket unit, but can be altered with the - <option>Service=</option> option described below. - Depending on the setting of the <option>Accept=</option> - option described below, this .service unit must either - be named like the .socket unit, but with the suffix - replaced, unless overridden with - <option>Service=</option>; or it must be a template - unit named the same way. Example: a socket file - <filename>foo.socket</filename> needs a matching - service <filename>foo.service</filename> if - <option>Accept=false</option> is set. If - <option>Accept=true</option> is set, a service - template file <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>Socket units will have a - <varname>Before=</varname> dependency on the service - which they trigger added implicitly. No implicit - <varname>WantedBy=</varname> or - <varname>RequiredBy=</varname> dependency from the - socket to the service is added. This means that the - service may be started without the socket, in which - case it must be able to open sockets by itself. To - prevent this, an explicit <varname>Requires=</varname> - dependency may be added.</para> - - <para>Socket units may be used to implement on-demand - starting of services, as well as parallelized starting - of services. See the blog stories linked at the end - for an introduction.</para> - - <para>Note that the daemon software configured for - socket activation with socket units needs to be able - to accept sockets from systemd, either via systemd's - native socket passing interface (see - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details) or via the traditional - <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style - socket passing (i.e. sockets passed in via standard input and - output, using <varname>StandardInput=socket</varname> - in the service file).</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>Socket files must include a [Socket] section, - which carries information about the socket or FIFO it - supervises. A number of options that may be used in - this section are shared with other unit types. These - options are documented in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The - options specific to the [Socket] section of socket - units are the following:</para> - - <variablelist class='unit-directives'> - <varlistentry> - <term><varname>ListenStream=</varname></term> - <term><varname>ListenDatagram=</varname></term> - <term><varname>ListenSequentialPacket=</varname></term> - <listitem><para>Specifies an address - to listen on for a stream - (<constant>SOCK_STREAM</constant>), datagram (<constant>SOCK_DGRAM</constant>), - or sequential packet - (<constant>SOCK_SEQPACKET</constant>) socket, respectively. The address - can be written in various formats:</para> - - <para>If the address starts with a - slash (<literal>/</literal>), it is read as file system - socket in the <constant>AF_UNIX</constant> socket - family.</para> - - <para>If the address starts with an at - symbol (<literal>@</literal>), it is read as abstract - namespace socket in the - <constant>AF_UNIX</constant> - family. The <literal>@</literal> is - replaced with a - <constant>NUL</constant> character - before binding. For details, see - <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - - <para>If the address string is a - single number, it is read as port - number to listen on via - IPv6. Depending on the value of - <varname>BindIPv6Only=</varname> (see below) this - might result in the service being - available via both IPv6 and IPv4 (default) or - just via IPv6. - </para> - - <para>If the address string is a - string in the format v.w.x.y:z, it is - read as IPv4 specifier for listening - on an address v.w.x.y on a port - z.</para> - - <para>If the address string is a - string in the format [x]:y, it is read - as IPv6 address x on a port y. Note - that this might make the service - available via IPv4, too, depending on - the <varname>BindIPv6Only=</varname> - setting (see below). - </para> - - <para>Note that <constant>SOCK_SEQPACKET</constant> - (i.e. <varname>ListenSequentialPacket=</varname>) - is only available for <constant>AF_UNIX</constant> - sockets. <constant>SOCK_STREAM</constant> - (i.e. <varname>ListenStream=</varname>) - when used for IP sockets refers to TCP - sockets, <constant>SOCK_DGRAM</constant> - (i.e. <varname>ListenDatagram=</varname>) - to UDP.</para> - - <para>These options may be specified - more than once in which case incoming - traffic on any of the sockets will - trigger service activation, and all - listed sockets will be passed to the - service, regardless of whether there is - incoming traffic on them or not. If - the empty string is assigned to any of - these options, the list of addresses - to listen on is reset, all prior uses - of any of these options will have no - effect.</para> - - <para>It is also possible to have more - than one socket unit for the same - service when using - <varname>Service=</varname>, and the - service will receive all the sockets - configured in all the socket units. - Sockets configured in one unit are - passed in the order of configuration, - but no ordering between socket units - is specified.</para> - - <para>If an IP address is used here, - it is often desirable to listen on it - before the interface it is configured - on is up and running, and even - regardless of whether it will be up and - running at any point. To deal with this, - it is recommended to set the - <varname>FreeBind=</varname> option - described below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ListenFIFO=</varname></term> - <listitem><para>Specifies a file - system FIFO to listen on. This expects - an absolute file system path as - argument. Behavior otherwise is very - similar to the - <varname>ListenDatagram=</varname> - directive above.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ListenSpecial=</varname></term> - <listitem><para>Specifies a special - file in the file system to listen - on. This expects an absolute file - system path as argument. Behavior - otherwise is very similar to the - <varname>ListenFIFO=</varname> - directive above. Use this to open - character device nodes as well as - special files in - <filename>/proc</filename> and - <filename>/sys</filename>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ListenNetlink=</varname></term> - <listitem><para>Specifies a Netlink - family to create a socket for to - listen on. This expects a short string - referring to the <constant>AF_NETLINK</constant> family - name (such as <varname>audit</varname> - or <varname>kobject-uevent</varname>) - as argument, optionally suffixed by a - whitespace followed by a multicast - group integer. Behavior otherwise is - very similar to the - <varname>ListenDatagram=</varname> - directive above.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ListenMessageQueue=</varname></term> - <listitem><para>Specifies a POSIX - message queue name to listen on. This - expects a valid message queue name - (i.e. beginning with /). Behavior - otherwise is very similar to the - <varname>ListenFIFO=</varname> - directive above. On Linux message - queue descriptors are actually file - descriptors and can be inherited - between processes.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>BindIPv6Only=</varname></term> - <listitem><para>Takes a one of - <option>default</option>, - <option>both</option> or - <option>ipv6-only</option>. Controls - the IPV6_V6ONLY socket option (see - <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details). If - <option>both</option>, IPv6 sockets - bound will be accessible via both IPv4 - and IPv6. If - <option>ipv6-only</option>, they will - be accessible via IPv6 only. If - <option>default</option> (which is the - default, surprise!), the system wide - default setting is used, as controlled - by - <filename>/proc/sys/net/ipv6/bindv6only</filename>, - which in turn defaults to the - equivalent of - <option>both</option>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>Backlog=</varname></term> - <listitem><para>Takes an unsigned - integer argument. Specifies the number - of connections to queue that have not - been accepted yet. This setting - matters only for stream and sequential - packet sockets. See - <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. Defaults to SOMAXCONN - (128).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>BindToDevice=</varname></term> - <listitem><para>Specifies a network - interface name to bind this socket - to. If set, traffic will only be - accepted from the specified network - interfaces. This controls the - SO_BINDTODEVICE socket option (see - <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details). If this option is used, - an automatic dependency from this - socket unit on the network interface - device unit - (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> - is created.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SocketUser=</varname></term> - <term><varname>SocketGroup=</varname></term> - - <listitem><para>Takes a UNIX - user/group name. When specified, - all AF_UNIX sockets and FIFO nodes in - the file system are owned by the - specified user and group. If unset - (the default), the nodes are owned by - the root user/group (if run in system - context) or the invoking user/group - (if run in user context). If only a - user is specified but no group, then - the group is derived from the user's - default group.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SocketMode=</varname></term> - <listitem><para>If listening on a file - system socket or FIFO, this option - specifies the file system access mode - used when creating the file - node. Takes an access mode in octal - notation. Defaults to - 0666.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DirectoryMode=</varname></term> - <listitem><para>If listening on a file - system socket or FIFO, the parent - directories are automatically created - if needed. This option specifies the - file system access mode used when - creating these directories. Takes an - access mode in octal - notation. Defaults to - 0755.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Accept=</varname></term> - <listitem><para>Takes a boolean - argument. If true, a service instance - is spawned for each incoming - connection and only the connection - socket is passed to it. If false, all - listening sockets themselves are - passed to the started service unit, - and only one service unit is spawned - for all connections (also see - above). This value is ignored for - datagram sockets and FIFOs where a - single service unit unconditionally - handles all incoming traffic. Defaults - to <option>false</option>. For - performance reasons, it is recommended - to write new daemons only in a way - that is suitable for - <option>Accept=false</option>. A - daemon listening on an <constant>AF_UNIX</constant> socket - may, but does not need to, call - <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry> - on the received socket before - exiting. However, it must not unlink - the socket from a file system. It - should not invoke - <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry> - on sockets it got with - <varname>Accept=false</varname>, but - it may do so for sockets it got with - <varname>Accept=true</varname> set. - Setting <varname>Accept=true</varname> - is mostly useful to allow daemons - designed for usage with - <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> - to work unmodified with systemd socket - activation.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>MaxConnections=</varname></term> - <listitem><para>The maximum number of - connections to simultaneously run - services instances for, when - <option>Accept=true</option> is - set. If more concurrent connections - are coming in, they will be refused - until at least one existing connection - is terminated. This setting has no - effect on sockets configured with - <option>Accept=false</option> or datagram - sockets. Defaults to - 64.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>KeepAlive=</varname></term> - <listitem><para>Takes a boolean - argument. If true, the TCP/IP stack - will send a keep alive message after - 2h (depending on the configuration of - <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>) - for all TCP streams accepted on this - socket. This controls the SO_KEEPALIVE - socket option (see - <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> - and the <ulink - url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP - Keepalive HOWTO</ulink> for details.) - Defaults to - <option>false</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>KeepAliveTimeSec=</varname></term> - <listitem><para>Takes time (in seconds) as argument . The connection needs to remain - idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE - socket option (see - <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> - and the <ulink - url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP - Keepalive HOWTO</ulink> for details.) - Defaults value is 7200 seconds (2 hours).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>KeepAliveIntervalSec=</varname></term> - <listitem><para>Takes time (in seconds) as argument between individual keepalive probes, - if the socket option SO_KEEPALIVE has been set on this socket seconds as argument. - This controls the TCP_KEEPINTVL socket option (see - <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> - and the <ulink - url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP - Keepalive HOWTO</ulink> for details.) - Defaults value is 75 seconds.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>KeepAliveProbes=</varname></term> - <listitem><para>Takes integer as argument. It's the number of unacknowledged probes to - send before considering the connection dead and notifying the application layer. - This controls the TCP_KEEPCNT socket option (see - <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> - and the <ulink - url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP - Keepalive HOWTO</ulink> for details.) - Defaults value is 9.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>NoDelay=</varname></term> - <listitem><para>Takes a boolean - argument. TCP Nagle's algorithm works by combining a number of - small outgoing messages, and sending them all at once. - This controls the TCP_NODELAY socket option (see - <citerefentry><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry> - Defaults to - <option>false</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Priority=</varname></term> - <listitem><para>Takes an integer - argument controlling the priority for - all traffic sent from this - socket. This controls the SO_PRIORITY - socket option (see - <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details.).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DeferAcceptSec=</varname></term> - - <listitem><para>Takes time (in - seconds) as argument. If set, the - listening process will be awakened - only when data arrives on the socket, - and not immediately when connection is - established. When this option is set, - the - <constant>TCP_DEFER_ACCEPT</constant> - socket option will be used (see - <citerefentry><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>), - and the kernel will ignore initial ACK - packets without any data. The argument - specifies the approximate amount of - time the kernel should wait for - incoming data before falling back to - the normal behaviour of honouring - empty ACK packets. This option is - beneficial for protocols where the - client sends the data first (e.g. - HTTP, in contrast to SMTP), because - the server process will not be woken - up unnecessarily before it can take - any action. - </para> - - <para>If the client also uses the - <constant>TCP_DEFER_ACCEPT</constant> - option, the latency of the initial - connection may be reduced, because the - kernel will send data in the final - packet establishing the connection - (the third packet in the "three-way - handshake").</para> - - <para>Disabled by default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>ReceiveBuffer=</varname></term> - <term><varname>SendBuffer=</varname></term> - <listitem><para>Takes an integer - argument controlling the receive or - send buffer sizes of this socket, - respectively. This controls the - SO_RCVBUF and SO_SNDBUF socket options - (see - <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details.). The usual suffixes K, - M, G are supported and are understood - to the base of 1024.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>IPTOS=</varname></term> - <listitem><para>Takes an integer - argument controlling the IP - Type-Of-Service field for packets - generated from this socket. This - controls the IP_TOS socket option (see - <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details.). Either a numeric string - or one of <option>low-delay</option>, - <option>throughput</option>, - <option>reliability</option> or - <option>low-cost</option> may be - specified.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>IPTTL=</varname></term> - <listitem><para>Takes an integer - argument controlling the IPv4 - Time-To-Live/IPv6 Hop-Count field for - packets generated from this - socket. This sets the - IP_TTL/IPV6_UNICAST_HOPS socket - options (see - <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details.)</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Mark=</varname></term> - <listitem><para>Takes an integer - value. Controls the firewall mark of - packets generated by this socket. This - can be used in the firewall logic to - filter packets from this socket. This - sets the SO_MARK socket option. See - <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ReusePort=</varname></term> - <listitem><para>Takes a boolean - value. If true, allows multiple <citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s - to this TCP or UDP port. This - controls the SO_REUSEPORT socket - option. See - <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SmackLabel=</varname></term> - <term><varname>SmackLabelIPIn=</varname></term> - <term><varname>SmackLabelIPOut=</varname></term> - <listitem><para>Takes a string - value. Controls the extended - attributes - <literal>security.SMACK64</literal>, - <literal>security.SMACK64IPIN</literal> - and - <literal>security.SMACK64IPOUT</literal>, - respectively, i.e. the security label - of the FIFO, or the security label for - the incoming or outgoing connections - of the socket, respectively. See - <ulink - url="https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt</ulink> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SELinuxContextFromNet=</varname></term> - <listitem><para>Takes a boolean - argument. When true, systemd will attempt - to figure out the SELinux label used - for the instantiated service from the - information handed by the peer over the - network. Note that only the security - level is used from the information - provided by the peer. Other parts of - the resulting SELinux context originate - from either the target binary that is - effectively triggered by socket unit - or from the value of the - <varname>SELinuxContext=</varname> - option. This configuration option only - affects sockets with - <varname>Accept=</varname> mode set to - <literal>true</literal>. Also note that - this option is useful only when - MLS/MCS SELinux policy is - deployed. Defaults to - <literal>false</literal>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PipeSize=</varname></term> - <listitem><para>Takes a size in - bytes. Controls the pipe buffer size - of FIFOs configured in this socket - unit. See - <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. The usual suffixes K, M, - G are supported and are understood to - the base of 1024.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>MessageQueueMaxMessages=</varname>, - <varname>MessageQueueMessageSize=</varname></term> - <listitem><para>These two settings - take integer values and control the - mq_maxmsg field or the mq_msgsize field, respectively, when - creating the message queue. Note that - either none or both of these variables - need to be set. See - <citerefentry><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for details.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>FreeBind=</varname></term> - <listitem><para>Takes a boolean - value. Controls whether the socket can - be bound to non-local IP - addresses. This is useful to configure - sockets listening on specific IP - addresses before those IP addresses - are successfully configured on a - network interface. This sets the - IP_FREEBIND socket option. For - robustness reasons it is recommended - to use this option whenever you bind a - socket to a specific IP - address. Defaults to <option>false</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Transparent=</varname></term> - <listitem><para>Takes a boolean - value. Controls the IP_TRANSPARENT - socket option. Defaults to - <option>false</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Broadcast=</varname></term> - <listitem><para>Takes a boolean - value. This controls the SO_BROADCAST - socket option, which allows broadcast - datagrams to be sent from this - socket. Defaults to - <option>false</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PassCredentials=</varname></term> - <listitem><para>Takes a boolean - value. This controls the SO_PASSCRED - socket option, which allows <constant>AF_UNIX</constant> sockets to - receive the credentials of the sending - process in an ancillary message. - Defaults to - <option>false</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PassSecurity=</varname></term> - <listitem><para>Takes a boolean - value. This controls the SO_PASSSEC - socket option, which allows <constant>AF_UNIX</constant> - sockets to receive the security - context of the sending process in an - ancillary message. Defaults to - <option>false</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TCPCongestion=</varname></term> - <listitem><para>Takes a string - value. Controls the TCP congestion - algorithm used by this socket. Should - be one of "westwood", "veno", "cubic", - "lp" or any other available algorithm - supported by the IP stack. This - setting applies only to stream - sockets.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ExecStartPre=</varname></term> - <term><varname>ExecStartPost=</varname></term> - <listitem><para>Takes one or more - command lines, which are executed - before or after the listening - sockets/FIFOs are created and - bound, respectively. The first token of the command - line must be an absolute filename, - then followed by arguments for the - process. Multiple command lines may be - specified following the same scheme as - used for - <varname>ExecStartPre=</varname> of - service unit files.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ExecStopPre=</varname></term> - <term><varname>ExecStopPost=</varname></term> - <listitem><para>Additional commands - that are executed before or after - the listening sockets/FIFOs are closed - and removed, respectively. Multiple command lines - may be specified following the same - scheme as used for - <varname>ExecStartPre=</varname> of - service unit files.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TimeoutSec=</varname></term> - <listitem><para>Configures the time to - wait for the commands specified in - <varname>ExecStartPre=</varname>, - <varname>ExecStartPost=</varname>, - <varname>ExecStopPre=</varname> and - <varname>ExecStopPost=</varname> to - finish. If a command does not exit - within the configured time, the socket - will be considered failed and be shut - down again. All commands still running - will be terminated forcibly via - <constant>SIGTERM</constant>, and after another delay of - this time with <constant>SIGKILL</constant>. (See - <option>KillMode=</option> in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) - Takes a unit-less value in seconds, or - a time span value such as "5min - 20s". Pass <literal>0</literal> to disable the timeout - logic. Defaults to <varname>DefaultTimeoutStartSec=</varname> from the - manager configuration file - (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Service=</varname></term> - <listitem><para>Specifies the service - unit name to activate on incoming - traffic. This setting is only allowed - for sockets with - <varname>Accept=no</varname>. It - defaults to the service that bears the - same name as the socket (with the - suffix replaced). In most cases, it - should not be necessary to use this - option.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RemoveOnStop=</varname></term> - <listitem><para>Takes a boolean - argument. If enabled, any file nodes - created by this socket unit are - removed when it is stopped. This - applies to AF_UNIX sockets in the file - system, POSIX message queues, FIFOs, - as well as any symlinks to - them configured with - <varname>Symlinks=</varname>. Normally, - it should not be necessary to use this - option, and is not recommended as - services might continue to run after - the socket unit has been terminated - and it should still be possible to - communicate with them via their file - system node. Defaults to - off.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Symlinks=</varname></term> - <listitem><para>Takes a list of file - system paths. The specified paths will - be created as symlinks to the AF_UNIX - socket path or FIFO path of this - socket unit. If this setting is used, - only one AF_UNIX socket in the file - system or one FIFO may be configured - for the socket unit. Use this option - to manage one or more symlinked alias - names for a socket, binding their - lifecycle together. Defaults to the - empty list.</para></listitem> - </varlistentry> - - </variablelist> - - <para>Check - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more settings.</para> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - - <para> - For more extensive descriptions see the "systemd for Developers" series: - <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>, - <ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>, - <ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>, - <ulink url="http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>. - </para> - </refsect1> + <refentryinfo> + <title>systemd.socket</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.socket</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.socket</refname> + <refpurpose>Socket unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>socket</replaceable>.socket</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.socket</literal> encodes information about an IPC or + network socket or a file system FIFO controlled and supervised by + systemd, for socket-based activation.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. The socket specific configuration options are + configured in the [Socket] section.</para> + + <para>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the + <option>ExecStartPre=</option>, <option>ExecStartPost=</option>, + <option>ExecStopPre=</option> and <option>ExecStopPost=</option> + commands are executed in, and in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the way the processes are terminated, and in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which configure resource control settings for the processes of the + socket.</para> + + <para>For each socket file, a matching service file must exist, + describing the service to start on incoming traffic on the socket + (see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information about .service files). The name of the + .service unit is by default the same as the name of the .socket + unit, but can be altered with the <option>Service=</option> option + described below. Depending on the setting of the + <option>Accept=</option> option described below, this .service + unit must either be named like the .socket unit, but with the + suffix replaced, unless overridden with <option>Service=</option>; + or it must be a template unit named the same way. Example: a + socket file <filename>foo.socket</filename> needs a matching + service <filename>foo.service</filename> if + <option>Accept=false</option> is set. If + <option>Accept=true</option> is set, a service template file + <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>Socket units will have a <varname>Before=</varname> + dependency on the service which they trigger added implicitly. No + implicit <varname>WantedBy=</varname> or + <varname>RequiredBy=</varname> dependency from the socket to the + service is added. This means that the service may be started + without the socket, in which case it must be able to open sockets + by itself. To prevent this, an explicit + <varname>Requires=</varname> dependency may be added.</para> + + <para>Socket units may be used to implement on-demand starting of + services, as well as parallelized starting of services. See the + blog stories linked at the end for an introduction.</para> + + <para>Note that the daemon software configured for socket + activation with socket units needs to be able to accept sockets + from systemd, either via systemd's native socket passing interface + (see + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details) or via the traditional + <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>-style + socket passing (i.e. sockets passed in via standard input and + output, using <varname>StandardInput=socket</varname> in the + service file).</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Socket files must include a [Socket] section, which carries + information about the socket or FIFO it supervises. A number of + options that may be used in this section are shared with other + unit types. These options are documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + The options specific to the [Socket] section of socket units are + the following:</para> + + <variablelist class='unit-directives'> + <varlistentry> + <term><varname>ListenStream=</varname></term> + <term><varname>ListenDatagram=</varname></term> + <term><varname>ListenSequentialPacket=</varname></term> + <listitem><para>Specifies an address to listen on for a stream + (<constant>SOCK_STREAM</constant>), datagram + (<constant>SOCK_DGRAM</constant>), or sequential packet + (<constant>SOCK_SEQPACKET</constant>) socket, respectively. + The address can be written in various formats:</para> + + <para>If the address starts with a slash + (<literal>/</literal>), it is read as file system socket in + the <constant>AF_UNIX</constant> socket family.</para> + + <para>If the address starts with an at symbol + (<literal>@</literal>), it is read as abstract namespace + socket in the <constant>AF_UNIX</constant> family. The + <literal>@</literal> is replaced with a + <constant>NUL</constant> character before binding. For + details, see + <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>If the address string is a single number, it is read as + port number to listen on via IPv6. Depending on the value of + <varname>BindIPv6Only=</varname> (see below) this might result + in the service being available via both IPv6 and IPv4 + (default) or just via IPv6. + </para> + + <para>If the address string is a string in the format + v.w.x.y:z, it is read as IPv4 specifier for listening on an + address v.w.x.y on a port z.</para> + + <para>If the address string is a string in the format [x]:y, + it is read as IPv6 address x on a port y. Note that this might + make the service available via IPv4, too, depending on the + <varname>BindIPv6Only=</varname> setting (see below). + </para> + + <para>Note that <constant>SOCK_SEQPACKET</constant> (i.e. + <varname>ListenSequentialPacket=</varname>) is only available + for <constant>AF_UNIX</constant> sockets. + <constant>SOCK_STREAM</constant> (i.e. + <varname>ListenStream=</varname>) when used for IP sockets + refers to TCP sockets, <constant>SOCK_DGRAM</constant> (i.e. + <varname>ListenDatagram=</varname>) to UDP.</para> + + <para>These options may be specified more than once in which + case incoming traffic on any of the sockets will trigger + service activation, and all listed sockets will be passed to + the service, regardless of whether there is incoming traffic + on them or not. If the empty string is assigned to any of + these options, the list of addresses to listen on is reset, + all prior uses of any of these options will have no + effect.</para> + + <para>It is also possible to have more than one socket unit + for the same service when using <varname>Service=</varname>, + and the service will receive all the sockets configured in all + the socket units. Sockets configured in one unit are passed in + the order of configuration, but no ordering between socket + units is specified.</para> + + <para>If an IP address is used here, it is often desirable to + listen on it before the interface it is configured on is up + and running, and even regardless of whether it will be up and + running at any point. To deal with this, it is recommended to + set the <varname>FreeBind=</varname> option described + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenFIFO=</varname></term> + <listitem><para>Specifies a file system FIFO to listen on. + This expects an absolute file system path as argument. + Behavior otherwise is very similar to the + <varname>ListenDatagram=</varname> directive + above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenSpecial=</varname></term> + <listitem><para>Specifies a special file in the file system to + listen on. This expects an absolute file system path as + argument. Behavior otherwise is very similar to the + <varname>ListenFIFO=</varname> directive above. Use this to + open character device nodes as well as special files in + <filename>/proc</filename> and + <filename>/sys</filename>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenNetlink=</varname></term> + <listitem><para>Specifies a Netlink family to create a socket + for to listen on. This expects a short string referring to the + <constant>AF_NETLINK</constant> family name (such as + <varname>audit</varname> or <varname>kobject-uevent</varname>) + as argument, optionally suffixed by a whitespace followed by a + multicast group integer. Behavior otherwise is very similar to + the <varname>ListenDatagram=</varname> directive + above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ListenMessageQueue=</varname></term> + <listitem><para>Specifies a POSIX message queue name to listen + on. This expects a valid message queue name (i.e. beginning + with /). Behavior otherwise is very similar to the + <varname>ListenFIFO=</varname> directive above. On Linux + message queue descriptors are actually file descriptors and + can be inherited between processes.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BindIPv6Only=</varname></term> + <listitem><para>Takes a one of <option>default</option>, + <option>both</option> or <option>ipv6-only</option>. Controls + the IPV6_V6ONLY socket option (see + <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). If <option>both</option>, IPv6 sockets bound + will be accessible via both IPv4 and IPv6. If + <option>ipv6-only</option>, they will be accessible via IPv6 + only. If <option>default</option> (which is the default, + surprise!), the system wide default setting is used, as + controlled by + <filename>/proc/sys/net/ipv6/bindv6only</filename>, which in + turn defaults to the equivalent of + <option>both</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>Backlog=</varname></term> + <listitem><para>Takes an unsigned integer argument. Specifies + the number of connections to queue that have not been accepted + yet. This setting matters only for stream and sequential + packet sockets. See + <citerefentry><refentrytitle>listen</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. Defaults to SOMAXCONN (128).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BindToDevice=</varname></term> + <listitem><para>Specifies a network interface name to bind + this socket to. If set, traffic will only be accepted from the + specified network interfaces. This controls the + SO_BINDTODEVICE socket option (see + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). If this option is used, an automatic dependency + from this socket unit on the network interface device unit + (<citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> + is created.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SocketUser=</varname></term> + <term><varname>SocketGroup=</varname></term> + + <listitem><para>Takes a UNIX user/group name. When specified, + all AF_UNIX sockets and FIFO nodes in the file system are + owned by the specified user and group. If unset (the default), + the nodes are owned by the root user/group (if run in system + context) or the invoking user/group (if run in user context). + If only a user is specified but no group, then the group is + derived from the user's default group.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SocketMode=</varname></term> + <listitem><para>If listening on a file system socket or FIFO, + this option specifies the file system access mode used when + creating the file node. Takes an access mode in octal + notation. Defaults to 0666.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + <listitem><para>If listening on a file system socket or FIFO, + the parent directories are automatically created if needed. + This option specifies the file system access mode used when + creating these directories. Takes an access mode in octal + notation. Defaults to 0755.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Accept=</varname></term> + <listitem><para>Takes a boolean argument. If true, a service + instance is spawned for each incoming connection and only the + connection socket is passed to it. If false, all listening + sockets themselves are passed to the started service unit, and + only one service unit is spawned for all connections (also see + above). This value is ignored for datagram sockets and FIFOs + where a single service unit unconditionally handles all + incoming traffic. Defaults to <option>false</option>. For + performance reasons, it is recommended to write new daemons + only in a way that is suitable for + <option>Accept=false</option>. A daemon listening on an + <constant>AF_UNIX</constant> socket may, but does not need to, + call + <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry> + on the received socket before exiting. However, it must not + unlink the socket from a file system. It should not invoke + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry> + on sockets it got with <varname>Accept=false</varname>, but it + may do so for sockets it got with + <varname>Accept=true</varname> set. Setting + <varname>Accept=true</varname> is mostly useful to allow + daemons designed for usage with + <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry> + to work unmodified with systemd socket + activation.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MaxConnections=</varname></term> + <listitem><para>The maximum number of connections to + simultaneously run services instances for, when + <option>Accept=true</option> is set. If more concurrent + connections are coming in, they will be refused until at least + one existing connection is terminated. This setting has no + effect on sockets configured with + <option>Accept=false</option> or datagram sockets. Defaults to + 64.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KeepAlive=</varname></term> + <listitem><para>Takes a boolean argument. If true, the TCP/IP + stack will send a keep alive message after 2h (depending on + the configuration of + <filename>/proc/sys/net/ipv4/tcp_keepalive_time</filename>) + for all TCP streams accepted on this socket. This controls the + SO_KEEPALIVE socket option (see + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and the <ulink + url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP + Keepalive HOWTO</ulink> for details.) Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KeepAliveTimeSec=</varname></term> + <listitem><para>Takes time (in seconds) as argument . The connection needs to remain + idle before TCP starts sending keepalive probes. This controls the TCP_KEEPIDLE + socket option (see + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and the <ulink + url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP + Keepalive HOWTO</ulink> for details.) + Defaults value is 7200 seconds (2 hours).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KeepAliveIntervalSec=</varname></term> + <listitem><para>Takes time (in seconds) as argument between + individual keepalive probes, if the socket option SO_KEEPALIVE + has been set on this socket seconds as argument. This controls + the TCP_KEEPINTVL socket option (see + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and the <ulink + url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP + Keepalive HOWTO</ulink> for details.) Defaults value is 75 + seconds.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>KeepAliveProbes=</varname></term> + <listitem><para>Takes integer as argument. It's the number of + unacknowledged probes to send before considering the + connection dead and notifying the application layer. This + controls the TCP_KEEPCNT socket option (see + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and the <ulink + url="http://www.tldp.org/HOWTO/html_single/TCP-Keepalive-HOWTO/">TCP + Keepalive HOWTO</ulink> for details.) Defaults value is + 9.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>NoDelay=</varname></term> + <listitem><para>Takes a boolean argument. TCP Nagle's + algorithm works by combining a number of small outgoing + messages, and sending them all at once. This controls the + TCP_NODELAY socket option (see + <citerefentry><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry> + Defaults to <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Priority=</varname></term> + <listitem><para>Takes an integer argument controlling the + priority for all traffic sent from this socket. This controls + the SO_PRIORITY socket option (see + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DeferAcceptSec=</varname></term> + + <listitem><para>Takes time (in seconds) as argument. If set, + the listening process will be awakened only when data arrives + on the socket, and not immediately when connection is + established. When this option is set, the + <constant>TCP_DEFER_ACCEPT</constant> socket option will be + used (see + <citerefentry><refentrytitle>tcp</refentrytitle><manvolnum>7</manvolnum></citerefentry>), + and the kernel will ignore initial ACK packets without any + data. The argument specifies the approximate amount of time + the kernel should wait for incoming data before falling back + to the normal behaviour of honouring empty ACK packets. This + option is beneficial for protocols where the client sends the + data first (e.g. HTTP, in contrast to SMTP), because the + server process will not be woken up unnecessarily before it + can take any action. + </para> + + <para>If the client also uses the + <constant>TCP_DEFER_ACCEPT</constant> option, the latency of + the initial connection may be reduced, because the kernel will + send data in the final packet establishing the connection (the + third packet in the "three-way handshake").</para> + + <para>Disabled by default.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>ReceiveBuffer=</varname></term> + <term><varname>SendBuffer=</varname></term> + <listitem><para>Takes an integer argument controlling the + receive or send buffer sizes of this socket, respectively. + This controls the SO_RCVBUF and SO_SNDBUF socket options (see + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.). The usual suffixes K, M, G are supported and + are understood to the base of 1024.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IPTOS=</varname></term> + <listitem><para>Takes an integer argument controlling the IP + Type-Of-Service field for packets generated from this socket. + This controls the IP_TOS socket option (see + <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.). Either a numeric string or one of + <option>low-delay</option>, <option>throughput</option>, + <option>reliability</option> or <option>low-cost</option> may + be specified.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IPTTL=</varname></term> + <listitem><para>Takes an integer argument controlling the IPv4 + Time-To-Live/IPv6 Hop-Count field for packets generated from + this socket. This sets the IP_TTL/IPV6_UNICAST_HOPS socket + options (see + <citerefentry><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.)</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Mark=</varname></term> + <listitem><para>Takes an integer value. Controls the firewall + mark of packets generated by this socket. This can be used in + the firewall logic to filter packets from this socket. This + sets the SO_MARK socket option. See + <citerefentry><refentrytitle>iptables</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ReusePort=</varname></term> + <listitem><para>Takes a boolean value. If true, allows + multiple + <citerefentry><refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum></citerefentry>s + to this TCP or UDP port. This controls the SO_REUSEPORT socket + option. See + <citerefentry><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SmackLabel=</varname></term> + <term><varname>SmackLabelIPIn=</varname></term> + <term><varname>SmackLabelIPOut=</varname></term> + <listitem><para>Takes a string value. Controls the extended + attributes <literal>security.SMACK64</literal>, + <literal>security.SMACK64IPIN</literal> and + <literal>security.SMACK64IPOUT</literal>, respectively, i.e. + the security label of the FIFO, or the security label for the + incoming or outgoing connections of the socket, respectively. + See <ulink + url="https://www.kernel.org/doc/Documentation/security/Smack.txt">Smack.txt</ulink> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SELinuxContextFromNet=</varname></term> + <listitem><para>Takes a boolean argument. When true, systemd + will attempt to figure out the SELinux label used for the + instantiated service from the information handed by the peer + over the network. Note that only the security level is used + from the information provided by the peer. Other parts of the + resulting SELinux context originate from either the target + binary that is effectively triggered by socket unit or from + the value of the <varname>SELinuxContext=</varname> option. + This configuration option only affects sockets with + <varname>Accept=</varname> mode set to + <literal>true</literal>. Also note that this option is useful + only when MLS/MCS SELinux policy is deployed. Defaults to + <literal>false</literal>. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PipeSize=</varname></term> + <listitem><para>Takes a size in bytes. Controls the pipe + buffer size of FIFOs configured in this socket unit. See + <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. The usual suffixes K, M, G are supported and are + understood to the base of 1024.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>MessageQueueMaxMessages=</varname>, + <varname>MessageQueueMessageSize=</varname></term> + <listitem><para>These two settings take integer values and + control the mq_maxmsg field or the mq_msgsize field, + respectively, when creating the message queue. Note that + either none or both of these variables need to be set. See + <citerefentry><refentrytitle>mq_setattr</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FreeBind=</varname></term> + <listitem><para>Takes a boolean value. Controls whether the + socket can be bound to non-local IP addresses. This is useful + to configure sockets listening on specific IP addresses before + those IP addresses are successfully configured on a network + interface. This sets the IP_FREEBIND socket option. For + robustness reasons it is recommended to use this option + whenever you bind a socket to a specific IP address. Defaults + to <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Transparent=</varname></term> + <listitem><para>Takes a boolean value. Controls the + IP_TRANSPARENT socket option. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Broadcast=</varname></term> + <listitem><para>Takes a boolean value. This controls the + SO_BROADCAST socket option, which allows broadcast datagrams + to be sent from this socket. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PassCredentials=</varname></term> + <listitem><para>Takes a boolean value. This controls the + SO_PASSCRED socket option, which allows + <constant>AF_UNIX</constant> sockets to receive the + credentials of the sending process in an ancillary message. + Defaults to <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PassSecurity=</varname></term> + <listitem><para>Takes a boolean value. This controls the + SO_PASSSEC socket option, which allows + <constant>AF_UNIX</constant> sockets to receive the security + context of the sending process in an ancillary message. + Defaults to <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TCPCongestion=</varname></term> + <listitem><para>Takes a string value. Controls the TCP + congestion algorithm used by this socket. Should be one of + "westwood", "veno", "cubic", "lp" or any other available + algorithm supported by the IP stack. This setting applies only + to stream sockets.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStartPre=</varname></term> + <term><varname>ExecStartPost=</varname></term> + <listitem><para>Takes one or more command lines, which are + executed before or after the listening sockets/FIFOs are + created and bound, respectively. The first token of the + command line must be an absolute filename, then followed by + arguments for the process. Multiple command lines may be + specified following the same scheme as used for + <varname>ExecStartPre=</varname> of service unit + files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ExecStopPre=</varname></term> + <term><varname>ExecStopPost=</varname></term> + <listitem><para>Additional commands that are executed before + or after the listening sockets/FIFOs are closed and removed, + respectively. Multiple command lines may be specified + following the same scheme as used for + <varname>ExecStartPre=</varname> of service unit + files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>Configures the time to wait for the commands + specified in <varname>ExecStartPre=</varname>, + <varname>ExecStartPost=</varname>, + <varname>ExecStopPre=</varname> and + <varname>ExecStopPost=</varname> to finish. If a command does + not exit within the configured time, the socket will be + considered failed and be shut down again. All commands still + running will be terminated forcibly via + <constant>SIGTERM</constant>, and after another delay of this + time with <constant>SIGKILL</constant>. (See + <option>KillMode=</option> in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Pass <literal>0</literal> to disable the + timeout logic. Defaults to + <varname>DefaultTimeoutStartSec=</varname> from the manager + configuration file (see + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Service=</varname></term> + <listitem><para>Specifies the service unit name to activate on + incoming traffic. This setting is only allowed for sockets + with <varname>Accept=no</varname>. It defaults to the service + that bears the same name as the socket (with the suffix + replaced). In most cases, it should not be necessary to use + this option.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RemoveOnStop=</varname></term> + <listitem><para>Takes a boolean argument. If enabled, any file + nodes created by this socket unit are removed when it is + stopped. This applies to AF_UNIX sockets in the file system, + POSIX message queues, FIFOs, as well as any symlinks to them + configured with <varname>Symlinks=</varname>. Normally, it + should not be necessary to use this option, and is not + recommended as services might continue to run after the socket + unit has been terminated and it should still be possible to + communicate with them via their file system node. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Symlinks=</varname></term> + <listitem><para>Takes a list of file system paths. The + specified paths will be created as symlinks to the AF_UNIX + socket path or FIFO path of this socket unit. If this setting + is used, only one AF_UNIX socket in the file system or one + FIFO may be configured for the socket unit. Use this option to + manage one or more symlinked alias names for a socket, binding + their lifecycle together. Defaults to the empty + list.</para></listitem> + </varlistentry> + + </variablelist> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</para> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + + <para> + For more extensive descriptions see the "systemd for Developers" series: + <ulink url="http://0pointer.de/blog/projects/socket-activation.html">Socket Activation</ulink>, + <ulink url="http://0pointer.de/blog/projects/socket-activation2.html">Socket Activation, part II</ulink>, + <ulink url="http://0pointer.de/blog/projects/inetd.html">Converting inetd Services</ulink>, + <ulink url="http://0pointer.de/blog/projects/socket-activated-containers.html">Socket Activated Internet Services and OS Containers</ulink>. + </para> + </refsect1> </refentry> diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 863d7f35d9..cf76aaf607 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,1142 +23,854 @@ <refentry id="systemd.special"> - <refentryinfo> - <title>systemd.special</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.special</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.special</refname> - <refpurpose>Special systemd units</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>basic.target</filename>, - <filename>bluetooth.target</filename>, - <filename>ctrl-alt-del.target</filename>, - <filename>cryptsetup.target</filename>, - <filename>cryptsetup-pre.target</filename>, - <filename>dbus.service</filename>, - <filename>dbus.socket</filename>, - <filename>default.target</filename>, - <filename>display-manager.service</filename>, - <filename>emergency.target</filename>, - <filename>exit.target</filename>, - <filename>final.target</filename>, - <filename>getty.target</filename>, - <filename>graphical.target</filename>, - <filename>halt.target</filename>, - <filename>hibernate.target</filename>, - <filename>hybrid-sleep.target</filename>, - <filename>initrd-fs.target</filename>, - <filename>kbrequest.target</filename>, - <filename>kexec.target</filename>, - <filename>local-fs.target</filename>, - <filename>local-fs-pre.target</filename>, - <filename>multi-user.target</filename>, - <filename>network.target</filename>, - <filename>network-online.target</filename>, - <filename>network-pre.target</filename>, - <filename>nss-lookup.target</filename>, - <filename>nss-user-lookup.target</filename>, - <filename>paths.target</filename>, - <filename>poweroff.target</filename>, - <filename>printer.target</filename>, - <filename>reboot.target</filename>, - <filename>remote-fs.target</filename>, - <filename>remote-fs-pre.target</filename>, - <filename>rescue.target</filename>, - <filename>initrd-root-fs.target</filename>, - <filename>rpcbind.target</filename>, - <filename>runlevel2.target</filename>, - <filename>runlevel3.target</filename>, - <filename>runlevel4.target</filename>, - <filename>runlevel5.target</filename>, - <filename>shutdown.target</filename>, - <filename>sigpwr.target</filename>, - <filename>sleep.target</filename>, - <filename>smartcard.target</filename>, - <filename>sockets.target</filename>, - <filename>sound.target</filename>, - <filename>suspend.target</filename>, - <filename>swap.target</filename>, - <filename>sysinit.target</filename>, - <filename>syslog.socket</filename>, - <filename>system-update.target</filename>, - <filename>time-sync.target</filename>, - <filename>timers.target</filename>, - <filename>umount.target</filename>, - <filename>-.slice</filename>, - <filename>system.slice</filename>, - <filename>user.slice</filename>, - <filename>machine.slice</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A few units are treated specially by - systemd. They have special internal semantics and - cannot be renamed.</para> - </refsect1> - - <refsect1> - <title>Special System Units</title> - - <variablelist> - <varlistentry> - <term><filename>basic.target</filename></term> - <listitem> - <para>A special target unit - covering basic boot-up.</para> - <para>systemd automatically - adds dependencies of the types - <varname>Requires=</varname> - and <varname>After=</varname> - for this target unit to all - services (except for those - with - <varname>DefaultDependencies=no</varname>).</para> - - <para>Usually this should - pull-in all mount points, swap - devices, sockets, timers, and - path units and other basic - initialization necessary for - general purpose - daemons.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>ctrl-alt-del.target</filename></term> - <listitem> - <para>systemd starts this - target whenever - Control+Alt+Del is pressed on - the console. Usually this - should be aliased (symlinked) - to - <filename>reboot.target</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>cryptsetup.target</filename></term> - <listitem> - <para>A target that pulls in - setup services for all - encrypted block - devices.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>dbus.service</filename></term> - <listitem> - <para>A special unit for the - D-Bus bus daemon. As soon as - this service is fully started - up systemd will connect to it - and register its - service.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>dbus.socket</filename></term> - <listitem> - <para>A special unit for the - D-Bus system bus socket. All - units with - <varname>Type=dbus</varname> - automatically gain a - dependency on this - unit.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>default.target</filename></term> - <listitem> - <para>The default unit systemd - starts at bootup. Usually this - should be aliased (symlinked) - to - <filename>multi-user.target</filename> - or - <filename>graphical.target</filename>.</para> - - <para>The default unit systemd - starts at bootup can be - overridden with the - <varname>systemd.unit=</varname> - kernel command line option.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>display-manager.service</filename></term> - <listitem> - <para>The display manager - service. Usually this should - be aliased (symlinked) to - <filename>gdm.service</filename> - or a similar display manager - service.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>emergency.target</filename></term> - <listitem> - <para>A special target unit - that starts an emergency - shell on the main - console. This unit is supposed - to be used with the kernel - command line option - <varname>systemd.unit=</varname> - and has otherwise little use. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>final.target</filename></term> - <listitem> - <para>A special target unit - that is used during the - shutdown logic and may be used - to pull in late services after - all normal services are - already terminated and all - mounts unmounted. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>getty.target</filename></term> - <listitem> - <para>A special target unit - that pulls in statically - configured local TTY - <filename>getty</filename> - instances. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>graphical.target</filename></term> - <listitem> - <para>A special target unit - for setting up a graphical - login screen. This pulls in - <filename>multi-user.target</filename>.</para> - - <para>Units that are needed - for graphical logins shall add - <varname>Wants=</varname> - dependencies for their unit to - this unit (or - <filename>multi-user.target</filename>) - during installation. This is - best configured via - <varname>WantedBy=graphical.target</varname> - in the unit's - <literal>[Install]</literal> - section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>hibernate.target</filename></term> - <listitem> - <para>A special target unit - for hibernating the - system. This pulls in - <filename>sleep.target</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>hybrid-sleep.target</filename></term> - <listitem> - <para>A special target unit - for hibernating and suspending the - system at the same time. This pulls in - <filename>sleep.target</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>halt.target</filename></term> - <listitem> - <para>A special target unit - for shutting down and halting - the system. Note that this - target is distinct from - <filename>poweroff.target</filename> - in that it generally really - just halts the system rather - than powering it down.</para> - - <para>Applications wanting to - halt the system should start - this unit.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>initrd-fs.target</filename></term> - <listitem> - <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - automatically adds - dependencies of type - <varname>Before=</varname> to - <filename>sysroot-usr.mount</filename> - and all mount points found in - <filename>/etc/fstab</filename> - that have - <option>x-initrd.mount</option> - and not have <option>noauto</option> - mount options set.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>kbrequest.target</filename></term> - <listitem> - <para>systemd starts this - target whenever Alt+ArrowUp is - pressed on the console. This - is a good candidate to be - aliased (symlinked) to - <filename>rescue.target</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>kexec.target</filename></term> - <listitem> - <para>A special target unit - for shutting down and rebooting the system via kexec.</para> - - <para>Applications wanting to - reboot the system with kexec should start - this unit.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>local-fs.target</filename></term> - <listitem> - <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - automatically adds - dependencies of type - <varname>Before=</varname> to - all mount units that refer to - local mount points for this - target unit. In addition, it - adds dependencies of type - <varname>Wants=</varname> to - this target unit for those - mounts listed in - <filename>/etc/fstab</filename> - that have the - <option>auto</option> mount - option set.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>multi-user.target</filename></term> - <listitem> - <para>A special target unit - for setting up a multi-user - system (non-graphical). This - is pulled in by - <filename>graphical.target</filename>.</para> - - <para>Units that are needed - for a multi-user system shall - add <varname>Wants=</varname> - dependencies for their unit to - this unit during - installation. This is best - configured via - <varname>WantedBy=multi-user.target</varname> - in the unit's - <literal>[Install]</literal> - section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>network-online.target</filename></term> - <listitem> - <para>Units that strictly - require a configured network - connection should pull in - <filename>network-online.target</filename> - (via a - <varname>Wants=</varname> type - dependency) and order - themselves after it. This - target unit is intended to - pull in a service that delays - further execution until the - network is sufficiently set - up. What precisely this - requires is left to the - implementation of the network - managing service.</para> - - <para>Note the distinction - between this unit and - <filename>network.target</filename>. This - unit is an active unit - (i.e. pulled in by the - consumer rather than the - provider of this - functionality) and pulls in a - service which possibly adds - substantial delays to further - execution. In contrast, - <filename>network.target</filename> - is a passive unit (i.e. pulled - in by the provider of the - functionality, rather than the - consumer) that usually does - not delay execution - much. Usually, - <filename>network.target</filename> - is part of the boot of most - systems, while - <filename>network-online.target</filename> - is not, except when at least - one unit requires it. Also see - <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running - Services After the Network is - up</ulink> for more - information.</para> - - <para>All mount units for - remote network file systems - automatically pull in this - unit, and order themselves - after it. Note that networking - daemons that simply provide - functionality to other hosts - generally do not need to pull - this in.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>paths.target</filename></term> - <listitem> - <para>A special target unit - that sets up all path units - (see - <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details) that shall be - active after boot.</para> - - <para>It is recommended that - path units installed by - applications get pulled in via - <varname>Wants=</varname> - dependencies from this - unit. This is best configured - via a - <varname>WantedBy=paths.target</varname> - in the path unit's - <literal>[Install]</literal> - section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>poweroff.target</filename></term> - <listitem> - <para>A special target unit - for shutting down and powering off the system.</para> - - <para>Applications wanting to - power off the system should start - this unit.</para> - - <para><filename>runlevel0.target</filename> - is an alias for this target - unit, for compatibility with SysV.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>reboot.target</filename></term> - <listitem> - <para>A special target unit - for shutting down and rebooting the system.</para> - - <para>Applications wanting to - reboot the system should start - this unit.</para> - - <para><filename>runlevel6.target</filename> - is an alias for this target - unit, for compatibility with SysV.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>remote-fs.target</filename></term> - <listitem> - <para>Similar to - <filename>local-fs.target</filename>, - but for remote mount - points.</para> - - <para>systemd automatically - adds dependencies of type - <varname>After=</varname> for - this target unit to all SysV - init script service units with - an LSB header referring to the - <literal>$remote_fs</literal> - facility.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>rescue.target</filename></term> - <listitem> - <para>A special target unit - for setting up the base system - and a rescue shell.</para> - - <para><filename>runlevel1.target</filename> - is an alias for this target - unit, for compatibility with SysV.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>initrd-root-fs.target</filename></term> - <listitem> - <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> - automatically adds - dependencies of type - <varname>Before=</varname> to - the - <filename>sysroot.mount</filename> - unit, which is generated from - the kernel command line. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>runlevel2.target</filename></term> - <term><filename>runlevel3.target</filename></term> - <term><filename>runlevel4.target</filename></term> - <term><filename>runlevel5.target</filename></term> - <listitem> - <para>These are targets that - are called whenever the SysV - compatibility code asks for - runlevel 2, 3, 4, 5, - respectively. It is a good - idea to make this an alias for - (i.e. symlink to) - <filename>multi-user.target</filename> - (for runlevel 2) or - <filename>graphical.target</filename> - (the others).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>shutdown.target</filename></term> - <listitem> - <para>A special target unit - that terminates the services - on system shutdown.</para> - - <para>Services that shall be - terminated on system shutdown - shall add <varname>Conflicts=</varname> - dependencies to this unit for - their service unit, which is - implicitly done when - <varname>DefaultDependencies=yes</varname> - is set (the default).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>sigpwr.target</filename></term> - <listitem> - <para>A special target that is - started when systemd receives - the SIGPWR process signal, - which is normally sent by the - kernel or UPS daemons when - power fails.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>sleep.target</filename></term> - <listitem> - <para>A special target unit - that is pulled in by - <filename>suspend.target</filename>, - <filename>hibernate.target</filename> - and - <filename>hybrid-sleep.target</filename> - and may be used to hook units - into the sleep state - logic.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>sockets.target</filename></term> - <listitem> - <para>A special target unit - that sets up all socket - units.(see - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details) that shall be - active after boot.</para> - - <para>Services that can be - socket-activated shall add - <varname>Wants=</varname> - dependencies to this unit for - their socket unit during - installation. This is best - configured via a - <varname>WantedBy=sockets.target</varname> - in the socket unit's - <literal>[Install]</literal> - section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>suspend.target</filename></term> - <listitem> - <para>A special target unit - for suspending the - system. This pulls in - <filename>sleep.target</filename>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>swap.target</filename></term> - <listitem> - <para>Similar to - <filename>local-fs.target</filename>, but for swap - partitions and swap - files.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>sysinit.target</filename></term> - <listitem> - <para>A special target unit - covering early boot-up scripts.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>syslog.socket</filename></term> - <listitem> - <para>The socket unit - syslog implementations should - listen on. All userspace log - messages will be made - available on this socket. For - more information about syslog - integration, please consult - the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/syslog">Syslog - Interface</ulink> - document.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>system-update.target</filename></term> - <listitem> - <para>A special target unit - that is used for off-line - system updates. - <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - will redirect the boot process - to this target if - <filename>/system-update</filename> - exists. For more information - see the <ulink - url="http://freedesktop.org/wiki/Software/systemd/SystemUpdates">System - Updates - Specification</ulink>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>timers.target</filename></term> - <listitem> - <para>A special target unit - that sets up all timer - units (see - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details) that shall be - active after boot.</para> - - <para>It is recommended that - timer units installed by - applications get pulled in via - <varname>Wants=</varname> - dependencies from this - unit. This is best configured - via - <varname>WantedBy=timers.target</varname> - in the timer unit's - <literal>[Install]</literal> - section.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>umount.target</filename></term> - <listitem> - <para>A special target unit - that umounts all mount and - automount points on system - shutdown.</para> - - <para>Mounts that shall be - unmounted on system shutdown - shall add Conflicts - dependencies to this unit for - their mount unit, which is - implicitly done when - <varname>DefaultDependencies=yes</varname> - is set (the default).</para> - </listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Special System Units for Devices</title> - - <para>Some target units are automatically pulled in as - devices of certain kinds show up in the system. These - may be used to automatically activate various services - based on the specific type of the available - hardware.</para> - - <variablelist> - <varlistentry> - <term><filename>bluetooth.target</filename></term> - <listitem> - <para>This target is started - automatically as soon as a - Bluetooth controller is - plugged in or becomes - available at boot.</para> - - <para>This may be used to pull - in Bluetooth management - daemons dynamically when - Bluetooth hardware is - found.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>printer.target</filename></term> - <listitem> - <para>This target is started - automatically as soon as a - printer is plugged in or - becomes available at - boot.</para> - - <para>This may be used to pull - in printer management - daemons dynamically when - printer hardware is - found.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>smartcard.target</filename></term> - <listitem> - <para>This target is started - automatically as soon as a - smartcard controller is - plugged in or becomes - available at boot.</para> - - <para>This may be used to pull - in smartcard management - daemons dynamically when - smartcard hardware is - found.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>sound.target</filename></term> - <listitem> - <para>This target is started - automatically as soon as a - sound card is plugged in or - becomes available at - boot.</para> - - <para>This may be used to pull - in audio management daemons - dynamically when audio - hardware is found.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Special Passive System Units </title> - - <para>A number of special system targets are defined - that can be used to properly order boot-up of optional - services. These targets are generally not part of the - initial boot transaction, unless they are explicitly - pulled in by one of the implementing services. Note - specifically that these <emphasis>passive</emphasis> - target units are generally not pulled in by the - consumer of a service, but by the provider of the - service. This means: a consuming service should order - itself after these targets (as appropriate), but not - pull it in. A providing service should order itself - before these targets (as appropriate) and pull it in - (via a <varname>Wants=</varname> type - dependency).</para> - - <para>Note that these passive units cannot be started - manually, i.e. <literal>systemctl start - time-sync.target</literal> will fail with an - error. They can only be pulled in by dependency. This - is enforced since they exist for ordering purposes - only and thus are not useful as only unit within a - transaction.</para> - - <variablelist> - <varlistentry> - <term><filename>cryptsetup-pre.target</filename></term> - <listitem> - <para>This passive target unit - may be pulled in by services - that want to run before any - encrypted block device is set - up. All encrypted block - devices are set up after this - target has been reached. Since - the shutdown order is - implicitly the reverse - start-up order between units, - this target is particularly - useful to ensure that a - service is shut down only - after all encrypted block - devices are fully - stopped.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>local-fs-pre.target</filename></term> - <listitem> - <para>This target unit is - automatically ordered before - all local mount points marked - with <option>auto</option> - (see above). It can be used to - execute certain units before - all local mounts.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>network.target</filename></term> - <listitem> - <para>This unit is supposed to - indicate when network - functionality is available, - but it is only very weakly - 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 -- 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 - <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running - Services After the Network is - up</ulink> for more - information. Also see - <filename>network-online.target</filename> - described above.</para> - - <para>systemd automatically - adds dependencies of type - <varname>After=</varname> for - this target unit to all SysV - init script service units with - an LSB header referring to the - <literal>$network</literal> - facility.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>network-pre.target</filename></term> - <listitem> - <para>This passive target unit - may be pulled in by services - that want to run before any - network is set up, for example - for the purpose of setting up a - firewall. All network - management software orders - itself after this target, but - does not pull it in.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>nss-lookup.target</filename></term> - <listitem> - <para>A target that should be - used as synchronization point - for all host/network name - service lookups. Note that - this is independent of - user/group name lookups for - which - <filename>nss-user-lookup.target</filename> - should be used. All services - for which the availability of - full host/network name - resolution is essential should - be ordered after this target, - but not pull it in. systemd - automatically adds - dependencies of type - <varname>After=</varname> for - this target unit to all SysV - init script service units with - an LSB header referring to the - <literal>$named</literal> - facility.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>nss-user-lookup.target</filename></term> - <listitem> - <para>A target that should be - used as synchronization point - for all user/group name - service lookups. Note that - this is independent of - host/network name lookups for - which - <filename>nss-lookup.target</filename> - should be used. All services - for which the availability of - the full user/group database is - essential should be ordered - after this target, but not - pull it in. Note that system - users are always resolvable, - and hence do not require any - special ordering against this - target.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>remote-fs-pre.target</filename></term> - <listitem> - <para>This target unit is - automatically ordered before - all remote mount point units - (see above). It can be used to - run certain units before the - remote mounts are - established. Note that this - unit is generally not part of - the initial transaction, - unless the unit that wants to - be ordered before all remote - mounts pulls it in via a - <varname>Wants=</varname> type - dependency. If the unit wants - to be pulled in by the first - remote mount showing up, it - should use - <filename>network-online.target</filename> - (see above).</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>rpcbind.target</filename></term> - <listitem> - <para>The portmapper/rpcbind - pulls in this target and - orders itself before it, to - indicate its - availability. systemd - automatically adds - dependencies of type - <varname>After=</varname> for - this target unit to all SysV - init script service units with - an LSB header referring to the - <literal>$portmap</literal> - facility.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><filename>time-sync.target</filename></term> - <listitem> - <para>Services responsible for - synchronizing the system clock - from a remote source (such as - NTP client implementations) - should pull in this target and - order themselves before - it. All services where correct - time is essential should be - ordered after this unit, but - not pull it in. systemd - automatically adds - dependencies of type - <varname>After=</varname> for - this target unit to all SysV - init script service units with - an LSB header referring to the - <literal>$time</literal> - facility. </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Special User Units</title> - - <para>When systemd runs as a user instance, the - following special units are available, which have - similar definitions as their system counterparts: - <filename>default.target</filename>, - <filename>shutdown.target</filename>, - <filename>sockets.target</filename>, - <filename>timers.target</filename>, - <filename>paths.target</filename>, - <filename>bluetooth.target</filename>, - <filename>printer.target</filename>, - <filename>smartcard.target</filename>, - <filename>sound.target</filename>.</para> - - <para>In addition, the following special unit is - understood only when systemd runs as service instance:</para> - - <variablelist> - <varlistentry> - <term><filename>exit.target</filename></term> - <listitem> - <para>A special service unit - for shutting down the - user service manager.</para> - - <para>Applications wanting to - terminate the user service - manager should start this - unit. If systemd receives - <constant>SIGTERM</constant> or <constant>SIGINT</constant> when running - as user service daemon, it will - start this unit.</para> - - <para>Normally, this pulls in - <filename>shutdown.target</filename> - which in turn should be - conflicted by all units that - want to be shut down on - user service manager exit.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Special Slice Units</title> - - <para>There are four <literal>.slice</literal> units - which form the basis of the hierarchy for assignment - of resources for services, users, and virtual machines - or containers.</para> - - <variablelist> - <varlistentry> - <term><filename>-.slice</filename></term> - <listitem> - <para>The root slice is the - root of the hierarchy. It - usually does not contain units - directly, but may be used to - set defaults for the whole - tree.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>system.slice</filename></term> - <listitem> - <para>By default, all services - services started by - <command>systemd</command> are - found in this slice.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>user.slice</filename></term> - <listitem> - <para>By default, all user - processes and services started - on behalf of the user, - including the per-user systemd - instance are found in this - slice.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><filename>machine.slice</filename></term> - <listitem> - <para>By default, all virtual - machines and containers - registered with - <command>systemd-machined</command> - are found in this slice. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd.special</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.special</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.special</refname> + <refpurpose>Special systemd units</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>basic.target</filename>, + <filename>bluetooth.target</filename>, + <filename>ctrl-alt-del.target</filename>, + <filename>cryptsetup.target</filename>, + <filename>cryptsetup-pre.target</filename>, + <filename>dbus.service</filename>, + <filename>dbus.socket</filename>, + <filename>default.target</filename>, + <filename>display-manager.service</filename>, + <filename>emergency.target</filename>, + <filename>exit.target</filename>, + <filename>final.target</filename>, + <filename>getty.target</filename>, + <filename>graphical.target</filename>, + <filename>halt.target</filename>, + <filename>hibernate.target</filename>, + <filename>hybrid-sleep.target</filename>, + <filename>initrd-fs.target</filename>, + <filename>kbrequest.target</filename>, + <filename>kexec.target</filename>, + <filename>local-fs.target</filename>, + <filename>local-fs-pre.target</filename>, + <filename>multi-user.target</filename>, + <filename>network.target</filename>, + <filename>network-online.target</filename>, + <filename>network-pre.target</filename>, + <filename>nss-lookup.target</filename>, + <filename>nss-user-lookup.target</filename>, + <filename>paths.target</filename>, + <filename>poweroff.target</filename>, + <filename>printer.target</filename>, + <filename>reboot.target</filename>, + <filename>remote-fs.target</filename>, + <filename>remote-fs-pre.target</filename>, + <filename>rescue.target</filename>, + <filename>initrd-root-fs.target</filename>, + <filename>rpcbind.target</filename>, + <filename>runlevel2.target</filename>, + <filename>runlevel3.target</filename>, + <filename>runlevel4.target</filename>, + <filename>runlevel5.target</filename>, + <filename>shutdown.target</filename>, + <filename>sigpwr.target</filename>, + <filename>sleep.target</filename>, + <filename>smartcard.target</filename>, + <filename>sockets.target</filename>, + <filename>sound.target</filename>, + <filename>suspend.target</filename>, + <filename>swap.target</filename>, + <filename>sysinit.target</filename>, + <filename>syslog.socket</filename>, + <filename>system-update.target</filename>, + <filename>time-sync.target</filename>, + <filename>timers.target</filename>, + <filename>umount.target</filename>, + <filename>-.slice</filename>, + <filename>system.slice</filename>, + <filename>user.slice</filename>, + <filename>machine.slice</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A few units are treated specially by systemd. They have + special internal semantics and cannot be renamed.</para> + </refsect1> + + <refsect1> + <title>Special System Units</title> + + <variablelist> + <varlistentry> + <term><filename>basic.target</filename></term> + <listitem> + <para>A special target unit covering basic boot-up.</para> + + <para>systemd automatically adds dependencies of the types + <varname>Requires=</varname> and <varname>After=</varname> + for this target unit to all services (except for those with + <varname>DefaultDependencies=no</varname>).</para> + + <para>Usually this should pull-in all mount points, swap + devices, sockets, timers, and path units and other basic + initialization necessary for general purpose daemons.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>ctrl-alt-del.target</filename></term> + <listitem> + <para>systemd starts this target whenever Control+Alt+Del is + pressed on the console. Usually this should be aliased + (symlinked) to <filename>reboot.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>cryptsetup.target</filename></term> + <listitem> + <para>A target that pulls in setup services for all + encrypted block devices.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>dbus.service</filename></term> + <listitem> + <para>A special unit for the D-Bus bus daemon. As soon as + this service is fully started up systemd will connect to it + and register its service.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>dbus.socket</filename></term> + <listitem> + <para>A special unit for the D-Bus system bus socket. All + units with <varname>Type=dbus</varname> automatically gain a + dependency on this unit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>default.target</filename></term> + <listitem> + <para>The default unit systemd starts at bootup. Usually + this should be aliased (symlinked) to + <filename>multi-user.target</filename> or + <filename>graphical.target</filename>.</para> + + <para>The default unit systemd starts at bootup can be + overridden with the <varname>systemd.unit=</varname> kernel + command line option.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>display-manager.service</filename></term> + <listitem> + <para>The display manager service. Usually this should be + aliased (symlinked) to <filename>gdm.service</filename> or a + similar display manager service.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>emergency.target</filename></term> + <listitem> + <para>A special target unit that starts an emergency shell + on the main console. This unit is supposed to be used with + the kernel command line option + <varname>systemd.unit=</varname> and has otherwise little + use. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>final.target</filename></term> + <listitem> + <para>A special target unit that is used during the shutdown + logic and may be used to pull in late services after all + normal services are already terminated and all mounts + unmounted. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>getty.target</filename></term> + <listitem> + <para>A special target unit that pulls in statically + configured local TTY <filename>getty</filename> instances. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>graphical.target</filename></term> + <listitem> + <para>A special target unit for setting up a graphical login + screen. This pulls in + <filename>multi-user.target</filename>.</para> + + <para>Units that are needed for graphical logins shall add + <varname>Wants=</varname> dependencies for their unit to + this unit (or <filename>multi-user.target</filename>) during + installation. This is best configured via + <varname>WantedBy=graphical.target</varname> in the unit's + <literal>[Install]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>hibernate.target</filename></term> + <listitem> + <para>A special target unit for hibernating the system. This + pulls in <filename>sleep.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>hybrid-sleep.target</filename></term> + <listitem> + <para>A special target unit for hibernating and suspending + the system at the same time. This pulls in + <filename>sleep.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>halt.target</filename></term> + <listitem> + <para>A special target unit for shutting down and halting + the system. Note that this target is distinct from + <filename>poweroff.target</filename> in that it generally + really just halts the system rather than powering it + down.</para> + + <para>Applications wanting to halt the system should start + this unit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>initrd-fs.target</filename></term> + <listitem> + <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + automatically adds dependencies of type + <varname>Before=</varname> to + <filename>sysroot-usr.mount</filename> and all mount points + found in <filename>/etc/fstab</filename> that have + <option>x-initrd.mount</option> and not have + <option>noauto</option> mount options set.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>kbrequest.target</filename></term> + <listitem> + <para>systemd starts this target whenever Alt+ArrowUp is + pressed on the console. This is a good candidate to be + aliased (symlinked) to + <filename>rescue.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>kexec.target</filename></term> + <listitem> + <para>A special target unit for shutting down and rebooting + the system via kexec.</para> + + <para>Applications wanting to reboot the system with kexec + should start this unit.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>local-fs.target</filename></term> + <listitem> + <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + automatically adds dependencies of type + <varname>Before=</varname> to all mount units that refer to + local mount points for this target unit. In addition, it + adds dependencies of type <varname>Wants=</varname> to this + target unit for those mounts listed in + <filename>/etc/fstab</filename> that have the + <option>auto</option> mount option set.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>multi-user.target</filename></term> + <listitem> + <para>A special target unit for setting up a multi-user + system (non-graphical). This is pulled in by + <filename>graphical.target</filename>.</para> + + <para>Units that are needed for a multi-user system shall + add <varname>Wants=</varname> dependencies for their unit to + this unit during installation. This is best configured via + <varname>WantedBy=multi-user.target</varname> in the unit's + <literal>[Install]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>network-online.target</filename></term> + <listitem> + <para>Units that strictly require a configured network + connection should pull in + <filename>network-online.target</filename> (via a + <varname>Wants=</varname> type dependency) and order + themselves after it. This target unit is intended to pull in + a service that delays further execution until the network is + sufficiently set up. What precisely this requires is left to + the implementation of the network managing service.</para> + + <para>Note the distinction between this unit and + <filename>network.target</filename>. This unit is an active + unit (i.e. pulled in by the consumer rather than the + provider of this functionality) and pulls in a service which + possibly adds substantial delays to further execution. In + contrast, <filename>network.target</filename> is a passive + unit (i.e. pulled in by the provider of the functionality, + rather than the consumer) that usually does not delay + execution much. Usually, <filename>network.target</filename> + is part of the boot of most systems, while + <filename>network-online.target</filename> is not, except + when at least one unit requires it. Also see <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running + Services After the Network is up</ulink> for more + information.</para> + + <para>All mount units for remote network file systems + automatically pull in this unit, and order themselves after + it. Note that networking daemons that simply provide + functionality to other hosts generally do not need to pull + this in.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>paths.target</filename></term> + <listitem> + <para>A special target unit that sets up all path units (see + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) that shall be active after boot.</para> + + <para>It is recommended that path units installed by + applications get pulled in via <varname>Wants=</varname> + dependencies from this unit. This is best configured via a + <varname>WantedBy=paths.target</varname> in the path unit's + <literal>[Install]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>poweroff.target</filename></term> + <listitem> + <para>A special target unit for shutting down and powering + off the system.</para> + + <para>Applications wanting to power off the system should + start this unit.</para> + + <para><filename>runlevel0.target</filename> is an alias for + this target unit, for compatibility with SysV.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>reboot.target</filename></term> + <listitem> + <para>A special target unit for shutting down and rebooting + the system.</para> + + <para>Applications wanting to reboot the system should start + this unit.</para> + + <para><filename>runlevel6.target</filename> is an alias for + this target unit, for compatibility with SysV.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>remote-fs.target</filename></term> + <listitem> + <para>Similar to <filename>local-fs.target</filename>, but + for remote mount points.</para> + + <para>systemd automatically adds dependencies of type + <varname>After=</varname> for this target unit to all SysV + init script service units with an LSB header referring to + the <literal>$remote_fs</literal> facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>rescue.target</filename></term> + <listitem> + <para>A special target unit for setting up the base system + and a rescue shell.</para> + + <para><filename>runlevel1.target</filename> is an alias for + this target unit, for compatibility with SysV.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>initrd-root-fs.target</filename></term> + <listitem> + <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry> + automatically adds dependencies of type + <varname>Before=</varname> to the + <filename>sysroot.mount</filename> unit, which is generated + from the kernel command line. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>runlevel2.target</filename></term> + <term><filename>runlevel3.target</filename></term> + <term><filename>runlevel4.target</filename></term> + <term><filename>runlevel5.target</filename></term> + <listitem> + <para>These are targets that are called whenever the SysV + compatibility code asks for runlevel 2, 3, 4, 5, + respectively. It is a good idea to make this an alias for + (i.e. symlink to) <filename>multi-user.target</filename> + (for runlevel 2) or <filename>graphical.target</filename> + (the others).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>shutdown.target</filename></term> + <listitem> + <para>A special target unit that terminates the services on + system shutdown.</para> + + <para>Services that shall be terminated on system shutdown + shall add <varname>Conflicts=</varname> dependencies to this + unit for their service unit, which is implicitly done when + <varname>DefaultDependencies=yes</varname> is set (the + default).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sigpwr.target</filename></term> + <listitem> + <para>A special target that is started when systemd receives + the SIGPWR process signal, which is normally sent by the + kernel or UPS daemons when power fails.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sleep.target</filename></term> + <listitem> + <para>A special target unit that is pulled in by + <filename>suspend.target</filename>, + <filename>hibernate.target</filename> and + <filename>hybrid-sleep.target</filename> and may be used to + hook units into the sleep state logic.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sockets.target</filename></term> + <listitem> + <para>A special target unit that sets up all socket + units.(see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) that shall be active after boot.</para> + + <para>Services that can be socket-activated shall add + <varname>Wants=</varname> dependencies to this unit for + their socket unit during installation. This is best + configured via a <varname>WantedBy=sockets.target</varname> + in the socket unit's <literal>[Install]</literal> + section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>suspend.target</filename></term> + <listitem> + <para>A special target unit for suspending the system. This + pulls in <filename>sleep.target</filename>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>swap.target</filename></term> + <listitem> + <para>Similar to <filename>local-fs.target</filename>, but + for swap partitions and swap files.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sysinit.target</filename></term> + <listitem> + <para>A special target unit covering early boot-up + scripts.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>syslog.socket</filename></term> + <listitem> + <para>The socket unit syslog implementations should listen + on. All userspace log messages will be made available on + this socket. For more information about syslog integration, + please consult the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/syslog">Syslog + Interface</ulink> document.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>system-update.target</filename></term> + <listitem> + <para>A special target unit that is used for off-line system + updates. + <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + will redirect the boot process to this target if + <filename>/system-update</filename> exists. For more + information see the <ulink + url="http://freedesktop.org/wiki/Software/systemd/SystemUpdates">System + Updates Specification</ulink>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>timers.target</filename></term> + <listitem> + <para>A special target unit that sets up all timer units + (see + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details) that shall be active after boot.</para> + + <para>It is recommended that timer units installed by + applications get pulled in via <varname>Wants=</varname> + dependencies from this unit. This is best configured via + <varname>WantedBy=timers.target</varname> in the timer + unit's <literal>[Install]</literal> section.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>umount.target</filename></term> + <listitem> + <para>A special target unit that umounts all mount and + automount points on system shutdown.</para> + + <para>Mounts that shall be unmounted on system shutdown + shall add Conflicts dependencies to this unit for their + mount unit, which is implicitly done when + <varname>DefaultDependencies=yes</varname> is set (the + default).</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Special System Units for Devices</title> + + <para>Some target units are automatically pulled in as devices of + certain kinds show up in the system. These may be used to + automatically activate various services based on the specific type + of the available hardware.</para> + + <variablelist> + <varlistentry> + <term><filename>bluetooth.target</filename></term> + <listitem> + <para>This target is started automatically as soon as a + Bluetooth controller is plugged in or becomes available at + boot.</para> + + <para>This may be used to pull in Bluetooth management + daemons dynamically when Bluetooth hardware is found.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>printer.target</filename></term> + <listitem> + <para>This target is started automatically as soon as a + printer is plugged in or becomes available at boot.</para> + + <para>This may be used to pull in printer management daemons + dynamically when printer hardware is found.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>smartcard.target</filename></term> + <listitem> + <para>This target is started automatically as soon as a + smartcard controller is plugged in or becomes available at + boot.</para> + + <para>This may be used to pull in smartcard management + daemons dynamically when smartcard hardware is found.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>sound.target</filename></term> + <listitem> + <para>This target is started automatically as soon as a + sound card is plugged in or becomes available at + boot.</para> + + <para>This may be used to pull in audio management daemons + dynamically when audio hardware is found.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Special Passive System Units </title> + + <para>A number of special system targets are defined that can be + used to properly order boot-up of optional services. These targets + are generally not part of the initial boot transaction, unless + they are explicitly pulled in by one of the implementing services. + Note specifically that these <emphasis>passive</emphasis> target + units are generally not pulled in by the consumer of a service, + but by the provider of the service. This means: a consuming + service should order itself after these targets (as appropriate), + but not pull it in. A providing service should order itself before + these targets (as appropriate) and pull it in (via a + <varname>Wants=</varname> type dependency).</para> + + <para>Note that these passive units cannot be started manually, + i.e. <literal>systemctl start time-sync.target</literal> will fail + with an error. They can only be pulled in by dependency. This is + enforced since they exist for ordering purposes only and thus are + not useful as only unit within a transaction.</para> + + <variablelist> + <varlistentry> + <term><filename>cryptsetup-pre.target</filename></term> + <listitem> + <para>This passive target unit may be pulled in by services + that want to run before any encrypted block device is set + up. All encrypted block devices are set up after this target + has been reached. Since the shutdown order is implicitly the + reverse start-up order between units, this target is + particularly useful to ensure that a service is shut down + only after all encrypted block devices are fully + stopped.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>local-fs-pre.target</filename></term> + <listitem> + <para>This target unit is + automatically ordered before + all local mount points marked + with <option>auto</option> + (see above). It can be used to + execute certain units before + all local mounts.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>network.target</filename></term> + <listitem> + <para>This unit is supposed to indicate when network + functionality is available, but it is only very weakly + 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 -- + 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 + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running + Services After the Network is up</ulink> for more + information. Also see + <filename>network-online.target</filename> described + above.</para> + + <para>systemd automatically adds dependencies of type + <varname>After=</varname> for this target unit to all SysV + init script service units with an LSB header referring to + the <literal>$network</literal> facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>network-pre.target</filename></term> + <listitem> + <para>This passive target unit may be pulled in by services + that want to run before any network is set up, for example + for the purpose of setting up a firewall. All network + management software orders itself after this target, but + does not pull it in.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>nss-lookup.target</filename></term> + <listitem> + <para>A target that should be used as synchronization point + for all host/network name service lookups. Note that this is + independent of user/group name lookups for which + <filename>nss-user-lookup.target</filename> should be used. + All services for which the availability of full host/network + name resolution is essential should be ordered after this + target, but not pull it in. systemd automatically adds + dependencies of type <varname>After=</varname> for this + target unit to all SysV init script service units with an + LSB header referring to the <literal>$named</literal> + facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>nss-user-lookup.target</filename></term> + <listitem> + <para>A target that should be used as synchronization point + for all user/group name service lookups. Note that this is + independent of host/network name lookups for which + <filename>nss-lookup.target</filename> should be used. All + services for which the availability of the full user/group + database is essential should be ordered after this target, + but not pull it in. Note that system users are always + resolvable, and hence do not require any special ordering + against this target.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>remote-fs-pre.target</filename></term> + <listitem> + <para>This target unit is automatically ordered before all + remote mount point units (see above). It can be used to run + certain units before the remote mounts are established. Note + that this unit is generally not part of the initial + transaction, unless the unit that wants to be ordered before + all remote mounts pulls it in via a + <varname>Wants=</varname> type dependency. If the unit wants + to be pulled in by the first remote mount showing up, it + should use <filename>network-online.target</filename> (see + above).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>rpcbind.target</filename></term> + <listitem> + <para>The portmapper/rpcbind pulls in this target and orders + itself before it, to indicate its availability. systemd + automatically adds dependencies of type + <varname>After=</varname> for this target unit to all SysV + init script service units with an LSB header referring to + the <literal>$portmap</literal> facility.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><filename>time-sync.target</filename></term> + <listitem> + <para>Services responsible for synchronizing the system + clock from a remote source (such as NTP client + implementations) should pull in this target and order + themselves before it. All services where correct time is + essential should be ordered after this unit, but not pull it + in. systemd automatically adds dependencies of type + <varname>After=</varname> for this target unit to all SysV + init script service units with an LSB header referring to + the <literal>$time</literal> facility. </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Special User Units</title> + + <para>When systemd runs as a user instance, the following special + units are available, which have similar definitions as their + system counterparts: + <filename>default.target</filename>, + <filename>shutdown.target</filename>, + <filename>sockets.target</filename>, + <filename>timers.target</filename>, + <filename>paths.target</filename>, + <filename>bluetooth.target</filename>, + <filename>printer.target</filename>, + <filename>smartcard.target</filename>, + <filename>sound.target</filename>.</para> + + <para>In addition, the following special unit is understood only + when systemd runs as service instance:</para> + + <variablelist> + <varlistentry> + <term><filename>exit.target</filename></term> + <listitem> + <para>A special service unit for shutting down the user + service manager.</para> + + <para>Applications wanting to terminate the user service + manager should start this unit. If systemd receives + <constant>SIGTERM</constant> or <constant>SIGINT</constant> + when running as user service daemon, it will start this + unit.</para> + + <para>Normally, this pulls in + <filename>shutdown.target</filename> which in turn should be + conflicted by all units that want to be shut down on user + service manager exit.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Special Slice Units</title> + + <para>There are four <literal>.slice</literal> units which form + the basis of the hierarchy for assignment of resources for + services, users, and virtual machines or containers.</para> + + <variablelist> + <varlistentry> + <term><filename>-.slice</filename></term> + <listitem> + <para>The root slice is the root of the hierarchy. It + usually does not contain units directly, but may be used to + set defaults for the whole tree.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>system.slice</filename></term> + <listitem> + <para>By default, all services services started by + <command>systemd</command> are found in this slice.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>user.slice</filename></term> + <listitem> + <para>By default, all user processes and services started on + behalf of the user, including the per-user systemd instance + are found in this slice.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>machine.slice</filename></term> + <listitem> + <para>By default, all virtual machines and containers + registered with <command>systemd-machined</command> are + found in this slice. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.swap.xml b/man/systemd.swap.xml index 9cc3b80bb9..5523e5e11b 100644 --- a/man/systemd.swap.xml +++ b/man/systemd.swap.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,237 +23,217 @@ --> <refentry id="systemd.swap"> - <refentryinfo> - <title>systemd.swap</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.swap</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.swap</refname> - <refpurpose>Swap unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>swap</replaceable>.swap</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.swap</literal> encodes information about a - swap device or file for memory paging controlled and - supervised by systemd.</para> - - <para>This man page lists the configuration options - specific to this unit type. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the common options of all unit configuration - files. The common configuration items are configured - in the generic [Unit] and [Install] sections. The swap - specific configuration options are configured in the - [Swap] section.</para> - - <para>Additional options are listed in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the execution environment the - <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> - binary is executed in, and in - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which define the way the processes are - terminated, and in - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - which configure resource control settings for the - processes of the service.</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>All swap units automatically get the appropriate - dependencies on the devices or on the mount points - of the files they are activated from.</para> - - <para>Swap units with - <varname>DefaultDependencies=</varname> enabled - implicitly acquire a conflicting dependency to - <filename>umount.target</filename> so that they are - deactivated at shutdown.</para> - </refsect1> - - <refsect1> - <title><filename>fstab</filename></title> - - <para>Swap units may either be configured via unit - files, or via <filename>/etc/fstab</filename> (see - <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). Swaps listed in - <filename>/etc/fstab</filename> will be converted into - native units dynamically at boot and when the - configuration of the system manager is - reloaded. See - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details about the conversion.</para> - - <para>If a swap device or file is configured in both - <filename>/etc/fstab</filename> and a unit file, the - configuration in the latter takes precedence.</para> - - <para>When reading <filename>/etc/fstab</filename> a - few special options are understood by systemd which - influence how dependencies are created for swap - units.</para> - - <variablelist class='fstab-options'> - <varlistentry> - <term><option>noauto</option></term> - <term><option>auto</option></term> - - <listitem><para>With <option>noauto</option> the - swap unit will not be added as a dependency for - <filename>swap.target</filename>. This means that - it will not be activated automatically during - boot, unless it is pulled in by some other - unit. Option <option>auto</option> has the - opposite meaning and is the default.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><option>nofail</option></term> - - <listitem><para>With <option>nofail</option> the - swap unit will be only wanted, not required by - <filename>swap.target</filename>. This means that - the boot will continue even if this swap device is - not activated successfully.</para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>Swap files must include a [Swap] section, which - carries information about the swap device it - supervises. A number of options that may be used in - this section are shared with other unit types. These - options are documented in - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The - options specific to the [Swap] section of swap units - are the following:</para> - - <variablelist class='unit-directives'> - - <varlistentry> - <term><varname>What=</varname></term> - <listitem><para>Takes an absolute path - of a device node or file to use for - paging. See - <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for details. If this refers to a - device node, a dependency on the - respective device unit is - automatically created. (See - <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information.) If this refers - to a file, a dependency on the - respective mount unit is automatically - created. (See - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information.) This option is - mandatory.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Priority=</varname></term> - - <listitem><para>Swap priority to use - when activating the swap device or - file. This takes an integer. This - setting is optional.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Options=</varname></term> - - <listitem><para>May contain an option - string for the swap device. This may - be used for controlling discard - options among other functionality, if - the swap backing device supports the - discard or trim operation. (See - <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for more information.) - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>TimeoutSec=</varname></term> - <listitem><para>Configures the time to - wait for the swapon command to - finish. If a command does not exit - within the configured time, the swap - will be considered failed and be shut - down again. All commands still running - will be terminated forcibly via - <constant>SIGTERM</constant>, and after another delay of - this time with <constant>SIGKILL</constant>. (See - <option>KillMode=</option> in - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) - Takes a unit-less value in seconds, or - a time span value such as "5min - 20s". Pass <literal>0</literal> to disable the timeout - logic. Defaults to <varname>DefaultTimeoutStartSec=</varname> from the - manager configuration file - (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - </para></listitem> - </varlistentry> - </variablelist> - - <para>Check - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more settings.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd.swap</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.swap</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.swap</refname> + <refpurpose>Swap unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>swap</replaceable>.swap</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.swap</literal> encodes information about a swap device + or file for memory paging controlled and supervised by + systemd.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. The swap specific configuration options are + configured in the [Swap] section.</para> + + <para>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the + <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> + binary is executed in, and in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the way the processes are terminated, and in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which configure resource control settings for the processes of the + service.</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>All swap units automatically get the appropriate + dependencies on the devices or on the mount points of the files + they are activated from.</para> + + <para>Swap units with <varname>DefaultDependencies=</varname> + enabled implicitly acquire a conflicting dependency to + <filename>umount.target</filename> so that they are deactivated at + shutdown.</para> + </refsect1> + + <refsect1> + <title><filename>fstab</filename></title> + + <para>Swap units may either be configured via unit files, or via + <filename>/etc/fstab</filename> (see + <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Swaps listed in <filename>/etc/fstab</filename> will + be converted into native units dynamically at boot and when the + configuration of the system manager is reloaded. See + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details about the conversion.</para> + + <para>If a swap device or file is configured in both + <filename>/etc/fstab</filename> and a unit file, the configuration + in the latter takes precedence.</para> + + <para>When reading <filename>/etc/fstab</filename> a few special + options are understood by systemd which influence how dependencies + are created for swap units.</para> + + <variablelist class='fstab-options'> + <varlistentry> + <term><option>noauto</option></term> + <term><option>auto</option></term> + + <listitem><para>With <option>noauto</option> the swap unit + will not be added as a dependency for + <filename>swap.target</filename>. This means that it will not + be activated automatically during boot, unless it is pulled in + by some other unit. Option <option>auto</option> has the + opposite meaning and is the default.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>nofail</option></term> + + <listitem><para>With <option>nofail</option> the swap unit + will be only wanted, not required by + <filename>swap.target</filename>. This means that the boot + will continue even if this swap device is not activated + successfully.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Swap files must include a [Swap] section, which carries + information about the swap device it supervises. A number of + options that may be used in this section are shared with other + unit types. These options are documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + The options specific to the [Swap] section of swap units are the + following:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>What=</varname></term> + <listitem><para>Takes an absolute path of a device node or + file to use for paging. See + <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details. If this refers to a device node, a dependency on + the respective device unit is automatically created. (See + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.) If this refers to a file, a dependency + on the respective mount unit is automatically created. (See + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.) This option is + mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Priority=</varname></term> + + <listitem><para>Swap priority to use when activating the swap + device or file. This takes an integer. This setting is + optional.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Options=</varname></term> + + <listitem><para>May contain an option string for the swap + device. This may be used for controlling discard options among + other functionality, if the swap backing device supports the + discard or trim operation. (See + <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more information.) </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>Configures the time to wait for the swapon + command to finish. If a command does not exit within the + configured time, the swap will be considered failed and be + shut down again. All commands still running will be terminated + forcibly via <constant>SIGTERM</constant>, and after another + delay of this time with <constant>SIGKILL</constant>. (See + <option>KillMode=</option> in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Pass <literal>0</literal> to disable the + timeout logic. Defaults to + <varname>DefaultTimeoutStartSec=</varname> from the manager + configuration file (see + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + </para></listitem> + </varlistentry> + </variablelist> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.target.xml b/man/systemd.target.xml index e2cdfd83c3..3b8ec165e2 100644 --- a/man/systemd.target.xml +++ b/man/systemd.target.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,87 +23,81 @@ --> <refentry id="systemd.target"> - <refentryinfo> - <title>systemd.target</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.target</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.target</refname> - <refpurpose>Target unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>target</replaceable>.target</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.target</literal> encodes information about - a target unit of systemd, which is used for grouping - units and as well-known synchronization points during - start-up.</para> - - <para>This unit type has no specific options. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the common options of all unit configuration - files. The common configuration items are configured - in the generic [Unit] and [Install] sections. A - separate [Target] section does not exist, since no - target-specific options may be configured.</para> - - <para>Target units do not offer any additional - functionality on top of the generic functionality - provided by units. They exist merely to group units via dependencies - (useful as boot targets), and to establish - standardized names for synchronization points used in - dependencies between units. Among other things, target - units are a more flexible replacement for SysV - runlevels in the classic SysV init system. (And for - compatibility reasons special - target units such as - <filename>runlevel3.target</filename> exist which are used by - the SysV runlevel compatibility code in systemd. See - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details).</para> - - <para>Unless <varname>DefaultDependencies=</varname> - is set to <option>false</option>, target units will - implicitly complement all configured dependencies of - type <varname>Wants=</varname>, - <varname>Requires=</varname>, - <varname>RequiresOverridable=</varname> with - dependencies of type <varname>After=</varname> if the - units in question also have - <varname>DefaultDependencies=true</varname>. - </para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd.target</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.target</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.target</refname> + <refpurpose>Target unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>target</replaceable>.target</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.target</literal> encodes information about a target unit + of systemd, which is used for grouping units and as well-known + synchronization points during start-up.</para> + + <para>This unit type has no specific options. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. A separate [Target] section does not exist, + since no target-specific options may be configured.</para> + + <para>Target units do not offer any additional functionality on + top of the generic functionality provided by units. They exist + merely to group units via dependencies (useful as boot targets), + and to establish standardized names for synchronization points + used in dependencies between units. Among other things, target + units are a more flexible replacement for SysV runlevels in the + classic SysV init system. (And for compatibility reasons special + target units such as <filename>runlevel3.target</filename> exist + which are used by the SysV runlevel compatibility code in systemd. + See + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details).</para> + + <para>Unless <varname>DefaultDependencies=</varname> is set to + <option>false</option>, target units will implicitly complement + all configured dependencies of type <varname>Wants=</varname>, + <varname>Requires=</varname>, + <varname>RequiresOverridable=</varname> with dependencies of type + <varname>After=</varname> if the units in question also have + <varname>DefaultDependencies=true</varname>. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.time.xml b/man/systemd.time.xml index 2e64089c29..da0729725d 100644 --- a/man/systemd.time.xml +++ b/man/systemd.time.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,288 +23,275 @@ <refentry id="systemd.time"> - <refentryinfo> - <title>systemd.time</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.time</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.time</refname> - <refpurpose>Time and date specifications</refpurpose> - </refnamediv> - - <refsect1> - <title>Description</title> - - <para>In systemd, timestamps, time spans, and calendar - events are displayed and may be specified in closely - related syntaxes.</para> - </refsect1> - - <refsect1> - <title>Displaying Time Spans</title> - - <para>Time spans refer to time durations. On display, - systemd will present time spans as a space-separated - series of time values each suffixed by a time - unit.</para> - - <programlisting>2h 30min</programlisting> - - <para>All specified time values are meant to be added - up. The above hence refers to 150 minutes.</para> - </refsect1> - - <refsect1> - <title>Parsing Time Spans</title> - - <para>When parsing, systemd will accept the same - time span syntax. Separating spaces may be omitted. The - following time units are understood:</para> - - <itemizedlist> - <listitem><para>usec, us</para></listitem> - <listitem><para>msec, ms</para></listitem> - <listitem><para>seconds, second, sec, s</para></listitem> - <listitem><para>minutes, minute, min, m</para></listitem> - <listitem><para>hours, hour, hr, h</para></listitem> - <listitem><para>days, day, d</para></listitem> - <listitem><para>weeks, week, w</para></listitem> - <listitem><para>months, month</para></listitem> - <listitem><para>years, year, y</para></listitem> - </itemizedlist> - - <para>If no time unit is specified, generally seconds - are assumed, but some exceptions exist and are marked - as such. In a few cases <literal>ns</literal>, - <literal>nsec</literal> is accepted too, where the - granularity of the time span allows for this.</para> - - <para>Examples for valid time span specifications:</para> - - <programlisting>2 h + <refentryinfo> + <title>systemd.time</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.time</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.time</refname> + <refpurpose>Time and date specifications</refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>In systemd, timestamps, time spans, and calendar events are + displayed and may be specified in closely related syntaxes.</para> + </refsect1> + + <refsect1> + <title>Displaying Time Spans</title> + + <para>Time spans refer to time durations. On display, systemd will + present time spans as a space-separated series of time values each + suffixed by a time unit.</para> + + <programlisting>2h 30min</programlisting> + + <para>All specified time values are meant to be added up. The + above hence refers to 150 minutes.</para> + </refsect1> + + <refsect1> + <title>Parsing Time Spans</title> + + <para>When parsing, systemd will accept the same time span syntax. + Separating spaces may be omitted. The following time units are + understood:</para> + + <itemizedlist> + <listitem><para>usec, us</para></listitem> + <listitem><para>msec, ms</para></listitem> + <listitem><para>seconds, second, sec, s</para></listitem> + <listitem><para>minutes, minute, min, m</para></listitem> + <listitem><para>hours, hour, hr, h</para></listitem> + <listitem><para>days, day, d</para></listitem> + <listitem><para>weeks, week, w</para></listitem> + <listitem><para>months, month</para></listitem> + <listitem><para>years, year, y</para></listitem> + </itemizedlist> + + <para>If no time unit is specified, generally seconds are assumed, + but some exceptions exist and are marked as such. In a few cases + <literal>ns</literal>, <literal>nsec</literal> is accepted too, + where the granularity of the time span allows for this.</para> + + <para>Examples for valid time span specifications:</para> + + <programlisting>2 h 2hours 48hr 1y 12month 55s500ms 300ms20s 5day</programlisting> - </refsect1> - - <refsect1> - <title>Displaying Timestamps</title> - - <para>Timestamps refer to specific, unique points in - time. On display, systemd will format these in the - local timezone as follows:</para> - - <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting> - - <para>The weekday is printed according to the locale - choice of the user.</para> - </refsect1> - - <refsect1> - <title>Parsing Timestamps</title> - - <para>When parsing systemd will accept a similar - timestamp syntax, but excluding any timezone - specification (this limitation might be removed - eventually). The weekday specification is optional, - but when the weekday is specified it must either be - in the abbreviated (<literal>Wed</literal>) or - non-abbreviated (<literal>Wednesday</literal>) English - language form (case does not matter), and is not - subject to the locale choice of the user. Either the - date, or the time part may be omitted, in which case - the current date or 00:00:00, resp., is assumed. The - seconds component of the time may also be omitted, in - which case ":00" is assumed. Year numbers may be - specified in full or may be abbreviated (omitting the - century).</para> - - <para>A timestamp is considered invalid if a weekday - is specified and the date does not actually match the - specified day of the week.</para> - - <para>When parsing, systemd will also accept a few - special placeholders instead of timestamps: - <literal>now</literal> may be used to refer to the - current time (or of the invocation of the command - that is currently executed). <literal>today</literal>, - <literal>yesterday</literal>, - <literal>tomorrow</literal> refer to 00:00:00 of the - current day, the day before or the next day, - respectively.</para> - - <para>When parsing, systemd will also accept relative - time specifications. A time span (see above) that is - prefixed with <literal>+</literal> is evaluated to the - current time plus the specified time - span. Correspondingly, a time span that is prefixed - with <literal>-</literal> is evaluated to the current - time minus the specified time span. Instead of - prefixing the time span with <literal>+</literal> or - <literal>-</literal>, it may also be suffixed with a - space and the word <literal>left</literal> or - <literal>ago</literal>.</para> - - <para>Finally, a timespan prefixed with - <literal>@</literal> is evaluated relative to the UNIX - time epoch 1st Jan, 1970, 00:00.</para> - - <para>Examples for valid timestamps and their - normalized form (assuming the current time was - 2012-11-23 18:15:22):</para> - - <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13 + </refsect1> + + <refsect1> + <title>Displaying Timestamps</title> + + <para>Timestamps refer to specific, unique points in time. On + display, systemd will format these in the local timezone as + follows:</para> + + <programlisting>Fri 2012-11-23 23:02:15 CET</programlisting> + + <para>The weekday is printed according to the locale choice of the + user.</para> + </refsect1> + + <refsect1> + <title>Parsing Timestamps</title> + + <para>When parsing systemd will accept a similar timestamp syntax, + but excluding any timezone specification (this limitation might be + removed eventually). The weekday specification is optional, but + when the weekday is specified it must either be in the abbreviated + (<literal>Wed</literal>) or non-abbreviated + (<literal>Wednesday</literal>) English language form (case does + not matter), and is not subject to the locale choice of the user. + Either the date, or the time part may be omitted, in which case + the current date or 00:00:00, resp., is assumed. The seconds + component of the time may also be omitted, in which case ":00" is + assumed. Year numbers may be specified in full or may be + abbreviated (omitting the century).</para> + + <para>A timestamp is considered invalid if a weekday is specified + and the date does not actually match the specified day of the + week.</para> + + <para>When parsing, systemd will also accept a few special + placeholders instead of timestamps: <literal>now</literal> may be + used to refer to the current time (or of the invocation of the + command that is currently executed). <literal>today</literal>, + <literal>yesterday</literal>, <literal>tomorrow</literal> refer to + 00:00:00 of the current day, the day before or the next day, + respectively.</para> + + <para>When parsing, systemd will also accept relative time + specifications. A time span (see above) that is prefixed with + <literal>+</literal> is evaluated to the current time plus the + specified time span. Correspondingly, a time span that is prefixed + with <literal>-</literal> is evaluated to the current time minus + the specified time span. Instead of prefixing the time span with + <literal>+</literal> or <literal>-</literal>, it may also be + suffixed with a space and the word <literal>left</literal> or + <literal>ago</literal>.</para> + + <para>Finally, a timespan prefixed with <literal>@</literal> is + evaluated relative to the UNIX time epoch 1st Jan, 1970, + 00:00.</para> + + <para>Examples for valid timestamps and their normalized form + (assuming the current time was 2012-11-23 18:15:22):</para> + + <programlisting>Fri 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13 2012-11-23 11:12:13 → Fri 2012-11-23 11:12:13 - 2012-11-23 → Fri 2012-11-23 00:00:00 - 12-11-23 → Fri 2012-11-23 00:00:00 - 11:12:13 → Fri 2012-11-23 11:12:13 - 11:12 → Fri 2012-11-23 11:12:00 - now → Fri 2012-11-23 18:15:22 - today → Fri 2012-11-23 00:00:00 - yesterday → Fri 2012-11-22 00:00:00 - tomorrow → Fri 2012-11-24 00:00:00 - +3h30min → Fri 2012-11-23 21:45:22 - -5s → Fri 2012-11-23 18:15:17 - 11min ago → Fri 2012-11-23 18:04:22 - @1395716396 → Tue 2014-03-25 03:59:56</programlisting> - - <para>Note that timestamps printed by systemd will not - be parsed correctly by systemd, as the timezone - specification is not accepted, and printing timestamps - is subject to locale settings for the weekday while - parsing only accepts English weekday names.</para> - - <para>In some cases, systemd will display a relative - timestamp (relative to the current time, or the time - of invocation of the command) instead or in addition - to an absolute timestamp as described above. A - relative timestamp is formatted as follows:</para> - - <para>2 months 5 days ago</para> - - <para>Note that any relative timestamp will also parse - correctly where a timestamp is expected. (see above)</para> - </refsect1> - - <refsect1> - <title>Calendar Events</title> - - <para>Calendar events may be used to refer to one or - more points in time in a single expression. They form - a superset of the absolute timestamps explained above:</para> - - <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting> - - <para>The above refers to 11:12:13 of the first or - fifth day of any month of the year 2012, but only if that - day is a Thursday or Friday.</para> - - <para>The weekday specification is optional. If - specified, it should consist of one or more English - language weekday names, either in the abbreviated - (Wed) or non-abbreviated (Wednesday) form (case does - not matter), separated by commas. Specifying two - weekdays separated by <literal>-</literal> refers to a - range of continuous weekdays. <literal>,</literal> and - <literal>-</literal> may be combined freely.</para> - - <para>In the date and time specifications, any - component may be specified as <literal>*</literal> in - which case any value will match. Alternatively, each - component can be specified as a list of values separated - by commas. Values may also be suffixed with - <literal>/</literal> and a repetition value, which - indicates that the value and all values plus multiples - of the repetition value are matched.</para> - - <para>Either time or date specification may be - omitted, in which case the current day and 00:00:00 is - implied, respectively. If the second component is not - specified, <literal>:00</literal> is assumed.</para> - - <para>Timezone names may not be specified.</para> - - <para>The special expressions - <literal>minutely</literal>, - <literal>hourly</literal>, <literal>daily</literal>, - <literal>monthly</literal>, <literal>weekly</literal>, - <literal>yearly</literal>, - <literal>quarterly</literal>, - <literal>semiannually</literal> may be used as - calendar events which refer to - <literal>*-*-* *:*:00</literal>, - <literal>*-*-* *:00:00</literal>, - <literal>*-*-* 00:00:00</literal>, - <literal>*-*-01 00:00:00</literal>, - <literal>Mon *-*-* 00:00:00</literal>, - <literal>*-01-01 00:00:00</literal>, - <literal>*-01,04,07,10-01 00:00:0</literal> and - <literal>*-01,07-01 00:00:00</literal> respectively. - </para> - - <para>Examples for valid timestamps and their - normalized form:</para> + 2012-11-23 → Fri 2012-11-23 00:00:00 + 12-11-23 → Fri 2012-11-23 00:00:00 + 11:12:13 → Fri 2012-11-23 11:12:13 + 11:12 → Fri 2012-11-23 11:12:00 + now → Fri 2012-11-23 18:15:22 + today → Fri 2012-11-23 00:00:00 + yesterday → Fri 2012-11-22 00:00:00 + tomorrow → Fri 2012-11-24 00:00:00 + +3h30min → Fri 2012-11-23 21:45:22 + -5s → Fri 2012-11-23 18:15:17 + 11min ago → Fri 2012-11-23 18:04:22 + @1395716396 → Tue 2014-03-25 03:59:56</programlisting> + + <para>Note that timestamps printed by systemd will not be parsed + correctly by systemd, as the timezone specification is not + accepted, and printing timestamps is subject to locale settings + for the weekday while parsing only accepts English weekday + names.</para> + + <para>In some cases, systemd will display a relative timestamp + (relative to the current time, or the time of invocation of the + command) instead or in addition to an absolute timestamp as + described above. A relative timestamp is formatted as + follows:</para> + + <para>2 months 5 days ago</para> + + <para>Note that any relative timestamp will also parse correctly + where a timestamp is expected. (see above)</para> + </refsect1> + + <refsect1> + <title>Calendar Events</title> + + <para>Calendar events may be used to refer to one or more points + in time in a single expression. They form a superset of the + absolute timestamps explained above:</para> + + <programlisting>Thu,Fri 2012-*-1,5 11:12:13</programlisting> + + <para>The above refers to 11:12:13 of the first or fifth day of + any month of the year 2012, but only if that day is a Thursday or + Friday.</para> + + <para>The weekday specification is optional. If specified, it + should consist of one or more English language weekday names, + either in the abbreviated (Wed) or non-abbreviated (Wednesday) + form (case does not matter), separated by commas. Specifying two + weekdays separated by <literal>-</literal> refers to a range of + continuous weekdays. <literal>,</literal> and <literal>-</literal> + may be combined freely.</para> + + <para>In the date and time specifications, any component may be + specified as <literal>*</literal> in which case any value will + match. Alternatively, each component can be specified as a list of + values separated by commas. Values may also be suffixed with + <literal>/</literal> and a repetition value, which indicates that + the value and all values plus multiples of the repetition value + are matched.</para> + + <para>Either time or date specification may be omitted, in which + case the current day and 00:00:00 is implied, respectively. If the + second component is not specified, <literal>:00</literal> is + assumed.</para> + + <para>Timezone names may not be specified.</para> + + <para>The special expressions + <literal>minutely</literal>, + <literal>hourly</literal>, <literal>daily</literal>, + <literal>monthly</literal>, <literal>weekly</literal>, + <literal>yearly</literal>, + <literal>quarterly</literal>, + <literal>semiannually</literal> may be used as + calendar events which refer to + <literal>*-*-* *:*:00</literal>, + <literal>*-*-* *:00:00</literal>, + <literal>*-*-* 00:00:00</literal>, + <literal>*-*-01 00:00:00</literal>, + <literal>Mon *-*-* 00:00:00</literal>, + <literal>*-01-01 00:00:00</literal>, + <literal>*-01,04,07,10-01 00:00:0</literal> and + <literal>*-01,07-01 00:00:00</literal> respectively. + </para> + + <para>Examples for valid timestamps and their + normalized form:</para> <programlisting> Sat,Thu,Mon-Wed,Sat-Sun → Mon-Thu,Sat,Sun *-*-* 00:00:00 Mon,Sun 12-*-* 2,1:23 → Mon,Sun 2012-*-* 01,02:23:00 - Wed *-1 → Wed *-*-01 00:00:00 - Wed-Wed,Wed *-1 → Wed *-*-01 00:00:00 - Wed, 17:48 → Wed *-*-* 17:48:00 + Wed *-1 → Wed *-*-01 00:00:00 + Wed-Wed,Wed *-1 → Wed *-*-01 00:00:00 + Wed, 17:48 → Wed *-*-* 17:48:00 Wed-Sat,Tue 12-10-15 1:2:3 → Tue-Sat 2012-10-15 01:02:03 - *-*-7 0:0:0 → *-*-07 00:00:00 - 10-15 → *-10-15 00:00:00 + *-*-7 0:0:0 → *-*-07 00:00:00 + 10-15 → *-10-15 00:00:00 monday *-12-* 17:00 → Mon *-12-* 17:00:00 Mon,Fri *-*-3,1,2 *:30:45 → Mon,Fri *-*-01,02,03 *:30:45 12,14,13,12:20,10,30 → *-*-* 12,13,14:10,20,30:00 mon,fri *-1/2-1,3 *:30:45 → Mon,Fri *-01/2-01,03 *:30:45 - 03-05 08:05:40 → *-03-05 08:05:40 - 08:05:40 → *-*-* 08:05:40 - 05:40 → *-*-* 05:40:00 + 03-05 08:05:40 → *-03-05 08:05:40 + 08:05:40 → *-*-* 08:05:40 + 05:40 → *-*-* 05:40:00 Sat,Sun 12-05 08:05:40 → Sat,Sun *-12-05 08:05:40 - Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40 - 2003-03-05 05:40 → 2003-03-05 05:40:00 - 2003-03-05 → 2003-03-05 00:00:00 - 03-05 → *-03-05 00:00:00 - hourly → *-*-* *:00:00 - daily → *-*-* 00:00:00 - monthly → *-*-01 00:00:00 - weekly → Mon *-*-* 00:00:00 - yearly → *-01-01 00:00:00 - annually → *-01-01 00:00:00 - *:2/3 → *-*-* *:02/3:00</programlisting> - - <para>Calendar events are used by timer units, see - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + Sat,Sun 08:05:40 → Sat,Sun *-*-* 08:05:40 + 2003-03-05 05:40 → 2003-03-05 05:40:00 + 2003-03-05 → 2003-03-05 00:00:00 + 03-05 → *-03-05 00:00:00 + hourly → *-*-* *:00:00 + daily → *-*-* 00:00:00 + monthly → *-*-01 00:00:00 + weekly → Mon *-*-* 00:00:00 + yearly → *-01-01 00:00:00 + annually → *-01-01 00:00:00 + *:2/3 → *-*-* *:02/3:00</programlisting> + + <para>Calendar events are used by timer units, see + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml index 55b458557f..317fbf1f2f 100644 --- a/man/systemd.timer.xml +++ b/man/systemd.timer.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,289 +23,232 @@ --> <refentry id="systemd.timer"> - <refentryinfo> - <title>systemd.timer</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.timer</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.timer</refname> - <refpurpose>Timer unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>timer</replaceable>.timer</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file whose name ends in - <literal>.timer</literal> encodes information about - a timer controlled and supervised by systemd, for - timer-based activation.</para> - - <para>This man page lists the configuration options - specific to this unit type. See - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the common options of all unit configuration - files. The common configuration items are configured - in the generic [Unit] and [Install] sections. The - timer specific configuration options are configured in - the [Timer] section.</para> - - <para>For each timer file, a matching unit file must - exist, describing the unit to activate when the timer - elapses. By default, a service by the same name as the - timer (except for the suffix) is activated. Example: a - timer file <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>Unless <varname>DefaultDependencies=</varname> - is set to <option>false</option>, all timer units will - implicitly have dependencies of type - <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> - <title>Options</title> - - <para>Timer files must include a [Timer] section, - which carries information about the timer it - defines. The options specific to the [Timer] section - of timer units are the following:</para> - - <variablelist class='unit-directives'> - <varlistentry> - <term><varname>OnActiveSec=</varname></term> - <term><varname>OnBootSec=</varname></term> - <term><varname>OnStartupSec=</varname></term> - <term><varname>OnUnitActiveSec=</varname></term> - <term><varname>OnUnitInactiveSec=</varname></term> - - <listitem><para>Defines monotonic timers - relative to different starting points: - <varname>OnActiveSec=</varname> defines a - timer relative to the moment the timer - itself is - activated. <varname>OnBootSec=</varname> - defines a timer relative to when the - machine was booted - up. <varname>OnStartupSec=</varname> - defines a timer relative to when - systemd was first - started. <varname>OnUnitActiveSec=</varname> - defines a timer relative to when the - unit the timer is activating was last - activated. <varname>OnUnitInactiveSec=</varname> - defines a timer relative to when the - unit the timer is activating was last - deactivated.</para> - - <para>Multiple directives may be - combined of the same and of different - types. For example, by combining - <varname>OnBootSec=</varname> and - <varname>OnUnitActiveSec=</varname>, it is - possible to define a timer that - elapses in regular intervals and - activates a specific service each - time.</para> - - <para>The arguments to the directives - are time spans configured in - seconds. Example: "OnBootSec=50" means - 50s after boot-up. The argument may - also include time units. Example: - "OnBootSec=5h 30min" means 5 hours and - 30 minutes after boot-up. For details - about the syntax of time spans, see - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <para>If a timer configured with - <varname>OnBootSec=</varname> or - <varname>OnStartupSec=</varname> is - already in the past when the timer - unit is activated, it will immediately - elapse and the configured unit is - started. This is not the case for - timers defined in the other - directives.</para> - - <para>These are monotonic timers, - independent of wall-clock time and timezones. If the - computer is temporarily suspended, the - monotonic clock stops too.</para> - - <para>If the empty string is assigned - to any of these options, the list of - timers is reset, and all prior - assignments will have no - effect.</para> - - <para>Note that timers do not - necessarily expire at the precise - time configured with these settings, - as they are subject to the - <varname>AccuracySec=</varname> - setting below.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><varname>OnCalendar=</varname></term> - - <listitem><para>Defines realtime - (i.e. wallclock) timers with calendar - event expressions. See - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for more information on the syntax of - calendar event expressions. Otherwise, - the semantics are similar to - <varname>OnActiveSec=</varname> and - related settings.</para> - - <para>Note that timers do not - necessarily expire at the precise - time configured with this setting, - as it is subject to the - <varname>AccuracySec=</varname> - setting below.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>AccuracySec=</varname></term> - - <listitem><para>Specify the accuracy - the timer shall elapse with. Defaults - to 1min. The timer is scheduled to - elapse within a time window starting - with the time specified in - <varname>OnCalendar=</varname>, - <varname>OnActiveSec=</varname>, - <varname>OnBootSec=</varname>, - <varname>OnStartupSec=</varname>, - <varname>OnUnitActiveSec=</varname> or - <varname>OnUnitInactiveSec=</varname> - and ending the time configured with - <varname>AccuracySec=</varname> - later. Within this time window, the - expiry time will be placed at a - host-specific, randomized but stable - position that is synchronized between - all local timer units. This is done in - order to distribute the wake-up time - in networked installations, as well as - optimizing power consumption to - suppress unnecessary CPU wake-ups. To - get best accuracy, set this option to - 1us. Note that the timer is still - subject to the timer slack configured - via - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s - <varname>TimerSlackNSec=</varname> - setting. See - <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. To optimize power - consumption, make sure to set this - value as high as possible and as low - as necessary.</para></listitem> - </varlistentry> - <varlistentry> - <term><varname>Unit=</varname></term> - - <listitem><para>The unit to activate - when this timer elapses. The argument is a - unit name, whose suffix is not - <literal>.timer</literal>. If not - specified, this value defaults to a - service that has the same name as the - timer unit, except for the - suffix. (See above.) It is recommended - that the unit name that is activated - and the unit name of the timer unit - are named identically, except for the - suffix.</para></listitem> - </varlistentry> - - - <varlistentry> - <term><varname>Persistent=</varname></term> - - <listitem><para>Takes a boolean - argument. If true, the time when the - service unit was last triggered is - stored on disk. When the timer is - activated, the service unit is - triggered immediately if it would have - been triggered at least once 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>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>WakeSystem=</varname></term> - - <listitem><para>Takes a boolean - argument. If true, an elapsing timer - will cause the system to resume from - suspend, should it be suspended and if - the system supports this. Note that - this option will only make sure the - system resumes on the appropriate - times, it will not take care of - suspending it again after any work - that is to be done is - finished. Defaults to - <varname>false</varname>.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> + <refentryinfo> + <title>systemd.timer</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.timer</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.timer</refname> + <refpurpose>Timer unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>timer</replaceable>.timer</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.timer</literal> encodes information about a timer + controlled and supervised by systemd, for timer-based + activation.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. The timer specific configuration options are + configured in the [Timer] section.</para> + + <para>For each timer file, a matching unit file must exist, + describing the unit to activate when the timer elapses. By + default, a service by the same name as the timer (except for the + suffix) is activated. Example: a timer file + <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>Unless <varname>DefaultDependencies=</varname> is set to + <option>false</option>, all timer units will implicitly have + dependencies of type <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> + <title>Options</title> + + <para>Timer files must include a [Timer] section, which carries + information about the timer it defines. The options specific to + the [Timer] section of timer units are the following:</para> + + <variablelist class='unit-directives'> + <varlistentry> + <term><varname>OnActiveSec=</varname></term> + <term><varname>OnBootSec=</varname></term> + <term><varname>OnStartupSec=</varname></term> + <term><varname>OnUnitActiveSec=</varname></term> + <term><varname>OnUnitInactiveSec=</varname></term> + + <listitem><para>Defines monotonic timers relative to different + starting points: <varname>OnActiveSec=</varname> defines a + timer relative to the moment the timer itself is activated. + <varname>OnBootSec=</varname> defines a timer relative to when + the machine was booted up. <varname>OnStartupSec=</varname> + defines a timer relative to when systemd was first started. + <varname>OnUnitActiveSec=</varname> defines a timer relative + to when the unit the timer is activating was last activated. + <varname>OnUnitInactiveSec=</varname> defines a timer relative + to when the unit the timer is activating was last + deactivated.</para> + + <para>Multiple directives may be combined of the same and of + different types. For example, by combining + <varname>OnBootSec=</varname> and + <varname>OnUnitActiveSec=</varname>, it is possible to define + a timer that elapses in regular intervals and activates a + specific service each time.</para> + + <para>The arguments to the directives are time spans + configured in seconds. Example: "OnBootSec=50" means 50s after + boot-up. The argument may also include time units. Example: + "OnBootSec=5h 30min" means 5 hours and 30 minutes after + boot-up. For details about the syntax of time spans, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>If a timer configured with <varname>OnBootSec=</varname> + or <varname>OnStartupSec=</varname> is already in the past + when the timer unit is activated, it will immediately elapse + and the configured unit is started. This is not the case for + timers defined in the other directives.</para> + + <para>These are monotonic timers, independent of wall-clock + time and timezones. If the computer is temporarily suspended, + the monotonic clock stops too.</para> + + <para>If the empty string is assigned to any of these options, + the list of timers is reset, and all prior assignments will + have no effect.</para> + + <para>Note that timers do not necessarily expire at the + precise time configured with these settings, as they are + subject to the <varname>AccuracySec=</varname> setting + below.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><varname>OnCalendar=</varname></term> + + <listitem><para>Defines realtime (i.e. wallclock) timers with + calendar event expressions. See + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for more information on the syntax of calendar event + expressions. Otherwise, the semantics are similar to + <varname>OnActiveSec=</varname> and related settings.</para> + + <para>Note that timers do not necessarily expire at the + precise time configured with this setting, as it is subject to + the <varname>AccuracySec=</varname> setting + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AccuracySec=</varname></term> + + <listitem><para>Specify the accuracy the timer shall elapse + with. Defaults to 1min. The timer is scheduled to elapse + within a time window starting with the time specified in + <varname>OnCalendar=</varname>, + <varname>OnActiveSec=</varname>, + <varname>OnBootSec=</varname>, + <varname>OnStartupSec=</varname>, + <varname>OnUnitActiveSec=</varname> or + <varname>OnUnitInactiveSec=</varname> and ending the time + configured with <varname>AccuracySec=</varname> later. Within + this time window, the expiry time will be placed at a + host-specific, randomized but stable position that is + synchronized between all local timer units. This is done in + order to distribute the wake-up time in networked + installations, as well as optimizing power consumption to + suppress unnecessary CPU wake-ups. To get best accuracy, set + this option to 1us. Note that the timer is still subject to + the timer slack configured via + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s + <varname>TimerSlackNSec=</varname> setting. See + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details. To optimize power consumption, make sure to set + this value as high as possible and as low as + necessary.</para></listitem> + </varlistentry> + <varlistentry> + <term><varname>Unit=</varname></term> + + <listitem><para>The unit to activate when this timer elapses. + The argument is a unit name, whose suffix is not + <literal>.timer</literal>. If not specified, this value + defaults to a service that has the same name as the timer + unit, except for the suffix. (See above.) It is recommended + that the unit name that is activated and the unit name of the + timer unit are named identically, except for the + suffix.</para></listitem> + </varlistentry> + + + <varlistentry> + <term><varname>Persistent=</varname></term> + + <listitem><para>Takes a boolean argument. If true, the time + when the service unit was last triggered is stored on disk. + When the timer is activated, the service unit is triggered + immediately if it would have been triggered at least once + 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>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>WakeSystem=</varname></term> + + <listitem><para>Takes a boolean argument. If true, an elapsing + timer will cause the system to resume from suspend, should it + be suspended and if the system supports this. Note that this + option will only make sure the system resumes on the + appropriate times, it will not take care of suspending it + again after any work that is to be done is finished. Defaults + to <varname>false</varname>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 9704d6f227..4dae631389 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -1,6 +1,6 @@ <?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" [ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY % entities SYSTEM "custom-entities.ent" > %entities; ]> @@ -26,51 +26,51 @@ <refentry id="systemd.unit"> - <refentryinfo> - <title>systemd.unit</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.unit</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd.unit</refname> - <refpurpose>Unit configuration</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename><replaceable>service</replaceable>.service</filename>, - <filename><replaceable>socket</replaceable>.socket</filename>, - <filename><replaceable>device</replaceable>.device</filename>, - <filename><replaceable>mount</replaceable>.mount</filename>, - <filename><replaceable>automount</replaceable>.automount</filename>, - <filename><replaceable>swap</replaceable>.swap</filename>, - <filename><replaceable>target</replaceable>.target</filename>, - <filename><replaceable>path</replaceable>.path</filename>, - <filename><replaceable>timer</replaceable>.timer</filename>, - <filename><replaceable>snapshot</replaceable>.snapshot</filename>, - <filename><replaceable>slice</replaceable>.slice</filename>, - <filename><replaceable>scope</replaceable>.scope</filename></para> - - <para><literallayout><filename>/etc/systemd/system/*</filename> + <refentryinfo> + <title>systemd.unit</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.unit</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.unit</refname> + <refpurpose>Unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>service</replaceable>.service</filename>, + <filename><replaceable>socket</replaceable>.socket</filename>, + <filename><replaceable>device</replaceable>.device</filename>, + <filename><replaceable>mount</replaceable>.mount</filename>, + <filename><replaceable>automount</replaceable>.automount</filename>, + <filename><replaceable>swap</replaceable>.swap</filename>, + <filename><replaceable>target</replaceable>.target</filename>, + <filename><replaceable>path</replaceable>.path</filename>, + <filename><replaceable>timer</replaceable>.timer</filename>, + <filename><replaceable>snapshot</replaceable>.snapshot</filename>, + <filename><replaceable>slice</replaceable>.slice</filename>, + <filename><replaceable>scope</replaceable>.scope</filename></para> + + <para><literallayout><filename>/etc/systemd/system/*</filename> <filename>/run/systemd/system/*</filename> <filename>/usr/lib/systemd/system/*</filename> <filename>...</filename> - </literallayout></para> + </literallayout></para> - <para><literallayout><filename>$XDG_CONFIG_HOME/systemd/user/*</filename> + <para><literallayout><filename>$XDG_CONFIG_HOME/systemd/user/*</filename> <filename>$HOME/.config/systemd/user/*</filename> <filename>/etc/systemd/user/*</filename> <filename>$XDG_RUNTIME_DIR/systemd/user/*</filename> @@ -79,1513 +79,1213 @@ <filename>$HOME/.local/share/systemd/user/*</filename> <filename>/usr/lib/systemd/user/*</filename> <filename>...</filename> - </literallayout></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>A unit configuration file encodes information - about a service, a socket, a device, a mount point, an - automount point, a swap file or partition, a start-up - target, a watched file system path, a timer controlled - and supervised by - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - a temporary system state snapshot, a resource - management slice or a group of externally created - processes. The syntax is inspired by <ulink - url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG - Desktop Entry Specification</ulink> - <filename>.desktop</filename> files, which are in turn - inspired by Microsoft Windows - <filename>.ini</filename> files.</para> - - <para>This man page lists the common configuration - options of all the unit types. These options need to - be configured in the [Unit] or [Install] - sections of the unit files.</para> - - <para>In addition to the generic [Unit] and [Install] - sections described here, each unit may have a - type-specific section, e.g. [Service] for a service - unit. See the respective man pages for more - information: - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para> - - <para>Various settings are allowed to be specified - more than once, in which case the interpretation - depends on the setting. Often, multiple settings form - a list, and setting to an empty value "resets", which - means that previous assignments are ignored. When this - is allowed, it is mentioned in the description of the - setting. Note that using multiple assignments to the - same value makes the unit file incompatible with - parsers for the XDG <filename>.desktop</filename> file - format.</para> - - <para>Unit files are loaded from a set of paths - determined during compilation, described in the next section. - </para> - - <para>Unit files may contain additional options on top - of those listed here. If systemd encounters an unknown - option, it will write a warning log message but - continue loading the unit. If an option or section name - is prefixed with <option>X-</option>, it is ignored - completely by systemd. Options within an ignored - section do not need the prefix. Applications may use - this to include additional information in the unit - files.</para> - - <para>Boolean arguments used in unit files can be - written in various formats. For positive settings the - strings <option>1</option>, <option>yes</option>, - <option>true</option> and <option>on</option> are - equivalent. For negative settings, the strings - <option>0</option>, <option>no</option>, - <option>false</option> and <option>off</option> are - equivalent.</para> - - <para>Time span values encoded in unit files can be - written in various formats. A stand-alone number - specifies a time in seconds. If suffixed with a time - unit, the unit is honored. A concatenation of multiple - values with units is supported, in which case the - values are added up. Example: "50" refers to 50 - seconds; "2min 200ms" refers to 2 minutes plus 200 - milliseconds, i.e. 120200ms. The following time units - are understood: s, min, h, d, w, ms, us. For details - see - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - - <para>Empty lines and lines starting with # or ; are - ignored. This may be used for commenting. Lines ending - in a backslash are concatenated with the following - line while reading and the backslash is replaced by a - space character. This may be used to wrap long lines.</para> - - <para>Along with a unit file - <filename>foo.service</filename>, the directory - <filename>foo.service.wants/</filename> may exist. All - unit files symlinked from such a directory are - implicitly added as dependencies of type - <varname>Wants=</varname> to the unit. This is useful - to hook units into the start-up of other units, - without having to modify their unit files. For details - about the semantics of <varname>Wants=</varname>, see - below. The preferred way to create symlinks in the - <filename>.wants/</filename> directory of a unit file - is with the <command>enable</command> command of the - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool which reads information from the [Install] - section of unit files (see below). A similar - functionality exists for <varname>Requires=</varname> - type dependencies as well, the directory suffix is - <filename>.requires/</filename> in this case.</para> - - <para>Along with a unit file - <filename>foo.service</filename>, a directory - <filename>foo.service.d/</filename> may exist. All - files with the suffix <literal>.conf</literal> from - this directory will be parsed after the file itself is - parsed. This is useful to alter or add configuration - settings to a unit, without having to modify their - unit files. Make sure that the file that is included - has the appropriate section headers before any - directive. Note that for instanced units this logic - will first look for the instance - <literal>.d/</literal> subdirectory and read its - <literal>.conf</literal> files, followed by the - template <literal>.d/</literal> subdirectory and reads - its <literal>.conf</literal> files.</para> - - <!-- Note that we do not document .include here, as we - consider it mostly obsolete, and want people to - use .d/ drop-ins instead. --> - - <para>Note that while systemd offers a flexible - dependency system between units it is recommended to - use this functionality only sparingly and instead rely - on techniques such as bus-based or socket-based - activation which make dependencies implicit, resulting - in a both simpler and more flexible system.</para> - - <para>Some unit names reflect paths existing in the - file system namespace. Example: a device unit - <filename>dev-sda.device</filename> refers to a device - with the device node <filename noindex='true'>/dev/sda</filename> in - the file system namespace. If this applies, a special - way to escape the path name is used, so that the - result is usable as part of a filename. Basically, - given a path, "/" is replaced by "-" and all other - characters which are not ASCII alphanumerics are - replaced by C-style "\x2d" escapes (except that "_" - is never replaced and "." is only replaced when it - would be the first character in the escaped path). - The root directory "/" is encoded as single dash, - while otherwise the initial and ending "/" are removed - from all paths during transformation. This escaping - is reversible. Properly escaped paths can be generated - using the <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry> - command.</para> - - <para>Optionally, units may be instantiated from a - template file at runtime. This allows creation of - multiple units from a single configuration file. If - systemd looks for a unit configuration file, it will - first search for the literal unit name in the - file system. If that yields no success and the unit - name contains an <literal>@</literal> character, systemd will look for a - unit template that shares the same name but with the - instance string (i.e. the part between the <literal>@</literal> character - and the suffix) removed. Example: if a service - <filename>getty@tty3.service</filename> is requested - and no file by that name is found, systemd will look - for <filename>getty@.service</filename> and - instantiate a service from that configuration file if - it is found.</para> - - <para>To refer to the instance string from - within the configuration file you may use the special - <literal>%i</literal> specifier in many of the - configuration options. See below for details.</para> - - <para>If a unit file is empty (i.e. has the file size - 0) or is symlinked to <filename>/dev/null</filename>, - its configuration will not be loaded and it appears - with a load state of <literal>masked</literal>, and - cannot be activated. Use this as an effective way to - fully disable a unit, making it impossible to start it - even manually.</para> - - <para>The unit file format is covered by the - <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface - Stability Promise</ulink>.</para> - - </refsect1> - - <refsect1> - <title>Unit Load Path</title> - - <para>Unit files are loaded from a set of paths - determined during compilation, described in the two - tables below. Unit files found in directories listed - earlier override files with the same name in - directories lower in the list.</para> - - <para>When systemd is running in user mode - (<option>--user</option>) and the variable - <varname>$SYSTEMD_UNIT_PATH</varname> is set, the - contents of this variable overrides the unit load - path. If <varname>$SYSTEMD_UNIT_PATH</varname> ends - with an empty component (<literal>:</literal>), the - usual unit load path will be appended to the contents - of the variable.</para> - - <table> - <title> - Load path when running in system mode (<option>--system</option>). - </title> - - <tgroup cols='2'> - <colspec colname='path' /> - <colspec colname='expl' /> - <thead> - <row> - <entry>Path</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry><filename>/etc/systemd/system</filename></entry> - <entry>Local configuration</entry> - </row> - <row> - <entry><filename>/run/systemd/system</filename></entry> - <entry>Runtime units</entry> - </row> - <row> - <entry><filename>/usr/lib/systemd/system</filename></entry> - <entry>Units of installed packages</entry> - </row> - </tbody> - </tgroup> - </table> - - <table> - <title> - Load path when running in user mode (<option>--user</option>). - </title> - - <tgroup cols='2'> - <colspec colname='path' /> - <colspec colname='expl' /> - <thead> - <row> - <entry>Path</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry> - <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry> - </row> - <row> - <entry><filename>$HOME/.config/systemd/user</filename></entry> - <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry> - </row> - <row> - <entry><filename>/etc/systemd/user</filename></entry> - <entry>Local configuration</entry> - </row> - <row> - <entry><filename>$XDG_RUNTIME_DIR/systemd/user</filename></entry> - <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)</entry> - </row> - <row> - <entry><filename>/run/systemd/user</filename></entry> - <entry>Runtime units</entry> - </row> - <row> - <entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry> - <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</entry> - </row> - <row> - <entry><filename>$HOME/.local/share/systemd/user</filename></entry> - <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)</entry> - </row> - <row> - <entry><filename>/usr/lib/systemd/user</filename></entry> - <entry>Units of packages that have been installed system-wide</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Additional units might be loaded into systemd - ("linked") from directories not on the unit load - path. See the <command>link</command> command for - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Also, - some units are dynamically created via generators - <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/Generators/">Generators</ulink>. - </para> - </refsect1> - - <refsect1> - <title>[Unit] Section Options</title> - - <para>Unit file may include a [Unit] section, which - carries generic information about the unit that is not - dependent on the type of unit:</para> - - <variablelist class='unit-directives'> - - <varlistentry> - <term><varname>Description=</varname></term> - <listitem><para>A free-form string - describing the unit. This is intended - for use in UIs to show descriptive - information along with the unit - name. The description should contain a name - that means something to the end user. - <literal>Apache2 Web Server</literal> is a good - example. Bad examples are - <literal>high-performance light-weight HTTP - server</literal> (too generic) or - <literal>Apache2</literal> (too specific and - meaningless for people who do not know - Apache).</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Documentation=</varname></term> - <listitem><para>A space-separated list - of URIs referencing documentation for - this unit or its - configuration. Accepted are only URIs - of the types - <literal>http://</literal>, - <literal>https://</literal>, - <literal>file:</literal>, - <literal>info:</literal>, - <literal>man:</literal>. For more - information about the syntax of these - URIs, see - <citerefentry project='man-pages'><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The - URIs should be listed in order of - relevance, starting with the most - relevant. It is a good idea to first - reference documentation that explains - what the unit's purpose is, followed - by how it is configured, followed by - any other related documentation. This - option may be specified more than once, - in which case the specified list of - URIs is merged. If the empty string is - assigned to this option, the list is - reset and all prior assignments will - have no effect.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Requires=</varname></term> - - <listitem><para>Configures requirement - dependencies on other units. If this - unit gets activated, the units listed - here will be activated as well. If one - of the other units gets deactivated or - its activation fails, this unit will - be deactivated. This option may be - specified more than once or multiple - space-separated units may be specified - in one option in which case - requirement dependencies for all - listed names will be created. Note - that requirement dependencies do not - influence the order in which services - are started or stopped. This has to be - configured independently with the - <varname>After=</varname> or - <varname>Before=</varname> options. If - a unit - <filename>foo.service</filename> - requires a unit - <filename>bar.service</filename> as - configured with - <varname>Requires=</varname> and no - ordering is configured with - <varname>After=</varname> or - <varname>Before=</varname>, then both - units will be started simultaneously - and without any delay between them if - <filename>foo.service</filename> is - activated. Often it is a better choice - to use <varname>Wants=</varname> - instead of - <varname>Requires=</varname> in order - to achieve a system that is more - robust when dealing with failing - services.</para> - - <para>Note that dependencies of this - type may also be configured outside of - the unit configuration file by - adding a symlink to a - <filename>.requires/</filename> directory - accompanying the unit file. For - details see above.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RequiresOverridable=</varname></term> - - <listitem><para>Similar to - <varname>Requires=</varname>. - Dependencies listed in - <varname>RequiresOverridable=</varname> - which cannot be fulfilled or fail to - start are ignored if the startup was - explicitly requested by the user. If - the start-up was pulled in indirectly - by some dependency or automatic - start-up of units that is not - requested by the user, this dependency - must be fulfilled and otherwise the - transaction fails. Hence, this option - may be used to configure dependencies - that are normally honored unless the - user explicitly starts up the unit, in - which case whether they failed or not - is irrelevant.</para></listitem> - - </varlistentry> - <varlistentry> - <term><varname>Requisite=</varname></term> - <term><varname>RequisiteOverridable=</varname></term> - - <listitem><para>Similar to - <varname>Requires=</varname> and - <varname>RequiresOverridable=</varname>, - respectively. However, if the units - listed here are not started already, - they will not be started and the - transaction will fail immediately. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Wants=</varname></term> - - <listitem><para>A weaker version of - <varname>Requires=</varname>. Units - listed in this option will be started - if the configuring unit is. However, - if the listed units fail to start - or cannot be added to the transaction, - this has no impact on the validity of - the transaction as a whole. This is - the recommended way to hook start-up - of one unit to the start-up of another - unit.</para> - - <para>Note that dependencies of this - type may also be configured outside of - the unit configuration file by adding - symlinks to a - <filename>.wants/</filename> directory - accompanying the unit file. For - details, see above.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>BindsTo=</varname></term> - - <listitem><para>Configures requirement - dependencies, very similar in style to - <varname>Requires=</varname>, however - in addition to this behavior, it also - declares that this unit is stopped - when any of the units listed suddenly - disappears. Units can suddenly, - unexpectedly disappear if a service - terminates on its own choice, a device - is unplugged or a mount point - unmounted without involvement of - systemd.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PartOf=</varname></term> - - <listitem><para>Configures dependencies - similar to <varname>Requires=</varname>, - but limited to stopping and restarting - of units. When systemd stops or restarts - the units listed here, the action is - propagated to this unit. - Note that this is a one-way dependency — - changes to this unit do not affect the - listed units. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Conflicts=</varname></term> - - <listitem><para>A space-separated list - of unit names. Configures negative - requirement dependencies. If a unit - has a <varname>Conflicts=</varname> - setting on another unit, starting the - former will stop the latter and vice - versa. Note that this setting is - independent of and orthogonal to the - <varname>After=</varname> and - <varname>Before=</varname> ordering - dependencies.</para> - - <para>If a unit A that conflicts with - a unit B is scheduled to be started at - the same time as B, the transaction - will either fail (in case both are - required part of the transaction) or - be modified to be fixed (in case one - or both jobs are not a required part - of the transaction). In the latter - case, the job that is not the required - will be removed, or in case both are - not required, the unit that conflicts - will be started and the unit that is - conflicted is - stopped.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Before=</varname></term> - <term><varname>After=</varname></term> - - <listitem><para>A space-separated list - of unit names. Configures ordering - dependencies between units. If a unit - <filename>foo.service</filename> - contains a setting - <option>Before=bar.service</option> - and both units are being started, - <filename>bar.service</filename>'s - start-up is delayed until - <filename>foo.service</filename> is - started up. Note that this setting is - independent of and orthogonal to the - requirement dependencies as configured - by <varname>Requires=</varname>. It is - a common pattern to include a unit - name in both the - <varname>After=</varname> and - <varname>Requires=</varname> option, in - which case the unit listed will be - started before the unit that is - configured with these options. This - option may be specified more than - once, in which case ordering - dependencies for all listed names are - created. <varname>After=</varname> is - the inverse of - <varname>Before=</varname>, i.e. while - <varname>After=</varname> ensures that - the configured unit is started after - the listed unit finished starting up, - <varname>Before=</varname> ensures the - opposite, i.e. that the configured - unit is fully started up before the - listed unit is started. Note that when - two units with an ordering dependency - 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. </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>OnFailure=</varname></term> - - <listitem><para>A space-separated list - of one or more units that are - activated when this unit enters the - <literal>failed</literal> - state.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PropagatesReloadTo=</varname></term> - <term><varname>ReloadPropagatedFrom=</varname></term> - - <listitem><para>A space-separated list - of one or more units where reload - requests on this unit will be - propagated to, or reload requests on - the other unit will be propagated to - this unit, respectively. Issuing a - reload request on a unit will - automatically also enqueue a reload - request on all units that the reload - request shall be propagated to via - these two settings.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>JoinsNamespaceOf=</varname></term> - - <listitem><para>For units that start - processes (such as service units), - lists one or more other units whose - network and/or temporary file - namespace to join. This only applies - to unit types which support the - <varname>PrivateNetwork=</varname> and - <varname>PrivateTmp=</varname> - directives (see - <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 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 - <varname>PrivateNetwork=</varname> - and/or <varname>PrivateTmp=</varname> - is enabled for both the unit that - joins the namespace and the unit whose - namespace is joined.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RequiresMountsFor=</varname></term> - - <listitem><para>Takes a - space-separated list of absolute - paths. Automatically adds dependencies - of type <varname>Requires=</varname> - and <varname>After=</varname> for all - mount units required to access the - specified path.</para> - - <para>Mount points marked with - <option>noauto</option> are not - mounted automatically and will be - ignored for the purposes of this - option. If such a mount should be a - requirement for this unit, - direct dependencies on the mount - units may be added - (<varname>Requires=</varname> and - <varname>After=</varname> or - some other combination). - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>OnFailureJobMode=</varname></term> - - <listitem><para>Takes a value of - <literal>fail</literal>, - <literal>replace</literal>, - <literal>replace-irreversibly</literal>, - <literal>isolate</literal>, - <literal>flush</literal>, - <literal>ignore-dependencies</literal> - or - <literal>ignore-requirements</literal>. Defaults - to - <literal>replace</literal>. Specifies - how the units listed in - <varname>OnFailure=</varname> will be - enqueued. See - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s - <option>--job-mode=</option> option - for details on the possible values. If - this is set to - <literal>isolate</literal>, only a - single unit may be listed in - <varname>OnFailure=</varname>..</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>IgnoreOnIsolate=</varname></term> - - <listitem><para>Takes a boolean - argument. If <option>true</option>, - this unit will not be stopped when - isolating another unit. Defaults to - <option>false</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>IgnoreOnSnapshot=</varname></term> - - <listitem><para>Takes a boolean - argument. If <option>true</option>, - this unit will not be included in - snapshots. Defaults to - <option>true</option> for device and - snapshot units, <option>false</option> - for the others.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>StopWhenUnneeded=</varname></term> - - <listitem><para>Takes a boolean - argument. If <option>true</option>, - this unit will be stopped when it is - no longer used. Note that in order to - minimize the work to be executed, - systemd will not stop units by default - unless they are conflicting with other - units, or the user explicitly - requested their shut down. If this - option is set, a unit will be - automatically cleaned up if no other - active unit requires it. Defaults to - <option>false</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>RefuseManualStart=</varname></term> - <term><varname>RefuseManualStop=</varname></term> - - <listitem><para>Takes a boolean - argument. If <option>true</option>, - this unit can only be activated - or deactivated indirectly. In - this case, explicit start-up - or termination requested by the - user is denied, however if it is - started or stopped as a - dependency of another unit, start-up - or termination will succeed. This - is mostly a safety feature to ensure - that the user does not accidentally - activate units that are not intended - to be activated explicitly, and not - accidentally deactivate units that are - not intended to be deactivated. - These options default to - <option>false</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>AllowIsolate=</varname></term> - - <listitem><para>Takes a boolean - argument. If <option>true</option>, - this unit may be used with the - <command>systemctl isolate</command> - command. Otherwise, this will be - refused. It probably is a good idea to - leave this disabled except for target - units that shall be used similar to - runlevels in SysV init systems, just - as a precaution to avoid unusable - system states. This option defaults to - <option>false</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultDependencies=</varname></term> - - <listitem><para>Takes a boolean - argument. If <option>true</option>, - (the default), a few default - dependencies will implicitly be - created for the unit. The actual - dependencies created depend on the - unit type. For example, for service - units, these dependencies ensure that - the service is started only after - basic system initialization is - completed and is properly terminated on - system shutdown. See the respective - man pages for details. Generally, only - services involved with early boot or - late shutdown should set this option - to <option>false</option>. It is - highly recommended to leave this - option enabled for the majority of - common units. If set to - <option>false</option>, this option - does not disable all implicit - dependencies, just non-essential - ones.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>JobTimeoutSec=</varname></term> - <term><varname>JobTimeoutAction=</varname></term> - <term><varname>JobTimeoutRebootArgument=</varname></term> - - <listitem><para>When a job for this - unit is queued a time-out may be - configured. If this time limit is - reached, the job will be cancelled, - the unit however will not change state - or even enter the - <literal>failed</literal> mode. This - value defaults to 0 (job timeouts - disabled), except for device - units. NB: this timeout is independent - from any unit-specific timeout (for - example, the timeout set with - <varname>StartTimeoutSec=</varname> in service - units) as the job timeout has no - effect on the unit itself, only on the - job that might be pending for it. Or - in other words: unit-specific timeouts - are useful to abort unit state - changes, and revert them. The job - timeout set with this option however - is useful to abort only the job - waiting for the unit state to - change.</para> - - <para><varname>JobTimeoutAction=</varname> - optionally configures an additional - action to take when the time-out is - hit. It takes the same values as the - per-service - <varname>StartLimitAction=</varname> - setting, see - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Defaults to - <option>none</option>. <varname>JobTimeoutRebootArgument=</varname> - configures an optional reboot string - to pass to the - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ConditionArchitecture=</varname></term> - <term><varname>ConditionVirtualization=</varname></term> - <term><varname>ConditionHost=</varname></term> - <term><varname>ConditionKernelCommandLine=</varname></term> - <term><varname>ConditionSecurity=</varname></term> - <term><varname>ConditionCapability=</varname></term> - <term><varname>ConditionACPower=</varname></term> - <term><varname>ConditionNeedsUpdate=</varname></term> - <term><varname>ConditionFirstBoot=</varname></term> - <term><varname>ConditionPathExists=</varname></term> - <term><varname>ConditionPathExistsGlob=</varname></term> - <term><varname>ConditionPathIsDirectory=</varname></term> - <term><varname>ConditionPathIsSymbolicLink=</varname></term> - <term><varname>ConditionPathIsMountPoint=</varname></term> - <term><varname>ConditionPathIsReadWrite=</varname></term> - <term><varname>ConditionDirectoryNotEmpty=</varname></term> - <term><varname>ConditionFileNotEmpty=</varname></term> - <term><varname>ConditionFileIsExecutable=</varname></term> - - <!-- We don't document ConditionNull= - here as it is not particularly - useful and probably just - confusing. --> - - <listitem><para>Before starting a unit - verify that the specified condition is - true. If it is not true, the starting - of the unit will be skipped, however - all ordering dependencies of it are - still respected. A failing condition - will not result in the unit being - moved into a failure state. The - condition is checked at the time the - queued start job is to be - executed.</para> - - <para><varname>ConditionArchitecture=</varname> - may be used to check whether the - system is running on a specific - architecture. Takes one of - <varname>x86</varname>, - <varname>x86-64</varname>, - <varname>ppc</varname>, - <varname>ppc-le</varname>, - <varname>ppc64</varname>, - <varname>ppc64-le</varname>, - <varname>ia64</varname>, - <varname>parisc</varname>, - <varname>parisc64</varname>, - <varname>s390</varname>, - <varname>s390x</varname>, - <varname>sparc</varname>, - <varname>sparc64</varname>, - <varname>mips</varname>, - <varname>mips-le</varname>, - <varname>mips64</varname>, - <varname>mips64-le</varname>, - <varname>alpha</varname>, - <varname>arm</varname>, - <varname>arm-be</varname>, - <varname>arm64</varname>, - <varname>arm64-be</varname>, - <varname>sh</varname>, - <varname>sh64</varname>, - <varname>m86k</varname>, - <varname>tilegx</varname>, - <varname>cris</varname> to test - against a specific architecture. The - architecture is determined from the - information returned by - <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> - and is thus subject to - <citerefentry><refentrytitle>personality</refentrytitle><manvolnum>2</manvolnum></citerefentry>. Note - that a <varname>Personality=</varname> - setting in the same unit file has no - effect on this condition. A special - architecture name - <varname>native</varname> is mapped to - the architecture the system manager - itself is compiled for. The test may - be negated by prepending an - exclamation mark.</para> - - <para><varname>ConditionVirtualization=</varname> - may be used to check whether the - system is executed in a virtualized - environment and optionally test - whether it is a specific - implementation. Takes either boolean - value to check if being executed in - any virtualized environment, or one of - <varname>vm</varname> and - <varname>container</varname> to test - against a generic type of - virtualization solution, or one of - <varname>qemu</varname>, - <varname>kvm</varname>, - <varname>zvm</varname>, - <varname>vmware</varname>, - <varname>microsoft</varname>, - <varname>oracle</varname>, - <varname>xen</varname>, - <varname>bochs</varname>, - <varname>uml</varname>, - <varname>openvz</varname>, - <varname>lxc</varname>, - <varname>lxc-libvirt</varname>, - <varname>systemd-nspawn</varname>, - <varname>docker</varname> to test - against a specific implementation. See - <citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry> - for a full list of known - virtualization technologies and their - identifiers. If multiple - virtualization technologies are - nested, only the innermost is - considered. The test may be negated by - prepending an exclamation mark.</para> - - <para><varname>ConditionHost=</varname> - may be used to match against the - hostname or machine ID of the - host. This either takes a hostname - string (optionally with shell style - globs) which is tested against the - locally set hostname as returned by - <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - or a machine ID formatted as string - (see - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>). - The test may be negated by prepending - an exclamation mark.</para> - - <para><varname>ConditionKernelCommandLine=</varname> - may be used to check whether a - specific kernel command line option is - set (or if prefixed with the - exclamation mark unset). The argument - must either be a single word, or an - assignment (i.e. two words, separated - <literal>=</literal>). In the former - case the kernel command line is - searched for the word appearing as is, - or as left hand side of an - assignment. In the latter case, the - exact assignment is looked for with - right and left hand side - matching.</para> - - <para><varname>ConditionSecurity=</varname> - may be used to check whether the given - security module is enabled on the - system. Currently the recognized - values values are - <varname>selinux</varname>, - <varname>apparmor</varname>, - <varname>ima</varname>, - <varname>smack</varname> and - <varname>audit</varname>. The test may - be negated by prepending an - exclamation mark.</para> - - <para><varname>ConditionCapability=</varname> - may be used to check whether the given - capability exists in the capability - bounding set of the service manager - (i.e. this does not check whether - capability is actually available in - the permitted or effective sets, see - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details). Pass a capability name - such as <literal>CAP_MKNOD</literal>, - possibly prefixed with an exclamation - mark to negate the check.</para> - - <para><varname>ConditionACPower=</varname> - may be used to check whether the - system has AC power, or is exclusively - battery powered at the time of - activation of the unit. This takes a - boolean argument. If set to - <varname>true</varname>, the condition - will hold only if at least one AC - connector of the system is connected - to a power source, or if no AC - connectors are known. Conversely, if - set to <varname>false</varname>, the - condition will hold only if there is - at least one AC connector known and - all AC connectors are disconnected - from a power source.</para> - - <para><varname>ConditionNeedsUpdate=</varname> - takes one of <filename>/var</filename> - or <filename>/etc</filename> as - argument, possibly prefixed with a - <literal>!</literal> (for inverting - the condition). This condition may be - used to conditionalize units on - whether the specified directory - requires an update because - <filename>/usr</filename>'s - modification time is newer than the - stamp file - <filename>.updated</filename> in the - specified directory. This is useful to - implement offline updates of the - vendor operating system resources in - <filename>/usr</filename> that require - updating of <filename>/etc</filename> - or <filename>/var</filename> on the - next following boot. Units making use - of this condition should order - themselves before - <citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - to make sure they run before the stamp - files's modification time gets reset - indicating a completed update.</para> - - <para><varname>ConditionFirstBoot=</varname> - takes a boolean argument. This - condition may be used to - conditionalize units on whether the - system is booting up with an - unpopulated <filename>/etc</filename> - directory. This may be used to - populate <filename>/etc</filename> on - the first boot after factory reset, or - when a new system instances boots up - for the first time.</para> - - <para>With - <varname>ConditionPathExists=</varname> - a file existence condition is - checked before a unit is started. If - the specified absolute path name does - not exist, the condition will - fail. If the absolute path name passed - to - <varname>ConditionPathExists=</varname> - is prefixed with an exclamation mark - (<literal>!</literal>), the test is negated, and the unit - is only started if the path does not - exist.</para> - - <para><varname>ConditionPathExistsGlob=</varname> - is similar to - <varname>ConditionPathExists=</varname>, - but checks for the existence of at - least one file or directory matching - the specified globbing pattern.</para> - - <para><varname>ConditionPathIsDirectory=</varname> - is similar to - <varname>ConditionPathExists=</varname> - but verifies whether a certain path - exists and is a - directory.</para> - - <para><varname>ConditionPathIsSymbolicLink=</varname> - is similar to - <varname>ConditionPathExists=</varname> - but verifies whether a certain path - exists and is a symbolic - link.</para> - - <para><varname>ConditionPathIsMountPoint=</varname> - is similar to - <varname>ConditionPathExists=</varname> - but verifies whether a certain path - exists and is a mount - point.</para> - - <para><varname>ConditionPathIsReadWrite=</varname> - is similar to - <varname>ConditionPathExists=</varname> - but verifies whether the underlying - file system is readable and writable - (i.e. not mounted - read-only).</para> - - <para><varname>ConditionDirectoryNotEmpty=</varname> - is similar to - <varname>ConditionPathExists=</varname> - but verifies whether a certain path - exists and is a non-empty - directory.</para> - - <para><varname>ConditionFileNotEmpty=</varname> - is similar to - <varname>ConditionPathExists=</varname> - but verifies whether a certain path - exists and refers to a regular file - with a non-zero size.</para> - - <para><varname>ConditionFileIsExecutable=</varname> - is similar to - <varname>ConditionPathExists=</varname> - but verifies whether a certain path - exists, is a regular file and marked - executable.</para> - - <para>If multiple conditions are - specified, the unit will be executed if - all of them apply (i.e. a logical AND - is applied). Condition checks can be - prefixed with a pipe symbol (|) in - which case a condition becomes a - triggering condition. If at least one - triggering condition is defined for a - unit, then the unit will be executed if - at least one of the triggering - conditions apply and all of the - non-triggering conditions. If you - prefix an argument with the pipe - symbol and an exclamation mark, the - pipe symbol must be passed first, the - exclamation second. Except for - <varname>ConditionPathIsSymbolicLink=</varname>, - all path checks follow symlinks. If - any of these options is assigned the - empty string, the list of conditions is - reset completely, all previous - condition settings (of any kind) will - have no effect.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>AssertArchitecture=</varname></term> - <term><varname>AssertVirtualization=</varname></term> - <term><varname>AssertHost=</varname></term> - <term><varname>AssertKernelCommandLine=</varname></term> - <term><varname>AssertSecurity=</varname></term> - <term><varname>AssertCapability=</varname></term> - <term><varname>AssertACPower=</varname></term> - <term><varname>AssertNeedsUpdate=</varname></term> - <term><varname>AssertFirstBoot=</varname></term> - <term><varname>AssertPathExists=</varname></term> - <term><varname>AssertPathExistsGlob=</varname></term> - <term><varname>AssertPathIsDirectory=</varname></term> - <term><varname>AssertPathIsSymbolicLink=</varname></term> - <term><varname>AssertPathIsMountPoint=</varname></term> - <term><varname>AssertPathIsReadWrite=</varname></term> - <term><varname>AssertDirectoryNotEmpty=</varname></term> - <term><varname>AssertFileNotEmpty=</varname></term> - <term><varname>AssertFileIsExecutable=</varname></term> - - <listitem><para>Similar to the - <varname>ConditionArchitecture=</varname>, - <varname>ConditionVirtualization=</varname>, - ... condition settings described above - these settings add assertion checks to - the start-up of the unit. However, - unlike the conditions settings any - assertion setting that is not met - results in failure of the start - job it was triggered by.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>SourcePath=</varname></term> - <listitem><para>A path to a - configuration file this unit has been - generated from. This is primarily - useful for implementation of generator - tools that convert configuration from - an external configuration file format - into native unit files. This - functionality should not be used in - normal units.</para></listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1> - <title>[Install] Section Options</title> - - <para>Unit file may include an - <literal>[Install]</literal> section, which carries - installation information for the unit. This section is - not interpreted by - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> - during runtime. It is used exclusively by the - <command>enable</command> and - <command>disable</command> commands of the - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool during installation of a unit:</para> - - <variablelist class='unit-directives'> - <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> - </varlistentry> - - <varlistentry> - <term><varname>WantedBy=</varname></term> - <term><varname>RequiredBy=</varname></term> - - <listitem><para>This option may be - used more than once, or a - space-separated list of unit names may - be given. A symbolic link is created - in the <filename>.wants/</filename> or - <filename>.requires/</filename> - directory of each of the listed units - when this unit is installed by - <command>systemctl enable</command>. - This has the effect that a dependency - of type <varname>Wants=</varname> or - <varname>Requires=</varname> is added - from the listed unit to the current - unit. The primary result is that the - current unit will be started when the - listed unit is started. See the - description of - <varname>Wants=</varname> and - <varname>Requires=</varname> in the - [Unit] section for details.</para> - - <para><command>WantedBy=foo.service</command> - in a service - <filename>bar.service</filename> is - mostly equivalent to - <command>Alias=foo.service.wants/bar.service</command> - in the same file. In case of template - units, <command>systemctl enable</command> - must be called with an instance name, and - this instance will be added to the - <filename>.wants/</filename> or - <filename>.requires/</filename> list - of the listed unit. - E.g. <command>WantedBy=getty.target</command> - in a service - <filename>getty@.service</filename> - will result in <command>systemctl - enable getty@tty2.service</command> - creating a - <filename>getty.target.wants/getty@tty2.service</filename> - link to <filename>getty@.service</filename>. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>Also=</varname></term> - - <listitem><para>Additional units to - install/deinstall when this unit is - installed/deinstalled. If the user - requests installation/deinstallation - of a unit with this option configured, - <command>systemctl enable</command> - and <command>systemctl - disable</command> will automatically - install/uninstall units listed in this option as - well.</para> - - <para>This option may be used more - than once, or a space-separated list - of unit names may be - given.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>DefaultInstance=</varname></term> - - <listitem><para>In template unit files, - this specifies for which instance the - unit shall be enabled if the template - is enabled without any explicitly set - instance. This option has no effect in - non-template unit files. The specified - string must be usable as instance - identifier.</para></listitem> - </varlistentry> - </variablelist> - - <para>The following specifiers are interpreted in the - Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v. - For their meaning see the next section. - </para> - </refsect1> - - <refsect1> - <title>Specifiers</title> - - <para>Many settings resolve specifiers which may be - used to write generic unit files referring to runtime - or unit parameters that are replaced when the unit - files are loaded. The following specifiers are - understood:</para> - - <table> - <title>Specifiers available in unit files</title> - <tgroup cols='3' align='left' colsep='1' rowsep='1'> - <colspec colname="spec" /> - <colspec colname="mean" /> - <colspec colname="detail" /> - <thead> - <row> - <entry>Specifier</entry> - <entry>Meaning</entry> - <entry>Details</entry> - </row> - </thead> - <tbody> - <row> - <entry><literal>%n</literal></entry> - <entry>Full unit name</entry> - <entry></entry> - </row> - <row> - <entry><literal>%N</literal></entry> - <entry>Unescaped full unit name</entry> - <entry>Same as <literal>%n</literal>, but with escaping undone</entry> - </row> - <row> - <entry><literal>%p</literal></entry> - <entry>Prefix name</entry> - <entry>For instantiated units, this refers to the string before the <literal>@</literal> character of the unit name. For non-instantiated units, this refers to the name of the unit with the type suffix removed.</entry> - </row> - <row> - <entry><literal>%P</literal></entry> - <entry>Unescaped prefix name</entry> - <entry>Same as <literal>%p</literal>, but with escaping undone</entry> - </row> - <row> - <entry><literal>%i</literal></entry> - <entry>Instance name</entry> - <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix of the unit name.</entry> - </row> - <row> - <entry><literal>%I</literal></entry> - <entry>Unescaped instance name</entry> - <entry>Same as <literal>%i</literal>, but with escaping undone</entry> - </row> - <row> - <entry><literal>%f</literal></entry> - <entry>Unescaped filename</entry> - <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the prefix name prepended with <filename>/</filename>.</entry> - </row> - <row> - <entry><literal>%c</literal></entry> - <entry>Control group path of the unit</entry> - <entry>This path does not include the <filename>/sys/fs/cgroup/systemd/</filename> prefix.</entry> - </row> - <row> - <entry><literal>%r</literal></entry> - <entry>Control group path of the slice the unit is placed in</entry> - <entry>This usually maps to the parent cgroup path of <literal>%c</literal>.</entry> - </row> - <row> - <entry><literal>%R</literal></entry> - <entry>Root control group path below which slices and units are placed</entry> - <entry>For system instances, this resolves to <filename>/</filename>, except in containers, where this maps to the container's root control group path.</entry> - </row> - <row> - <entry><literal>%t</literal></entry> - <entry>Runtime directory</entry> - <entry>This is either <filename>/run</filename> (for the system manager) or the path <literal>$XDG_RUNTIME_DIR</literal> resolves to (for user managers).</entry> - </row> - <row> - <entry><literal>%u</literal></entry> - <entry>User name</entry> - <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry> - </row> - <row> - <entry><literal>%U</literal></entry> - <entry>User UID</entry> - <entry>This is the numeric UID of the configured user of the unit, or (if none is set) the user running the systemd user instance. Note that this specifier is not available for units run by the systemd system instance (as opposed to those run by a systemd user instance), unless the user has been configured as a numeric UID in the first place or the configured user is the root user.</entry> - </row> - <row> - <entry><literal>%h</literal></entry> - <entry>User home directory</entry> - <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry> - </row> - <row> - <entry><literal>%s</literal></entry> - <entry>User shell</entry> - <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry> - </row> - <row> - <entry><literal>%m</literal></entry> - <entry>Machine ID</entry> - <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry> - </row> - <row> - <entry><literal>%b</literal></entry> - <entry>Boot ID</entry> - <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry> - </row> - <row> - <entry><literal>%H</literal></entry> - <entry>Host name</entry> - <entry>The hostname of the running system at the point in time the unit configuation is loaded.</entry> - </row> - <row> - <entry><literal>%v</literal></entry> - <entry>Kernel release</entry> - <entry>Identical to <command>uname -r</command> output</entry> - </row> - <row> - <entry><literal>%%</literal></entry> - <entry>Single percent sign</entry> - <entry>Use <literal>%%</literal> in place of <literal>%</literal> to specify a single percent sign.</entry> - </row> - </tbody> - </tgroup> - </table> - - <para>Please note that specifiers - <literal>%U</literal>, <literal>%h</literal>, - <literal>%s</literal> are mostly useless when systemd - is running in system mode. PID 1 cannot query the - user account database for information, so the - specifiers only work as shortcuts for things which are - already specified in a different way in the unit - file. They are fully functional when systemd is - running in <option>--user</option> mode.</para> - </refsect1> - - <refsect1> - <title>Examples</title> - - <example> - <title>Allowing units to be enabled</title> - - <para>The following snippet (highlighted) - allows a unit (e.g. - <filename>foo.service</filename>) to be - enabled via - <command>systemctl enable</command>:</para> - - <programlisting>[Unit] + </literallayout></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file encodes information about a + service, a socket, a device, a mount point, an automount point, a + swap file or partition, a start-up target, a watched file system + path, a timer controlled and supervised by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + a temporary system state snapshot, a resource management slice or + a group of externally created processes. The syntax is inspired by + <ulink + url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG + Desktop Entry Specification</ulink> <filename>.desktop</filename> + files, which are in turn inspired by Microsoft Windows + <filename>.ini</filename> files.</para> + + <para>This man page lists the common configuration options of all + the unit types. These options need to be configured in the [Unit] + or [Install] sections of the unit files.</para> + + <para>In addition to the generic [Unit] and [Install] sections + described here, each unit may have a type-specific section, e.g. + [Service] for a service unit. See the respective man pages for + more information: + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>Various settings are allowed to be specified more than once, + in which case the interpretation depends on the setting. Often, + multiple settings form a list, and setting to an empty value + "resets", which means that previous assignments are ignored. When + this is allowed, it is mentioned in the description of the + setting. Note that using multiple assignments to the same value + makes the unit file incompatible with parsers for the XDG + <filename>.desktop</filename> file format.</para> + + <para>Unit files are loaded from a set of paths determined during + compilation, described in the next section.</para> + + <para>Unit files may contain additional options on top of those + listed here. If systemd encounters an unknown option, it will + write a warning log message but continue loading the unit. If an + option or section name is prefixed with <option>X-</option>, it is + ignored completely by systemd. Options within an ignored section + do not need the prefix. Applications may use this to include + additional information in the unit files.</para> + + <para>Boolean arguments used in unit files can be written in + various formats. For positive settings the strings + <option>1</option>, <option>yes</option>, <option>true</option> + and <option>on</option> are equivalent. For negative settings, the + strings <option>0</option>, <option>no</option>, + <option>false</option> and <option>off</option> are + equivalent.</para> + + <para>Time span values encoded in unit files can be written in + various formats. A stand-alone number specifies a time in seconds. + If suffixed with a time unit, the unit is honored. A concatenation + of multiple values with units is supported, in which case the + values are added up. Example: "50" refers to 50 seconds; "2min + 200ms" refers to 2 minutes plus 200 milliseconds, i.e. 120200ms. + The following time units are understood: s, min, h, d, w, ms, us. + For details see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>Empty lines and lines starting with # or ; are + ignored. This may be used for commenting. Lines ending + in a backslash are concatenated with the following + line while reading and the backslash is replaced by a + space character. This may be used to wrap long lines.</para> + + <para>Along with a unit file <filename>foo.service</filename>, the + directory <filename>foo.service.wants/</filename> may exist. All + unit files symlinked from such a directory are implicitly added as + dependencies of type <varname>Wants=</varname> to the unit. This + is useful to hook units into the start-up of other units, without + having to modify their unit files. For details about the semantics + of <varname>Wants=</varname>, see below. The preferred way to + create symlinks in the <filename>.wants/</filename> directory of a + unit file is with the <command>enable</command> command of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool which reads information from the [Install] section of unit + files (see below). A similar functionality exists for + <varname>Requires=</varname> type dependencies as well, the + directory suffix is <filename>.requires/</filename> in this + case.</para> + + <para>Along with a unit file <filename>foo.service</filename>, a + directory <filename>foo.service.d/</filename> may exist. All files + with the suffix <literal>.conf</literal> from this directory will + be parsed after the file itself is parsed. This is useful to alter + or add configuration settings to a unit, without having to modify + their unit files. Make sure that the file that is included has the + appropriate section headers before any directive. Note that for + instanced units this logic will first look for the instance + <literal>.d/</literal> subdirectory and read its + <literal>.conf</literal> files, followed by the template + <literal>.d/</literal> subdirectory and reads its + <literal>.conf</literal> files.</para> + + <!-- Note that we do not document .include here, as we + consider it mostly obsolete, and want people to + use .d/ drop-ins instead. --> + + <para>Note that while systemd offers a flexible dependency system + between units it is recommended to use this functionality only + sparingly and instead rely on techniques such as bus-based or + socket-based activation which make dependencies implicit, + resulting in a both simpler and more flexible system.</para> + + <para>Some unit names reflect paths existing in the file system + namespace. Example: a device unit + <filename>dev-sda.device</filename> refers to a device with the + device node <filename noindex='true'>/dev/sda</filename> in the + file system namespace. If this applies, a special way to escape + the path name is used, so that the result is usable as part of a + filename. Basically, given a path, "/" is replaced by "-" and all + other characters which are not ASCII alphanumerics are replaced by + C-style "\x2d" escapes (except that "_" is never replaced and "." + is only replaced when it would be the first character in the + escaped path). The root directory "/" is encoded as single dash, + while otherwise the initial and ending "/" are removed from all + paths during transformation. This escaping is reversible. Properly + escaped paths can be generated using the + <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry> + command.</para> + + <para>Optionally, units may be instantiated from a + template file at runtime. This allows creation of + multiple units from a single configuration file. If + systemd looks for a unit configuration file, it will + first search for the literal unit name in the + file system. If that yields no success and the unit + name contains an <literal>@</literal> character, systemd will look for a + unit template that shares the same name but with the + instance string (i.e. the part between the <literal>@</literal> character + and the suffix) removed. Example: if a service + <filename>getty@tty3.service</filename> is requested + and no file by that name is found, systemd will look + for <filename>getty@.service</filename> and + instantiate a service from that configuration file if + it is found.</para> + + <para>To refer to the instance string from within the + configuration file you may use the special <literal>%i</literal> + specifier in many of the configuration options. See below for + details.</para> + + <para>If a unit file is empty (i.e. has the file size 0) or is + symlinked to <filename>/dev/null</filename>, its configuration + will not be loaded and it appears with a load state of + <literal>masked</literal>, and cannot be activated. Use this as an + effective way to fully disable a unit, making it impossible to + start it even manually.</para> + + <para>The unit file format is covered by the + <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface + Stability Promise</ulink>.</para> + + </refsect1> + + <refsect1> + <title>Unit Load Path</title> + + <para>Unit files are loaded from a set of paths determined during + compilation, described in the two tables below. Unit files found + in directories listed earlier override files with the same name in + directories lower in the list.</para> + + <para>When systemd is running in user mode + (<option>--user</option>) and the variable + <varname>$SYSTEMD_UNIT_PATH</varname> is set, the contents of this + variable overrides the unit load path. If + <varname>$SYSTEMD_UNIT_PATH</varname> ends with an empty component + (<literal>:</literal>), the usual unit load path will be appended + to the contents of the variable.</para> + + <table> + <title> + Load path when running in system mode (<option>--system</option>). + </title> + + <tgroup cols='2'> + <colspec colname='path' /> + <colspec colname='expl' /> + <thead> + <row> + <entry>Path</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>/etc/systemd/system</filename></entry> + <entry>Local configuration</entry> + </row> + <row> + <entry><filename>/run/systemd/system</filename></entry> + <entry>Runtime units</entry> + </row> + <row> + <entry><filename>/usr/lib/systemd/system</filename></entry> + <entry>Units of installed packages</entry> + </row> + </tbody> + </tgroup> + </table> + + <table> + <title> + Load path when running in user mode (<option>--user</option>). + </title> + + <tgroup cols='2'> + <colspec colname='path' /> + <colspec colname='expl' /> + <thead> + <row> + <entry>Path</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry> + <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry> + </row> + <row> + <entry><filename>$HOME/.config/systemd/user</filename></entry> + <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry> + </row> + <row> + <entry><filename>/etc/systemd/user</filename></entry> + <entry>Local configuration</entry> + </row> + <row> + <entry><filename>$XDG_RUNTIME_DIR/systemd/user</filename></entry> + <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)</entry> + </row> + <row> + <entry><filename>/run/systemd/user</filename></entry> + <entry>Runtime units</entry> + </row> + <row> + <entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry> + <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</entry> + </row> + <row> + <entry><filename>$HOME/.local/share/systemd/user</filename></entry> + <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)</entry> + </row> + <row> + <entry><filename>/usr/lib/systemd/user</filename></entry> + <entry>Units of packages that have been installed system-wide</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Additional units might be loaded into systemd ("linked") + from directories not on the unit load path. See the + <command>link</command> command for + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + Also, some units are dynamically created via generators <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/Generators/">Generators</ulink>. + </para> + </refsect1> + + <refsect1> + <title>[Unit] Section Options</title> + + <para>Unit file may include a [Unit] section, which carries + generic information about the unit that is not dependent on the + type of unit:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>Description=</varname></term> + <listitem><para>A free-form string describing the unit. This + is intended for use in UIs to show descriptive information + along with the unit name. The description should contain a + name that means something to the end user. <literal>Apache2 + Web Server</literal> is a good example. Bad examples are + <literal>high-performance light-weight HTTP server</literal> + (too generic) or <literal>Apache2</literal> (too specific and + meaningless for people who do not know + Apache).</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Documentation=</varname></term> + <listitem><para>A space-separated list of URIs referencing + documentation for this unit or its configuration. Accepted are + only URIs of the types <literal>http://</literal>, + <literal>https://</literal>, <literal>file:</literal>, + <literal>info:</literal>, <literal>man:</literal>. For more + information about the syntax of these URIs, see <citerefentry + project='man-pages'><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + The URIs should be listed in order of relevance, starting with + the most relevant. It is a good idea to first reference + documentation that explains what the unit's purpose is, + followed by how it is configured, followed by any other + related documentation. This option may be specified more than + once, in which case the specified list of URIs is merged. If + the empty string is assigned to this option, the list is reset + and all prior assignments will have no + effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Requires=</varname></term> + + <listitem><para>Configures requirement dependencies on other + units. If this unit gets activated, the units listed here will + be activated as well. If one of the other units gets + deactivated or its activation fails, this unit will be + deactivated. This option may be specified more than once or + multiple space-separated units may be specified in one option + in which case requirement dependencies for all listed names + will be created. Note that requirement dependencies do not + influence the order in which services are started or stopped. + This has to be configured independently with the + <varname>After=</varname> or <varname>Before=</varname> + options. If a unit <filename>foo.service</filename> requires a + unit <filename>bar.service</filename> as configured with + <varname>Requires=</varname> and no ordering is configured + with <varname>After=</varname> or <varname>Before=</varname>, + then both units will be started simultaneously and without any + delay between them if <filename>foo.service</filename> is + activated. Often it is a better choice to use + <varname>Wants=</varname> instead of + <varname>Requires=</varname> in order to achieve a system that + is more robust when dealing with failing services.</para> + + <para>Note that dependencies of this type may also be + configured outside of the unit configuration file by adding a + symlink to a <filename>.requires/</filename> directory + accompanying the unit file. For details see + above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RequiresOverridable=</varname></term> + + <listitem><para>Similar to <varname>Requires=</varname>. + Dependencies listed in <varname>RequiresOverridable=</varname> + which cannot be fulfilled or fail to start are ignored if the + startup was explicitly requested by the user. If the start-up + was pulled in indirectly by some dependency or automatic + start-up of units that is not requested by the user, this + dependency must be fulfilled and otherwise the transaction + fails. Hence, this option may be used to configure + dependencies that are normally honored unless the user + explicitly starts up the unit, in which case whether they + failed or not is irrelevant.</para></listitem> + + </varlistentry> + <varlistentry> + <term><varname>Requisite=</varname></term> + <term><varname>RequisiteOverridable=</varname></term> + + <listitem><para>Similar to <varname>Requires=</varname> and + <varname>RequiresOverridable=</varname>, respectively. + However, if the units listed here are not started already, + they will not be started and the transaction will fail + immediately. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Wants=</varname></term> + + <listitem><para>A weaker version of + <varname>Requires=</varname>. Units listed in this option will + be started if the configuring unit is. However, if the listed + units fail to start or cannot be added to the transaction, + this has no impact on the validity of the transaction as a + whole. This is the recommended way to hook start-up of one + unit to the start-up of another unit.</para> + + <para>Note that dependencies of this type may also be + configured outside of the unit configuration file by adding + symlinks to a <filename>.wants/</filename> directory + accompanying the unit file. For details, see + above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BindsTo=</varname></term> + + <listitem><para>Configures requirement dependencies, very + similar in style to <varname>Requires=</varname>, however in + addition to this behavior, it also declares that this unit is + stopped when any of the units listed suddenly disappears. + Units can suddenly, unexpectedly disappear if a service + terminates on its own choice, a device is unplugged or a mount + point unmounted without involvement of + systemd.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PartOf=</varname></term> + + <listitem><para>Configures dependencies similar to + <varname>Requires=</varname>, but limited to stopping and + restarting of units. When systemd stops or restarts the units + listed here, the action is propagated to this unit. Note that + this is a one-way dependency — changes to this unit do not + affect the listed units. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Conflicts=</varname></term> + + <listitem><para>A space-separated list of unit names. + Configures negative requirement dependencies. If a unit has a + <varname>Conflicts=</varname> setting on another unit, + starting the former will stop the latter and vice versa. Note + that this setting is independent of and orthogonal to the + <varname>After=</varname> and <varname>Before=</varname> + ordering dependencies.</para> + + <para>If a unit A that conflicts with a unit B is scheduled to + be started at the same time as B, the transaction will either + fail (in case both are required part of the transaction) or be + modified to be fixed (in case one or both jobs are not a + required part of the transaction). In the latter case, the job + that is not the required will be removed, or in case both are + not required, the unit that conflicts will be started and the + unit that is conflicted is stopped.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Before=</varname></term> + <term><varname>After=</varname></term> + + <listitem><para>A space-separated list of unit names. + Configures ordering dependencies between units. If a unit + <filename>foo.service</filename> contains a setting + <option>Before=bar.service</option> and both units are being + started, <filename>bar.service</filename>'s start-up is + delayed until <filename>foo.service</filename> is started up. + Note that this setting is independent of and orthogonal to the + requirement dependencies as configured by + <varname>Requires=</varname>. It is a common pattern to + include a unit name in both the <varname>After=</varname> and + <varname>Requires=</varname> option, in which case the unit + listed will be started before the unit that is configured with + these options. This option may be specified more than once, in + which case ordering dependencies for all listed names are + created. <varname>After=</varname> is the inverse of + <varname>Before=</varname>, i.e. while + <varname>After=</varname> ensures that the configured unit is + started after the listed unit finished starting up, + <varname>Before=</varname> ensures the opposite, i.e. that the + configured unit is fully started up before the listed unit is + started. Note that when two units with an ordering dependency + 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. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>OnFailure=</varname></term> + + <listitem><para>A space-separated list of one or more units + that are activated when this unit enters the + <literal>failed</literal> state.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PropagatesReloadTo=</varname></term> + <term><varname>ReloadPropagatedFrom=</varname></term> + + <listitem><para>A space-separated list of one or more units + where reload requests on this unit will be propagated to, or + reload requests on the other unit will be propagated to this + unit, respectively. Issuing a reload request on a unit will + automatically also enqueue a reload request on all units that + the reload request shall be propagated to via these two + settings.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>JoinsNamespaceOf=</varname></term> + + <listitem><para>For units that start processes (such as + service units), lists one or more other units whose network + and/or temporary file namespace to join. This only applies to + unit types which support the + <varname>PrivateNetwork=</varname> and + <varname>PrivateTmp=</varname> directives (see + <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 + 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 + <varname>PrivateNetwork=</varname> and/or + <varname>PrivateTmp=</varname> is enabled for both the unit + that joins the namespace and the unit whose namespace is + joined.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RequiresMountsFor=</varname></term> + + <listitem><para>Takes a space-separated list of absolute + paths. Automatically adds dependencies of type + <varname>Requires=</varname> and <varname>After=</varname> for + all mount units required to access the specified path.</para> + + <para>Mount points marked with <option>noauto</option> are not + mounted automatically and will be ignored for the purposes of + this option. If such a mount should be a requirement for this + unit, direct dependencies on the mount units may be added + (<varname>Requires=</varname> and <varname>After=</varname> or + some other combination). </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>OnFailureJobMode=</varname></term> + + <listitem><para>Takes a value of + <literal>fail</literal>, + <literal>replace</literal>, + <literal>replace-irreversibly</literal>, + <literal>isolate</literal>, + <literal>flush</literal>, + <literal>ignore-dependencies</literal> or + <literal>ignore-requirements</literal>. Defaults to + <literal>replace</literal>. Specifies how the units listed in + <varname>OnFailure=</varname> will be enqueued. See + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <option>--job-mode=</option> option for details on the + possible values. If this is set to <literal>isolate</literal>, + only a single unit may be listed in + <varname>OnFailure=</varname>..</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IgnoreOnIsolate=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, this unit will not be stopped when + isolating another unit. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IgnoreOnSnapshot=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, this unit will not be included in + snapshots. Defaults to <option>true</option> for device and + snapshot units, <option>false</option> for the + others.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StopWhenUnneeded=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, this unit will be stopped when it is no + longer used. Note that in order to minimize the work to be + executed, systemd will not stop units by default unless they + are conflicting with other units, or the user explicitly + requested their shut down. If this option is set, a unit will + be automatically cleaned up if no other active unit requires + it. Defaults to <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RefuseManualStart=</varname></term> + <term><varname>RefuseManualStop=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, this unit can only be activated or + deactivated indirectly. In this case, explicit start-up or + termination requested by the user is denied, however if it is + started or stopped as a dependency of another unit, start-up + or termination will succeed. This is mostly a safety feature + to ensure that the user does not accidentally activate units + that are not intended to be activated explicitly, and not + accidentally deactivate units that are not intended to be + deactivated. These options default to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AllowIsolate=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, this unit may be used with the + <command>systemctl isolate</command> command. Otherwise, this + will be refused. It probably is a good idea to leave this + disabled except for target units that shall be used similar to + runlevels in SysV init systems, just as a precaution to avoid + unusable system states. This option defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultDependencies=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, (the default), a few default + dependencies will implicitly be created for the unit. The + actual dependencies created depend on the unit type. For + example, for service units, these dependencies ensure that the + service is started only after basic system initialization is + completed and is properly terminated on system shutdown. See + the respective man pages for details. Generally, only services + involved with early boot or late shutdown should set this + option to <option>false</option>. It is highly recommended to + leave this option enabled for the majority of common units. If + set to <option>false</option>, this option does not disable + all implicit dependencies, just non-essential + ones.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>JobTimeoutSec=</varname></term> + <term><varname>JobTimeoutAction=</varname></term> + <term><varname>JobTimeoutRebootArgument=</varname></term> + + <listitem><para>When a job for this unit is queued a time-out + may be configured. If this time limit is reached, the job will + be cancelled, the unit however will not change state or even + enter the <literal>failed</literal> mode. This value defaults + to 0 (job timeouts disabled), except for device units. NB: + this timeout is independent from any unit-specific timeout + (for example, the timeout set with + <varname>StartTimeoutSec=</varname> in service units) as the + job timeout has no effect on the unit itself, only on the job + that might be pending for it. Or in other words: unit-specific + timeouts are useful to abort unit state changes, and revert + them. The job timeout set with this option however is useful + to abort only the job waiting for the unit state to + change.</para> + + <para><varname>JobTimeoutAction=</varname> + optionally configures an additional + action to take when the time-out is + hit. It takes the same values as the + per-service + <varname>StartLimitAction=</varname> + setting, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Defaults to + <option>none</option>. <varname>JobTimeoutRebootArgument=</varname> + configures an optional reboot string + to pass to the + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> + system call.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ConditionArchitecture=</varname></term> + <term><varname>ConditionVirtualization=</varname></term> + <term><varname>ConditionHost=</varname></term> + <term><varname>ConditionKernelCommandLine=</varname></term> + <term><varname>ConditionSecurity=</varname></term> + <term><varname>ConditionCapability=</varname></term> + <term><varname>ConditionACPower=</varname></term> + <term><varname>ConditionNeedsUpdate=</varname></term> + <term><varname>ConditionFirstBoot=</varname></term> + <term><varname>ConditionPathExists=</varname></term> + <term><varname>ConditionPathExistsGlob=</varname></term> + <term><varname>ConditionPathIsDirectory=</varname></term> + <term><varname>ConditionPathIsSymbolicLink=</varname></term> + <term><varname>ConditionPathIsMountPoint=</varname></term> + <term><varname>ConditionPathIsReadWrite=</varname></term> + <term><varname>ConditionDirectoryNotEmpty=</varname></term> + <term><varname>ConditionFileNotEmpty=</varname></term> + <term><varname>ConditionFileIsExecutable=</varname></term> + + <!-- We don't document ConditionNull= + here as it is not particularly + useful and probably just + confusing. --> + + <listitem><para>Before starting a unit verify that the + specified condition is true. If it is not true, the starting + of the unit will be skipped, however all ordering dependencies + of it are still respected. A failing condition will not result + in the unit being moved into a failure state. The condition is + checked at the time the queued start job is to be + executed.</para> + + <para><varname>ConditionArchitecture=</varname> may be used to + check whether the system is running on a specific + architecture. Takes one of + <varname>x86</varname>, + <varname>x86-64</varname>, + <varname>ppc</varname>, + <varname>ppc-le</varname>, + <varname>ppc64</varname>, + <varname>ppc64-le</varname>, + <varname>ia64</varname>, + <varname>parisc</varname>, + <varname>parisc64</varname>, + <varname>s390</varname>, + <varname>s390x</varname>, + <varname>sparc</varname>, + <varname>sparc64</varname>, + <varname>mips</varname>, + <varname>mips-le</varname>, + <varname>mips64</varname>, + <varname>mips64-le</varname>, + <varname>alpha</varname>, + <varname>arm</varname>, + <varname>arm-be</varname>, + <varname>arm64</varname>, + <varname>arm64-be</varname>, + <varname>sh</varname>, + <varname>sh64</varname>, + <varname>m86k</varname>, + <varname>tilegx</varname>, + <varname>cris</varname> to test + against a specific architecture. The architecture is + determined from the information returned by + <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> + and is thus subject to + <citerefentry><refentrytitle>personality</refentrytitle><manvolnum>2</manvolnum></citerefentry>. + Note that a <varname>Personality=</varname> setting in the + same unit file has no effect on this condition. A special + architecture name <varname>native</varname> is mapped to the + architecture the system manager itself is compiled for. The + test may be negated by prepending an exclamation mark.</para> + + <para><varname>ConditionVirtualization=</varname> may be used + to check whether the system is executed in a virtualized + environment and optionally test whether it is a specific + implementation. Takes either boolean value to check if being + executed in any virtualized environment, or one of + <varname>vm</varname> and + <varname>container</varname> to test against a generic type of + virtualization solution, or one of + <varname>qemu</varname>, + <varname>kvm</varname>, + <varname>zvm</varname>, + <varname>vmware</varname>, + <varname>microsoft</varname>, + <varname>oracle</varname>, + <varname>xen</varname>, + <varname>bochs</varname>, + <varname>uml</varname>, + <varname>openvz</varname>, + <varname>lxc</varname>, + <varname>lxc-libvirt</varname>, + <varname>systemd-nspawn</varname>, + <varname>docker</varname> to test + against a specific implementation. See + <citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for a full list of known virtualization technologies and their + identifiers. If multiple virtualization technologies are + nested, only the innermost is considered. The test may be + negated by prepending an exclamation mark.</para> + + <para><varname>ConditionHost=</varname> may be used to match + against the hostname or machine ID of the host. This either + takes a hostname string (optionally with shell style globs) + which is tested against the locally set hostname as returned + by + <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + or a machine ID formatted as string (see + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + The test may be negated by prepending an exclamation + mark.</para> + + <para><varname>ConditionKernelCommandLine=</varname> may be + used to check whether a specific kernel command line option is + set (or if prefixed with the exclamation mark unset). The + argument must either be a single word, or an assignment (i.e. + two words, separated <literal>=</literal>). In the former case + the kernel command line is searched for the word appearing as + is, or as left hand side of an assignment. In the latter case, + the exact assignment is looked for with right and left hand + side matching.</para> + + <para><varname>ConditionSecurity=</varname> may be used to + check whether the given security module is enabled on the + system. Currently the recognized values values are + <varname>selinux</varname>, + <varname>apparmor</varname>, + <varname>ima</varname>, + <varname>smack</varname> and + <varname>audit</varname>. The test may be negated by + prepending an exclamation mark.</para> + + <para><varname>ConditionCapability=</varname> may be used to + check whether the given capability exists in the capability + bounding set of the service manager (i.e. this does not check + whether capability is actually available in the permitted or + effective sets, see + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). Pass a capability name such as + <literal>CAP_MKNOD</literal>, possibly prefixed with an + exclamation mark to negate the check.</para> + + <para><varname>ConditionACPower=</varname> may be used to + check whether the system has AC power, or is exclusively + battery powered at the time of activation of the unit. This + takes a boolean argument. If set to <varname>true</varname>, + the condition will hold only if at least one AC connector of + the system is connected to a power source, or if no AC + connectors are known. Conversely, if set to + <varname>false</varname>, the condition will hold only if + there is at least one AC connector known and all AC connectors + are disconnected from a power source.</para> + + <para><varname>ConditionNeedsUpdate=</varname> takes one of + <filename>/var</filename> or <filename>/etc</filename> as + argument, possibly prefixed with a <literal>!</literal> (for + inverting the condition). This condition may be used to + conditionalize units on whether the specified directory + requires an update because <filename>/usr</filename>'s + modification time is newer than the stamp file + <filename>.updated</filename> in the specified directory. This + is useful to implement offline updates of the vendor operating + system resources in <filename>/usr</filename> that require + updating of <filename>/etc</filename> or + <filename>/var</filename> on the next following boot. Units + making use of this condition should order themselves before + <citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + to make sure they run before the stamp files's modification + time gets reset indicating a completed update.</para> + + <para><varname>ConditionFirstBoot=</varname> takes a boolean + argument. This condition may be used to conditionalize units + on whether the system is booting up with an unpopulated + <filename>/etc</filename> directory. This may be used to + populate <filename>/etc</filename> on the first boot after + factory reset, or when a new system instances boots up for the + first time.</para> + + <para>With <varname>ConditionPathExists=</varname> a file + existence condition is checked before a unit is started. If + the specified absolute path name does not exist, the condition + will fail. If the absolute path name passed to + <varname>ConditionPathExists=</varname> is prefixed with an + exclamation mark (<literal>!</literal>), the test is negated, + and the unit is only started if the path does not + exist.</para> + + <para><varname>ConditionPathExistsGlob=</varname> is similar + to <varname>ConditionPathExists=</varname>, but checks for the + existence of at least one file or directory matching the + specified globbing pattern.</para> + + <para><varname>ConditionPathIsDirectory=</varname> is similar + to <varname>ConditionPathExists=</varname> but verifies + whether a certain path exists and is a directory.</para> + + <para><varname>ConditionPathIsSymbolicLink=</varname> is + similar to <varname>ConditionPathExists=</varname> but + verifies whether a certain path exists and is a symbolic + link.</para> + + <para><varname>ConditionPathIsMountPoint=</varname> is similar + to <varname>ConditionPathExists=</varname> but verifies + whether a certain path exists and is a mount point.</para> + + <para><varname>ConditionPathIsReadWrite=</varname> is similar + to <varname>ConditionPathExists=</varname> but verifies + whether the underlying file system is readable and writable + (i.e. not mounted read-only).</para> + + <para><varname>ConditionDirectoryNotEmpty=</varname> is + similar to <varname>ConditionPathExists=</varname> but + verifies whether a certain path exists and is a non-empty + directory.</para> + + <para><varname>ConditionFileNotEmpty=</varname> is similar to + <varname>ConditionPathExists=</varname> but verifies whether a + certain path exists and refers to a regular file with a + non-zero size.</para> + + <para><varname>ConditionFileIsExecutable=</varname> is similar + to <varname>ConditionPathExists=</varname> but verifies + whether a certain path exists, is a regular file and marked + executable.</para> + + <para>If multiple conditions are specified, the unit will be + executed if all of them apply (i.e. a logical AND is applied). + Condition checks can be prefixed with a pipe symbol (|) in + which case a condition becomes a triggering condition. If at + least one triggering condition is defined for a unit, then the + unit will be executed if at least one of the triggering + conditions apply and all of the non-triggering conditions. If + you prefix an argument with the pipe symbol and an exclamation + mark, the pipe symbol must be passed first, the exclamation + second. Except for + <varname>ConditionPathIsSymbolicLink=</varname>, all path + checks follow symlinks. If any of these options is assigned + the empty string, the list of conditions is reset completely, + all previous condition settings (of any kind) will have no + effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AssertArchitecture=</varname></term> + <term><varname>AssertVirtualization=</varname></term> + <term><varname>AssertHost=</varname></term> + <term><varname>AssertKernelCommandLine=</varname></term> + <term><varname>AssertSecurity=</varname></term> + <term><varname>AssertCapability=</varname></term> + <term><varname>AssertACPower=</varname></term> + <term><varname>AssertNeedsUpdate=</varname></term> + <term><varname>AssertFirstBoot=</varname></term> + <term><varname>AssertPathExists=</varname></term> + <term><varname>AssertPathExistsGlob=</varname></term> + <term><varname>AssertPathIsDirectory=</varname></term> + <term><varname>AssertPathIsSymbolicLink=</varname></term> + <term><varname>AssertPathIsMountPoint=</varname></term> + <term><varname>AssertPathIsReadWrite=</varname></term> + <term><varname>AssertDirectoryNotEmpty=</varname></term> + <term><varname>AssertFileNotEmpty=</varname></term> + <term><varname>AssertFileIsExecutable=</varname></term> + + <listitem><para>Similar to the + <varname>ConditionArchitecture=</varname>, + <varname>ConditionVirtualization=</varname>, ... condition + settings described above these settings add assertion checks + to the start-up of the unit. However, unlike the conditions + settings any assertion setting that is not met results in + failure of the start job it was triggered + by.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SourcePath=</varname></term> + <listitem><para>A path to a configuration file this unit has + been generated from. This is primarily useful for + implementation of generator tools that convert configuration + from an external configuration file format into native unit + files. This functionality should not be used in normal + units.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>[Install] Section Options</title> + + <para>Unit file may include an <literal>[Install]</literal> + section, which carries installation information for the unit. This + section is not interpreted by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + during runtime. It is used exclusively by the + <command>enable</command> and <command>disable</command> commands + of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool during installation of a unit:</para> + + <variablelist class='unit-directives'> + <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> + </varlistentry> + + <varlistentry> + <term><varname>WantedBy=</varname></term> + <term><varname>RequiredBy=</varname></term> + + <listitem><para>This option may be used more than once, or a + space-separated list of unit names may be given. A symbolic + link is created in the <filename>.wants/</filename> or + <filename>.requires/</filename> directory of each of the + listed units when this unit is installed by <command>systemctl + enable</command>. This has the effect that a dependency of + type <varname>Wants=</varname> or <varname>Requires=</varname> + is added from the listed unit to the current unit. The primary + result is that the current unit will be started when the + listed unit is started. See the description of + <varname>Wants=</varname> and <varname>Requires=</varname> in + the [Unit] section for details.</para> + + <para><command>WantedBy=foo.service</command> in a service + <filename>bar.service</filename> is mostly equivalent to + <command>Alias=foo.service.wants/bar.service</command> in the + same file. In case of template units, <command>systemctl + enable</command> must be called with an instance name, and + this instance will be added to the + <filename>.wants/</filename> or + <filename>.requires/</filename> list of the listed unit. E.g. + <command>WantedBy=getty.target</command> in a service + <filename>getty@.service</filename> will result in + <command>systemctl enable getty@tty2.service</command> + creating a + <filename>getty.target.wants/getty@tty2.service</filename> + link to <filename>getty@.service</filename>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Also=</varname></term> + + <listitem><para>Additional units to install/deinstall when + this unit is installed/deinstalled. If the user requests + installation/deinstallation of a unit with this option + configured, <command>systemctl enable</command> and + <command>systemctl disable</command> will automatically + install/uninstall units listed in this option as well.</para> + + <para>This option may be used more than once, or a + space-separated list of unit names may be + given.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultInstance=</varname></term> + + <listitem><para>In template unit files, this specifies for + which instance the unit shall be enabled if the template is + enabled without any explicitly set instance. This option has + no effect in non-template unit files. The specified string + must be usable as instance identifier.</para></listitem> + </varlistentry> + </variablelist> + + <para>The following specifiers are interpreted in the Install + section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v. For their meaning + see the next section. + </para> + </refsect1> + + <refsect1> + <title>Specifiers</title> + + <para>Many settings resolve specifiers which may be used to write + generic unit files referring to runtime or unit parameters that + are replaced when the unit files are loaded. The following + specifiers are understood:</para> + + <table> + <title>Specifiers available in unit files</title> + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname="spec" /> + <colspec colname="mean" /> + <colspec colname="detail" /> + <thead> + <row> + <entry>Specifier</entry> + <entry>Meaning</entry> + <entry>Details</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>%n</literal></entry> + <entry>Full unit name</entry> + <entry></entry> + </row> + <row> + <entry><literal>%N</literal></entry> + <entry>Unescaped full unit name</entry> + <entry>Same as <literal>%n</literal>, but with escaping undone</entry> + </row> + <row> + <entry><literal>%p</literal></entry> + <entry>Prefix name</entry> + <entry>For instantiated units, this refers to the string before the <literal>@</literal> character of the unit name. For non-instantiated units, this refers to the name of the unit with the type suffix removed.</entry> + </row> + <row> + <entry><literal>%P</literal></entry> + <entry>Unescaped prefix name</entry> + <entry>Same as <literal>%p</literal>, but with escaping undone</entry> + </row> + <row> + <entry><literal>%i</literal></entry> + <entry>Instance name</entry> + <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix of the unit name.</entry> + </row> + <row> + <entry><literal>%I</literal></entry> + <entry>Unescaped instance name</entry> + <entry>Same as <literal>%i</literal>, but with escaping undone</entry> + </row> + <row> + <entry><literal>%f</literal></entry> + <entry>Unescaped filename</entry> + <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the prefix name prepended with <filename>/</filename>.</entry> + </row> + <row> + <entry><literal>%c</literal></entry> + <entry>Control group path of the unit</entry> + <entry>This path does not include the <filename>/sys/fs/cgroup/systemd/</filename> prefix.</entry> + </row> + <row> + <entry><literal>%r</literal></entry> + <entry>Control group path of the slice the unit is placed in</entry> + <entry>This usually maps to the parent cgroup path of <literal>%c</literal>.</entry> + </row> + <row> + <entry><literal>%R</literal></entry> + <entry>Root control group path below which slices and units are placed</entry> + <entry>For system instances, this resolves to <filename>/</filename>, except in containers, where this maps to the container's root control group path.</entry> + </row> + <row> + <entry><literal>%t</literal></entry> + <entry>Runtime directory</entry> + <entry>This is either <filename>/run</filename> (for the system manager) or the path <literal>$XDG_RUNTIME_DIR</literal> resolves to (for user managers).</entry> + </row> + <row> + <entry><literal>%u</literal></entry> + <entry>User name</entry> + <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry> + </row> + <row> + <entry><literal>%U</literal></entry> + <entry>User UID</entry> + <entry>This is the numeric UID of the configured user of the unit, or (if none is set) the user running the systemd user instance. Note that this specifier is not available for units run by the systemd system instance (as opposed to those run by a systemd user instance), unless the user has been configured as a numeric UID in the first place or the configured user is the root user.</entry> + </row> + <row> + <entry><literal>%h</literal></entry> + <entry>User home directory</entry> + <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry> + </row> + <row> + <entry><literal>%s</literal></entry> + <entry>User shell</entry> + <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry> + </row> + <row> + <entry><literal>%m</literal></entry> + <entry>Machine ID</entry> + <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry> + </row> + <row> + <entry><literal>%b</literal></entry> + <entry>Boot ID</entry> + <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry> + </row> + <row> + <entry><literal>%H</literal></entry> + <entry>Host name</entry> + <entry>The hostname of the running system at the point in time the unit configuation is loaded.</entry> + </row> + <row> + <entry><literal>%v</literal></entry> + <entry>Kernel release</entry> + <entry>Identical to <command>uname -r</command> output</entry> + </row> + <row> + <entry><literal>%%</literal></entry> + <entry>Single percent sign</entry> + <entry>Use <literal>%%</literal> in place of <literal>%</literal> to specify a single percent sign.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Please note that specifiers <literal>%U</literal>, + <literal>%h</literal>, <literal>%s</literal> are mostly useless + when systemd is running in system mode. PID 1 cannot query the + user account database for information, so the specifiers only work + as shortcuts for things which are already specified in a different + way in the unit file. They are fully functional when systemd is + running in <option>--user</option> mode.</para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Allowing units to be enabled</title> + + <para>The following snippet (highlighted) allows a unit (e.g. + <filename>foo.service</filename>) to be enabled via + <command>systemctl enable</command>:</para> + + <programlisting>[Unit] Description=Foo [Service] @@ -1594,70 +1294,59 @@ ExecStart=/usr/sbin/foo-daemon <emphasis>[Install]</emphasis> <emphasis>WantedBy=multi-user.target</emphasis></programlisting> - <para>After running - <command>systemctl enable</command>, a symlink - <filename>/etc/systemd/system/multi-user.target.wants/foo.service</filename> - linking to the actual unit will be created. It - tells systemd to pull in the unit when starting - <filename>multi-user.target</filename>. The - inverse <command>systemctl disable</command> - will remove that symlink again.</para> - </example> - - <example> - <title>Overriding vendor settings</title> - - <para>There are two methods of overriding - vendor settings in unit files: copying the unit - file from - <filename>/usr/lib/systemd/system</filename> - to <filename>/etc/systemd/system</filename> and - modifying the chosen settings. Alternatively, - one can create a directory named - <filename><replaceable>unit</replaceable>.d/</filename> - within - <filename>/etc/systemd/system</filename> and - place a drop-in file - <filename><replaceable>name</replaceable>.conf</filename> - there that only changes the specific settings - one is interested in. Note that multiple such - drop-in files are read if present.</para> - - <para>The advantage of the first method is - that one easily overrides the complete unit, - the vendor unit is not parsed at all anymore. - It has the disadvantage that improvements to - the unit file by the vendor are not - automatically incorporated on updates.</para> - - <para>The advantage of the second method is - that one only overrides the settings one - specifically wants, where updates to the unit - by the vendor automatically apply. This has the - disadvantage that some future updates by the - vendor might be incompatible with the local - changes.</para> - - <para>Note that for drop-in files, if one wants - to remove entries from a setting that is parsed - as a list (and is not a dependency), such as - <varname>ConditionPathExists=</varname> (or - e.g. <varname>ExecStart=</varname> in service - units), one needs to first clear the list - before re-adding all entries except the one - that is to be removed. See below for an - example.</para> - - <para>This also applies for user instances of - systemd, but with different locations for the - unit files. See the section on unit load paths - for further details.</para> - - <para>Suppose there is a vendor-supplied unit - <filename>/usr/lib/systemd/system/httpd.service</filename> - with the following contents:</para> - - <programlisting>[Unit] + <para>After running <command>systemctl enable</command>, a + symlink + <filename>/etc/systemd/system/multi-user.target.wants/foo.service</filename> + linking to the actual unit will be created. It tells systemd to + pull in the unit when starting + <filename>multi-user.target</filename>. The inverse + <command>systemctl disable</command> will remove that symlink + again.</para> + </example> + + <example> + <title>Overriding vendor settings</title> + + <para>There are two methods of overriding vendor settings in + unit files: copying the unit file from + <filename>/usr/lib/systemd/system</filename> to + <filename>/etc/systemd/system</filename> and modifying the + chosen settings. Alternatively, one can create a directory named + <filename><replaceable>unit</replaceable>.d/</filename> within + <filename>/etc/systemd/system</filename> and place a drop-in + file <filename><replaceable>name</replaceable>.conf</filename> + there that only changes the specific settings one is interested + in. Note that multiple such drop-in files are read if + present.</para> + + <para>The advantage of the first method is that one easily + overrides the complete unit, the vendor unit is not parsed at + all anymore. It has the disadvantage that improvements to the + unit file by the vendor are not automatically incorporated on + updates.</para> + + <para>The advantage of the second method is that one only + overrides the settings one specifically wants, where updates to + the unit by the vendor automatically apply. This has the + disadvantage that some future updates by the vendor might be + incompatible with the local changes.</para> + + <para>Note that for drop-in files, if one wants to remove + entries from a setting that is parsed as a list (and is not a + dependency), such as <varname>ConditionPathExists=</varname> (or + e.g. <varname>ExecStart=</varname> in service units), one needs + to first clear the list before re-adding all entries except the + one that is to be removed. See below for an example.</para> + + <para>This also applies for user instances of systemd, but with + different locations for the unit files. See the section on unit + load paths for further details.</para> + + <para>Suppose there is a vendor-supplied unit + <filename>/usr/lib/systemd/system/httpd.service</filename> with + the following contents:</para> + + <programlisting>[Unit] Description=Some HTTP server After=remote-fs.target sqldb.service Requires=sqldb.service @@ -1671,34 +1360,25 @@ Nice=5 [Install] WantedBy=multi-user.target</programlisting> - <para>Now one wants to change some settings as - an administrator: firstly, in the local setup, - <filename>/srv/webserver</filename> might not - exit, because the HTTP server is configured to - use <filename>/srv/www</filename> instead. - Secondly, the local configuration makes the - HTTP server also depend on a memory cache - service, - <filename>memcached.service</filename>, that - should be pulled in - (<varname>Requires=</varname>) and also be - ordered appropriately - (<varname>After=</varname>). Thirdly, in order - to harden the service a bit more, the - administrator would like to set the - <varname>PrivateTmp=</varname> - setting (see - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). And lastly, the administrator - would like to reset the niceness of the service - to its default value of 0.</para> - - <para>The first possibility is to copy the unit - file to - <filename>/etc/systemd/system/httpd.service</filename> - and change the chosen settings:</para> - - <programlisting>[Unit] + <para>Now one wants to change some settings as an administrator: + firstly, in the local setup, <filename>/srv/webserver</filename> + might not exit, because the HTTP server is configured to use + <filename>/srv/www</filename> instead. Secondly, the local + configuration makes the HTTP server also depend on a memory + cache service, <filename>memcached.service</filename>, that + should be pulled in (<varname>Requires=</varname>) and also be + ordered appropriately (<varname>After=</varname>). Thirdly, in + order to harden the service a bit more, the administrator would + like to set the <varname>PrivateTmp=</varname> setting (see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). And lastly, the administrator would like to reset + the niceness of the service to its default value of 0.</para> + + <para>The first possibility is to copy the unit file to + <filename>/etc/systemd/system/httpd.service</filename> and + change the chosen settings:</para> + + <programlisting>[Unit] Description=Some HTTP server After=remote-fs.target sqldb.service <emphasis>memcached.service</emphasis> Requires=sqldb.service <emphasis>memcached.service</emphasis> @@ -1713,12 +1393,12 @@ ExecStart=/usr/sbin/some-fancy-httpd-server [Install] WantedBy=multi-user.target</programlisting> - <para>Alternatively, the administrator could - create a drop-in file - <filename>/etc/systemd/system/httpd.service.d/local.conf</filename> - with the following contents:</para> + <para>Alternatively, the administrator could create a drop-in + file + <filename>/etc/systemd/system/httpd.service.d/local.conf</filename> + with the following contents:</para> - <programlisting>[Unit] + <programlisting>[Unit] After=memcached.service Requires=memcached.service # Reset all assertions and then re-add the condition we want @@ -1729,39 +1409,37 @@ AssertPathExists=/srv/www Nice=0 PrivateTmp=yes</programlisting> - <para>Note that dependencies - (<varname>After=</varname>, etc.) cannot be - reset to an empty list, so dependencies can - only be added in drop-ins. If you want to - remove dependencies, you have to override the - entire unit.</para> - </example> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + <para>Note that dependencies (<varname>After=</varname>, etc.) + cannot be reset to an empty list, so dependencies can only be + added in drop-ins. If you want to remove dependencies, you have + to override the entire unit.</para> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/systemd.xml b/man/systemd.xml index d020582b53..80591dc732 100644 --- a/man/systemd.xml +++ b/man/systemd.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,1269 +22,1075 @@ --> <refentry id="systemd" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd</refname> - <refname>init</refname> - <refpurpose>systemd system and service manager</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd <arg choice="opt" rep="repeat">OPTIONS</arg></command> - </cmdsynopsis> - <cmdsynopsis> - <command>init <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>systemd is a system and service manager for - Linux operating systems. When run as first process on - boot (as PID 1), it acts as init system that brings - up and maintains userspace services.</para> - - <para>For compatibility with SysV, if systemd is called - as <command>init</command> and a PID that is not - 1, it will execute <command>telinit</command> and pass - all command line arguments unmodified. That means - <command>init</command> and <command>telinit</command> - are mostly equivalent when invoked from normal login sessions. See - <citerefentry><refentrytitle>telinit</refentrytitle><manvolnum>8</manvolnum></citerefentry> - for more information.</para> - - <para>When run as a system instance, systemd interprets the - configuration file <filename>system.conf</filename> and the - files in <filename>system.conf.d</filename> directories; when - run as a user instance, systemd interprets the configuration - file <filename>user.conf</filename> and the files in - <filename>user.conf.d</filename> directories. See - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--test</option></term> - - <listitem><para>Determine startup - sequence, dump it and exit. This is an - option useful for debugging - only.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--dump-configuration-items</option></term> - - <listitem><para>Dump understood unit - configuration items. This outputs a - terse but complete list of - configuration items understood in unit - definition files.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--unit=</option></term> - - <listitem><para>Set default unit to - activate on startup. If not specified, - defaults to - <filename>default.target</filename>.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--system</option></term> - <term><option>--user</option></term> - - <listitem><para>For <option>--system</option>, - tell systemd to run a - system instance, even if the process ID is - not 1, i.e. systemd is not run as init process. - <option>--user</option> does the opposite, - running a user instance even if the process - ID is 1. - Normally it should not be necessary to - pass these options, as systemd - automatically detects the mode it is - started in. These options are hence of - little use except for debugging. Note - that it is not supported booting and - maintaining a full system with systemd - running in <option>--system</option> - mode, but PID not 1. In practice, - passing <option>--system</option> explicitly is - only useful in conjunction with - <option>--test</option>.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--dump-core</option></term> - - <listitem><para>Dump core on - crash. This switch has no effect when - run as user - instance.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--crash-shell</option></term> - - <listitem><para>Run shell on - crash. This switch has no effect when - run as user - instance.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--confirm-spawn</option></term> - - <listitem><para>Ask for confirmation - when spawning processes. This switch - has no effect when run as user - instance.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--show-status=</option></term> - - <listitem><para>Show terse service - status information while booting. This - switch has no effect when run as user - instance. Takes a boolean argument - which may be omitted which is - interpreted as - <option>true</option>.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--log-target=</option></term> - - <listitem><para>Set log - target. Argument must be one of - <option>console</option>, - <option>journal</option>, - <option>kmsg</option>, - <option>journal-or-kmsg</option>, - <option>null</option>.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--log-level=</option></term> - - <listitem><para>Set log level. As - argument this accepts a numerical log - level or the well-known <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> - symbolic names (lowercase): - <option>emerg</option>, - <option>alert</option>, - <option>crit</option>, - <option>err</option>, - <option>warning</option>, - <option>notice</option>, - <option>info</option>, - <option>debug</option>.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--log-color=</option></term> - - <listitem><para>Highlight important - log messages. Argument is a boolean - value. If the argument is omitted, it - defaults to - <option>true</option>.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--log-location=</option></term> - - <listitem><para>Include code location - in log messages. This is mostly - relevant for debugging - purposes. Argument is a boolean - value. If the argument is omitted - it defaults to - <option>true</option>.</para></listitem> - </varlistentry> - <varlistentry> - <term><option>--default-standard-output=</option></term> - <term><option>--default-standard-error=</option></term> - - <listitem><para>Sets the default - output or error output for all - services and sockets, respectively. That is, controls - the default for - <option>StandardOutput=</option> - and <option>StandardError=</option> - (see - <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). Takes one of - <option>inherit</option>, - <option>null</option>, - <option>tty</option>, - <option>journal</option>, - <option>journal+console</option>, - <option>syslog</option>, - <option>syslog+console</option>, - <option>kmsg</option>, - <option>kmsg+console</option>. If the - argument is omitted - <option>--default-standard-output=</option> - defaults to <option>journal</option> - and - <option>--default-standard-error=</option> - to - <option>inherit</option>.</para></listitem> - </varlistentry> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - </refsect1> - - <refsect1> - <title>Concepts</title> - - <para>systemd provides a dependency system between - various entities called "units" of 12 different - types. Units encapsulate various objects that are - relevant for system boot-up and maintenance. The - majority of units are configured in unit configuration - files, whose syntax and basic set of options is - described in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - however some are created automatically from other - configuration, dynamically from system state or - programmatically at runtime. Units may be "active" - (meaning started, bound, plugged in, ..., depending on - the unit type, see below), or "inactive" (meaning - stopped, unbound, unplugged, ...), as well as in the - process of being activated or deactivated, - i.e. between the two states (these states are called - "activating", "deactivating"). A special "failed" - state is available as well, which is very similar to - "inactive" and is entered when the service failed in - some way (process returned error code on exit, or - crashed, or an operation timed out). If this state is - entered, the cause will be logged, for later - reference. Note that the various unit types may have a - number of additional substates, which are mapped to - the five generalized unit states described - here.</para> - - <para>The following unit types are available:</para> - - <orderedlist> - <listitem><para>Service units, which start and control - daemons and the processes they consist of. For - details see - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Socket units, which - encapsulate local IPC or network sockets in - the system, useful for socket-based - activation. For details about socket units see - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - for details on socket-based activation and - other forms of activation, see - <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Target units are useful to - group units, or provide well-known - synchronization points during boot-up, see - <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Device units expose kernel - devices in systemd and may be used to - implement device-based activation. For details - see - <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Mount units control mount - points in the file system, for details see - <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Automount units provide - automount capabilities, for on-demand mounting - of file systems as well as parallelized - boot-up. See - <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Snapshot units can be used to - temporarily save the state of the set of - systemd units, which later may be restored by - activating the saved snapshot unit. For more - information see - <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Timer units are useful for - triggering activation of other units based on - timers. You may find details in - <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Swap units are very similar to - mount units and encapsulate memory swap - partitions or files of the operating - system. They are described in <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Path units may be used - to activate other services when file system - objects change or are modified. See - <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Slice units may be used to - group units which manage system processes - (such as service and scope units) in a - hierarchical tree for resource management - purposes. See - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - <listitem><para>Scope units are similar to - service units, but manage foreign processes - instead of starting them as well. See - <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> - - </orderedlist> - - <para>Units are named as their configuration - files. Some units have special semantics. A detailed - list is available in - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - - <para>systemd knows various kinds of dependencies, - including positive and negative requirement - dependencies (i.e. <varname>Requires=</varname> and - <varname>Conflicts=</varname>) as well as ordering - dependencies (<varname>After=</varname> and - <varname>Before=</varname>). NB: ordering and - requirement dependencies are orthogonal. If only a - requirement dependency exists between two units - (e.g. <filename>foo.service</filename> requires - <filename>bar.service</filename>), but no ordering - dependency (e.g. <filename>foo.service</filename> - after <filename>bar.service</filename>) and both are - requested to start, they will be started in - parallel. It is a common pattern that both requirement - and ordering dependencies are placed between two - units. Also note that the majority of dependencies are - implicitly created and maintained by systemd. In most - cases, it should be unnecessary to declare additional - dependencies manually, however it is possible to do - this.</para> - - <para>Application programs and units (via - dependencies) may request state changes of units. In - systemd, these requests are encapsulated as 'jobs' and - maintained in a job queue. Jobs may succeed or can - fail, their execution is ordered based on the ordering - dependencies of the units they have been scheduled - for.</para> - - <para>On boot systemd activates the target unit - <filename>default.target</filename> whose job is to - activate on-boot services and other on-boot units by - pulling them in via dependencies. Usually the unit - name is just an alias (symlink) for either - <filename>graphical.target</filename> (for - fully-featured boots into the UI) or - <filename>multi-user.target</filename> (for limited - console-only boots for use in embedded or server - environments, or similar; a subset of - graphical.target). However, it is at the discretion of - the administrator to configure it as an alias to any - other target unit. See - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details about these target units.</para> - - <para>Processes systemd spawns are placed in - individual Linux control groups named after the unit - which they belong to in the private systemd - hierarchy. (see <ulink - url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink> - for more information about control groups, or short - "cgroups"). systemd uses this to effectively keep - track of processes. Control group information is - maintained in the kernel, and is accessible via the - file system hierarchy (beneath - <filename>/sys/fs/cgroup/systemd/</filename>), or in tools - such as - <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> - (<command>ps xawf -eo pid,user,cgroup,args</command> - is particularly useful to list all processes and the - systemd units they belong to.).</para> - - <para>systemd is compatible with the SysV init system - to a large degree: SysV init scripts are supported and - simply read as an alternative (though limited) - configuration file format. The SysV - <filename>/dev/initctl</filename> interface is - provided, and compatibility implementations of the - various SysV client tools are available. In addition to - that, various established Unix functionality such as - <filename>/etc/fstab</filename> or the - <filename>utmp</filename> database are - supported.</para> - - <para>systemd has a minimal transaction system: if a - unit is requested to start up or shut down it will add - it and all its dependencies to a temporary - transaction. Then, it will verify if the transaction - is consistent (i.e. whether the ordering of all units - is cycle-free). If it is not, systemd will try to fix - it up, and removes non-essential jobs from the - transaction that might remove the loop. Also, systemd - tries to suppress non-essential jobs in the - transaction that would stop a running service. Finally - it is checked whether the jobs of the transaction - contradict jobs that have already been queued, and - optionally the transaction is aborted then. If all - worked out and the transaction is consistent and - minimized in its impact it is merged with all already - outstanding jobs and added to the run - queue. Effectively this means that before executing a - requested operation, systemd will verify that it makes - sense, fixing it if possible, and only failing if it - really cannot work.</para> - - <para>Systemd contains native implementations of - various tasks that need to be executed as part of the - boot process. For example, it sets the hostname or - configures the loopback network device. It also sets - up and mounts various API file systems, such as - <filename>/sys</filename> or - <filename>/proc</filename>.</para> - - <para>For more information about the concepts and - ideas behind systemd, please refer to the <ulink - url="http://0pointer.de/blog/projects/systemd.html">Original - Design Document</ulink>.</para> - - <para>Note that some but not all interfaces provided - by systemd are covered by the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface - Stability Promise</ulink>.</para> - - <para>Units may be generated dynamically at boot and - system manager reload time, for example based on other - configuration files or parameters passed on the kernel - command line. For details see the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/Generators">Generators - Specification</ulink>.</para> - - <para>Systems which invoke systemd in a container - or initrd environment should implement the - <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container - Interface</ulink> or <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/InitrdInterface">initrd - Interface</ulink> specifications, respectively.</para> - </refsect1> - - <refsect1> - <title>Directories</title> - - <variablelist> - <varlistentry> - <term>System unit directories</term> - - <listitem><para>The systemd system - manager reads unit configuration from - various directories. Packages that - want to install unit files shall place - them in the directory returned by - <command>pkg-config systemd - --variable=systemdsystemunitdir</command>. Other - directories checked are - <filename>/usr/local/lib/systemd/system</filename> - and - <filename>/usr/lib/systemd/system</filename>. User - configuration always takes - precedence. <command>pkg-config - systemd - --variable=systemdsystemconfdir</command> - returns the path of the system - configuration directory. Packages - should alter the content of these - directories only with the - <command>enable</command> and - <command>disable</command> commands of - the - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool. Full list of directories is provided in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - </variablelist> - - <variablelist> - <varlistentry> - <term>User unit directories</term> - - <listitem><para>Similar rules apply - for the user unit - directories. However, here the <ulink - url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG - Base Directory specification</ulink> - is followed to find - units. Applications should place their - unit files in the directory returned - by <command>pkg-config systemd - --variable=systemduserunitdir</command>. Global - configuration is done in the directory - reported by <command>pkg-config - systemd - --variable=systemduserconfdir</command>. The - <command>enable</command> and - <command>disable</command> commands of - the - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool can handle both global (i.e. for - all users) and private (for one user) - enabling/disabling of - units. Full list of directories is provided in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - </variablelist> - - <variablelist> - <varlistentry> - <term>SysV init scripts directory</term> - - <listitem><para>The location of the - SysV init script directory varies - between distributions. If systemd - cannot find a native unit file for a - requested service, it will look for a - SysV init script of the same name - (with the - <filename>.service</filename> suffix - removed).</para></listitem> - </varlistentry> - </variablelist> - - <variablelist> - <varlistentry> - <term>SysV runlevel link farm directory</term> - - <listitem><para>The location of the - SysV runlevel link farm directory - varies between distributions. systemd - will take the link farm into account - when figuring out whether a service - shall be enabled. Note that a service - unit with a native unit configuration - file cannot be started by activating it - in the SysV runlevel link - farm.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Signals</title> - - <variablelist> - <varlistentry> - <term><constant>SIGTERM</constant></term> - - <listitem><para>Upon receiving this - signal the systemd system manager - serializes its state, reexecutes - itself and deserializes the saved - state again. This is mostly equivalent - to <command>systemctl - daemon-reexec</command>.</para> - - <para>systemd user managers will - start the - <filename>exit.target</filename> unit - when this signal is received. This is - mostly equivalent to - <command>systemctl --user start - exit.target</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGINT</constant></term> - - <listitem><para>Upon receiving this - signal the systemd system manager will - start the - <filename>ctrl-alt-del.target</filename> - unit. This is mostly equivalent to - <command>systemctl start - ctl-alt-del.target</command>. If this - signal is received more often than 7 - times per 2s an immediate reboot is - triggered. Note that pressing - Ctrl-Alt-Del on the console will - trigger this signal. Hence, if a - reboot is hanging pressing - Ctrl-Alt-Del more than 7 times in 2s - is a relatively safe way to trigger an - immediate reboot.</para> - - <para>systemd user managers - treat this signal the same way as - <constant>SIGTERM</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGWINCH</constant></term> - - <listitem><para>When this signal is - received the systemd system manager - will start the - <filename>kbrequest.target</filename> - unit. This is mostly equivalent to - <command>systemctl start - kbrequest.target</command>.</para> - - <para>This signal is ignored by - systemd user - managers.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGPWR</constant></term> - - <listitem><para>When this signal is - received the systemd manager - will start the - <filename>sigpwr.target</filename> - unit. This is mostly equivalent to - <command>systemctl start - sigpwr.target</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGUSR1</constant></term> - - <listitem><para>When this signal is - received the systemd manager will try - to reconnect to the D-Bus - bus.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGUSR2</constant></term> - - <listitem><para>When this signal is - received the systemd manager will log - its complete state in human readable - form. The data logged is the same as - printed by <command>systemd-analyze - dump</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGHUP</constant></term> - - <listitem><para>Reloads the complete - daemon configuration. This is mostly - equivalent to <command>systemctl - daemon-reload</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+0</constant></term> - - <listitem><para>Enters default mode, starts the - <filename>default.target</filename> - unit. This is mostly equivalent to - <command>systemctl start - default.target</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+1</constant></term> - - <listitem><para>Enters rescue mode, - starts the - <filename>rescue.target</filename> - unit. This is mostly equivalent to - <command>systemctl isolate - rescue.target</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+2</constant></term> - - <listitem><para>Enters emergency mode, - starts the - <filename>emergency.service</filename> - unit. This is mostly equivalent to - <command>systemctl isolate - emergency.service</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+3</constant></term> - - <listitem><para>Halts the machine, - starts the - <filename>halt.target</filename> - unit. This is mostly equivalent to - <command>systemctl start - halt.target</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+4</constant></term> - - <listitem><para>Powers off the machine, - starts the - <filename>poweroff.target</filename> - unit. This is mostly equivalent to - <command>systemctl start - poweroff.target</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+5</constant></term> - - <listitem><para>Reboots the machine, - starts the - <filename>reboot.target</filename> - unit. This is mostly equivalent to - <command>systemctl start - reboot.target</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+6</constant></term> - - <listitem><para>Reboots the machine via kexec, - starts the - <filename>kexec.target</filename> - unit. This is mostly equivalent to - <command>systemctl start - kexec.target</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+13</constant></term> - - <listitem><para>Immediately halts the machine.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+14</constant></term> - - <listitem><para>Immediately powers off the machine.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+15</constant></term> - - <listitem><para>Immediately reboots the machine.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+16</constant></term> - - <listitem><para>Immediately reboots the machine with kexec.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+20</constant></term> - - <listitem><para>Enables display of - status messages on the console, as - controlled via - <varname>systemd.show_status=1</varname> - on the kernel command - line.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+21</constant></term> - - <listitem><para>Disables display of - status messages on the console, as - controlled via - <varname>systemd.show_status=0</varname> - on the kernel command - line.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+22</constant></term> - <term><constant>SIGRTMIN+23</constant></term> - - <listitem><para>Sets the log level to - <literal>debug</literal> - (or <literal>info</literal> on - <constant>SIGRTMIN+23</constant>), as - controlled via - <varname>systemd.log_level=debug</varname> - (or <varname>systemd.log_level=info</varname> - on <constant>SIGRTMIN+23</constant>) on - the kernel command - line.</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+24</constant></term> - - <listitem><para>Immediately exits the - manager (only available for --user - instances).</para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>SIGRTMIN+26</constant></term> - <term><constant>SIGRTMIN+27</constant></term> - <term><constant>SIGRTMIN+28</constant></term> - - <listitem><para>Sets the log level to - <literal>journal-or-kmsg</literal> (or - <literal>console</literal> on - <constant>SIGRTMIN+27</constant>, - <literal>kmsg</literal> on - <constant>SIGRTMIN+28</constant>), as - controlled via - <varname>systemd.log_target=journal-or-kmsg</varname> - (or - <varname>systemd.log_target=console</varname> - on <constant>SIGRTMIN+27</constant> or - <varname>systemd.log_target=kmsg</varname> - on <constant>SIGRTMIN+28</constant>) - on the kernel command - line.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Environment</title> - - <variablelist class='environment-variables'> - <varlistentry> - <term><varname>$SYSTEMD_LOG_LEVEL</varname></term> - <listitem><para>systemd reads the - log level from this environment - variable. This can be overridden with - <option>--log-level=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$SYSTEMD_LOG_TARGET</varname></term> - <listitem><para>systemd reads the - log target from this environment - variable. This can be overridden with - <option>--log-target=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$SYSTEMD_LOG_COLOR</varname></term> - <listitem><para>Controls whether - systemd highlights important log - messages. This can be overridden with - <option>--log-color=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$SYSTEMD_LOG_LOCATION</varname></term> - <listitem><para>Controls whether - systemd prints the code location along - with log messages. This can be - overridden with - <option>--log-location=</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$XDG_CONFIG_HOME</varname></term> - <term><varname>$XDG_CONFIG_DIRS</varname></term> - <term><varname>$XDG_DATA_HOME</varname></term> - <term><varname>$XDG_DATA_DIRS</varname></term> - - <listitem><para>The systemd user - manager uses these variables in - accordance to the <ulink - url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG - Base Directory specification</ulink> - to find its configuration.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$SYSTEMD_UNIT_PATH</varname></term> - - <listitem><para>Controls where systemd - looks for unit - files.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$SYSTEMD_SYSVINIT_PATH</varname></term> - - <listitem><para>Controls where systemd - looks for SysV init scripts.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$SYSTEMD_SYSVRCND_PATH</varname></term> - - <listitem><para>Controls where systemd - looks for SysV init script runlevel link - farms.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$LISTEN_PID</varname></term> - <term><varname>$LISTEN_FDS</varname></term> - - <listitem><para>Set by systemd for - supervised processes during - socket-based activation. See - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>$NOTIFY_SOCKET</varname></term> - - <listitem><para>Set by systemd for - supervised processes for status and - start-up completion notification. See - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> - for more information. - </para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Kernel Command Line</title> - - <para>When run as system instance systemd parses a - number of kernel command line - arguments<footnote><para>If run inside a Linux - container these arguments may be passed as command - line arguments to systemd itself, next to any of the - command line options listed in the Options section - above. If run outside of Linux containers, these - arguments are parsed from - <filename>/proc/cmdline</filename> - instead.</para></footnote>:</para> - - <variablelist class='kernel-commandline-options'> - <varlistentry> - <term><varname>systemd.unit=</varname></term> - <term><varname>rd.systemd.unit=</varname></term> - - <listitem><para>Overrides the unit to - activate on boot. Defaults to - <filename>default.target</filename>. This - may be used to temporarily boot into a - different boot unit, for example - <filename>rescue.target</filename> or - <filename>emergency.service</filename>. See - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> - for details about these units. The - option prefixed with - <literal>rd.</literal> is honored - only in the initial RAM disk (initrd), - while the one that is not prefixed only - in the main system.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.dump_core=</varname></term> - - <listitem><para>Takes a boolean - argument. If <option>true</option>, - systemd dumps core when it - crashes. Otherwise, no core dump is - created. Defaults to - <option>true</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.crash_shell=</varname></term> - - <listitem><para>Takes a boolean - argument. If <option>true</option>, - systemd spawns a shell when it - crashes. Otherwise, no shell is - spawned. Defaults to - <option>false</option>, for security - reasons, as the shell is not protected - by any password - authentication.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.crash_chvt=</varname></term> - - <listitem><para>Takes an integer - argument. If positive systemd - activates the specified virtual - terminal when it crashes. Defaults to - <constant>-1</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.confirm_spawn=</varname></term> - - <listitem><para>Takes a boolean - argument. If <option>true</option>, - asks for confirmation when spawning - processes. Defaults to - <option>false</option>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.show_status=</varname></term> - - <listitem><para>Takes a boolean - argument or the constant - <constant>auto</constant>. If - <option>true</option>, shows terse - service status updates on the console - during bootup. - <constant>auto</constant> behaves like - <option>false</option> until a service - fails or there is a significant delay - in boot. Defaults to - <option>true</option>, unless - <option>quiet</option> is passed as - kernel command line option in which - case it defaults to - <constant>auto</constant>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.log_target=</varname></term> - <term><varname>systemd.log_level=</varname></term> - <term><varname>systemd.log_color=</varname></term> - <term><varname>systemd.log_location=</varname></term> - - <listitem><para>Controls log output, - with the same effect as the - <varname>$SYSTEMD_LOG_TARGET</varname>, <varname>$SYSTEMD_LOG_LEVEL</varname>, <varname>$SYSTEMD_LOG_COLOR</varname>, <varname>$SYSTEMD_LOG_LOCATION</varname> - environment variables described above.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.default_standard_output=</varname></term> - <term><varname>systemd.default_standard_error=</varname></term> - <listitem><para>Controls default - standard output and error output for - services, with the same effect as the - <option>--default-standard-output=</option> - and <option>--default-standard-error=</option> - command line arguments described - above, respectively.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>systemd.setenv=</varname></term> - - <listitem><para>Takes a string - argument in the form VARIABLE=VALUE. - May be used to set default environment - variables to add to forked child processes. - May be used more than once to set multiple - variables.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>quiet</varname></term> - - <listitem><para>Turn off - status output at boot, much like - <varname>systemd.show_status=false</varname> - would. Note that this option is also - read by the kernel itself and disables - kernel log output. Passing this option - hence turns off the usual output from - both the system manager and the kernel. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>debug</varname></term> - - <listitem><para>Turn on debugging - output. This is equivalent to - <varname>systemd.log_level=debug</varname>. - Note that this option is also read by - the kernel itself and enables kernel - debug output. Passing this option - hence turns on the debug output from - both the system manager and the - kernel.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>emergency</varname></term> - <term><varname>-b</varname></term> - - <listitem><para>Boot into emergency - mode. This is equivalent to - <varname>systemd.unit=emergency.target</varname> - and provided for compatibility reasons - and to be easier to - type.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>rescue</varname></term> - <term><varname>single</varname></term> - <term><varname>s</varname></term> - <term><varname>S</varname></term> - <term><varname>1</varname></term> - - <listitem><para>Boot into rescue - mode. This is equivalent to - <varname>systemd.unit=rescue.target</varname> - and provided for compatibility reasons - and to be easier to - type.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>2</varname></term> - <term><varname>3</varname></term> - <term><varname>4</varname></term> - <term><varname>5</varname></term> - - <listitem><para>Boot into the - specified legacy SysV runlevel. These - are equivalent to - <varname>systemd.unit=runlevel2.target</varname>, - <varname>systemd.unit=runlevel3.target</varname>, - <varname>systemd.unit=runlevel4.target</varname>, - and <varname>systemd.unit=runlevel5.target</varname>, respectively, - and provided for compatibility reasons - and to be easier to - type.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>locale.LANG=</varname></term> - <term><varname>locale.LANGUAGE=</varname></term> - <term><varname>locale.LC_CTYPE=</varname></term> - <term><varname>locale.LC_NUMERIC=</varname></term> - <term><varname>locale.LC_TIME=</varname></term> - <term><varname>locale.LC_COLLATE=</varname></term> - <term><varname>locale.LC_MONETARY=</varname></term> - <term><varname>locale.LC_MESSAGES=</varname></term> - <term><varname>locale.LC_PAPER=</varname></term> - <term><varname>locale.LC_NAME=</varname></term> - <term><varname>locale.LC_ADDRESS=</varname></term> - <term><varname>locale.LC_TELEPHONE=</varname></term> - <term><varname>locale.LC_MEASUREMENT=</varname></term> - <term><varname>locale.LC_IDENTIFICATION=</varname></term> - - <listitem><para>Set the system locale - to use. This overrides the settings in - <filename>/etc/locale.conf</filename>. For - more information see - <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> - and - <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>. - </para></listitem> - </varlistentry> - </variablelist> - - <para>For other kernel command line parameters - understood by components of the core OS, please refer - to - <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - </refsect1> - - <refsect1> - <title>Sockets and FIFOs</title> - - <variablelist> - <varlistentry> - <term><filename>/run/systemd/notify</filename></term> - - <listitem><para>Daemon status - notification socket. This is an - <constant>AF_UNIX</constant> datagram socket and is used to - implement the daemon notification - logic as implemented by - <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> - - </varlistentry> - - <varlistentry> - <term><filename>/run/systemd/shutdownd</filename></term> - - <listitem><para>Used internally by the - <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry> - tool to implement delayed - shutdowns. This is an <constant>AF_UNIX</constant> datagram - socket.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/run/systemd/private</filename></term> - - <listitem><para>Used internally as - communication channel between - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and the systemd process. This is an - <constant>AF_UNIX</constant> stream socket. This interface - is private to systemd and should not - be used in external - projects.</para></listitem> - </varlistentry> - - <varlistentry> - <term><filename>/dev/initctl</filename></term> - - <listitem><para>Limited compatibility - support for the SysV client interface, - as implemented by the - <filename>systemd-initctl.service</filename> - unit. This is a named pipe in the file - system. This interface is obsolete and - should not be used in new - applications.</para></listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - The <ulink url="http://www.freedesktop.org/wiki/Software/systemd/">systemd Homepage</ulink>, - <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-notify</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd</refname> + <refname>init</refname> + <refpurpose>systemd system and service manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd <arg choice="opt" rep="repeat">OPTIONS</arg></command> + </cmdsynopsis> + <cmdsynopsis> + <command>init <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>systemd is a system and service manager for Linux operating + systems. When run as first process on boot (as PID 1), it acts as + init system that brings up and maintains userspace + services.</para> + + <para>For compatibility with SysV, if systemd is called as + <command>init</command> and a PID that is not 1, it will execute + <command>telinit</command> and pass all command line arguments + unmodified. That means <command>init</command> and + <command>telinit</command> are mostly equivalent when invoked from + normal login sessions. See + <citerefentry><refentrytitle>telinit</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more information.</para> + + <para>When run as a system instance, systemd interprets the + configuration file <filename>system.conf</filename> and the files + in <filename>system.conf.d</filename> directories; when run as a + user instance, systemd interprets the configuration file + <filename>user.conf</filename> and the files in + <filename>user.conf.d</filename> directories. See + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--test</option></term> + + <listitem><para>Determine startup sequence, dump it and exit. + This is an option useful for debugging only.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dump-configuration-items</option></term> + + <listitem><para>Dump understood unit configuration items. This + outputs a terse but complete list of configuration items + understood in unit definition files.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unit=</option></term> + + <listitem><para>Set default unit to activate on startup. If + not specified, defaults to + <filename>default.target</filename>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--system</option></term> + <term><option>--user</option></term> + + <listitem><para>For <option>--system</option>, tell systemd to + run a system instance, even if the process ID is not 1, i.e. + systemd is not run as init process. <option>--user</option> + does the opposite, running a user instance even if the process + ID is 1. Normally it should not be necessary to pass these + options, as systemd automatically detects the mode it is + started in. These options are hence of little use except for + debugging. Note that it is not supported booting and + maintaining a full system with systemd running in + <option>--system</option> mode, but PID not 1. In practice, + passing <option>--system</option> explicitly is only useful in + conjunction with <option>--test</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dump-core</option></term> + + <listitem><para>Dump core on crash. This switch has no effect + when run as user instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--crash-shell</option></term> + + <listitem><para>Run shell on + crash. This switch has no effect when + run as user + instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--confirm-spawn</option></term> + + <listitem><para>Ask for confirmation when spawning processes. + This switch has no effect when run as user + instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--show-status=</option></term> + + <listitem><para>Show terse service status information while + booting. This switch has no effect when run as user instance. + Takes a boolean argument which may be omitted which is + interpreted as <option>true</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-target=</option></term> + + <listitem><para>Set log target. Argument must be one of + <option>console</option>, + <option>journal</option>, + <option>kmsg</option>, + <option>journal-or-kmsg</option>, + <option>null</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-level=</option></term> + + <listitem><para>Set log level. As + argument this accepts a numerical log + level or the well-known <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + symbolic names (lowercase): + <option>emerg</option>, + <option>alert</option>, + <option>crit</option>, + <option>err</option>, + <option>warning</option>, + <option>notice</option>, + <option>info</option>, + <option>debug</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-color=</option></term> + + <listitem><para>Highlight important log messages. Argument is + a boolean value. If the argument is omitted, it defaults to + <option>true</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-location=</option></term> + + <listitem><para>Include code location in log messages. This is + mostly relevant for debugging purposes. Argument is a boolean + value. If the argument is omitted it defaults to + <option>true</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default-standard-output=</option></term> + <term><option>--default-standard-error=</option></term> + + <listitem><para>Sets the default output or error output for + all services and sockets, respectively. That is, controls the + default for <option>StandardOutput=</option> and + <option>StandardError=</option> (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Takes one of + <option>inherit</option>, + <option>null</option>, + <option>tty</option>, + <option>journal</option>, + <option>journal+console</option>, + <option>syslog</option>, + <option>syslog+console</option>, + <option>kmsg</option>, + <option>kmsg+console</option>. If the + argument is omitted + <option>--default-standard-output=</option> defaults to + <option>journal</option> and + <option>--default-standard-error=</option> to + <option>inherit</option>.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Concepts</title> + + <para>systemd provides a dependency system between various + entities called "units" of 12 different types. Units encapsulate + various objects that are relevant for system boot-up and + maintenance. The majority of units are configured in unit + configuration files, whose syntax and basic set of options is + described in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + however some are created automatically from other configuration, + dynamically from system state or programmatically at runtime. + Units may be "active" (meaning started, bound, plugged in, ..., + depending on the unit type, see below), or "inactive" (meaning + stopped, unbound, unplugged, ...), as well as in the process of + being activated or deactivated, i.e. between the two states (these + states are called "activating", "deactivating"). A special + "failed" state is available as well, which is very similar to + "inactive" and is entered when the service failed in some way + (process returned error code on exit, or crashed, or an operation + timed out). If this state is entered, the cause will be logged, + for later reference. Note that the various unit types may have a + number of additional substates, which are mapped to the five + generalized unit states described here.</para> + + <para>The following unit types are available:</para> + + <orderedlist> + <listitem><para>Service units, which start and control daemons + and the processes they consist of. For details see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Socket units, which encapsulate local IPC or + network sockets in the system, useful for socket-based + activation. For details about socket units see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + for details on socket-based activation and other forms of + activation, see + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Target units are useful to group units, or + provide well-known synchronization points during boot-up, see + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Device units expose kernel devices in systemd + and may be used to implement device-based activation. For + details see + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Mount units control mount points in the file + system, for details see + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Automount units provide automount capabilities, + for on-demand mounting of file systems as well as parallelized + boot-up. See + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Snapshot units can be used to temporarily save + the state of the set of systemd units, which later may be + restored by activating the saved snapshot unit. For more + information see + <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Timer units are useful for triggering activation + of other units based on timers. You may find details in + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Swap units are very similar to mount units and + encapsulate memory swap partitions or files of the operating + system. They are described in + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Path units may be used to activate other + services when file system objects change or are modified. See + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Slice units may be used to group units which + manage system processes (such as service and scope units) in a + hierarchical tree for resource management purposes. See + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Scope units are similar to service units, but + manage foreign processes instead of starting them as well. See + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + </orderedlist> + + <para>Units are named as their configuration files. Some units + have special semantics. A detailed list is available in + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>systemd knows various kinds of dependencies, including + positive and negative requirement dependencies (i.e. + <varname>Requires=</varname> and <varname>Conflicts=</varname>) as + well as ordering dependencies (<varname>After=</varname> and + <varname>Before=</varname>). NB: ordering and requirement + dependencies are orthogonal. If only a requirement dependency + exists between two units (e.g. <filename>foo.service</filename> + requires <filename>bar.service</filename>), but no ordering + dependency (e.g. <filename>foo.service</filename> after + <filename>bar.service</filename>) and both are requested to start, + they will be started in parallel. It is a common pattern that both + requirement and ordering dependencies are placed between two + units. Also note that the majority of dependencies are implicitly + created and maintained by systemd. In most cases, it should be + unnecessary to declare additional dependencies manually, however + it is possible to do this.</para> + + <para>Application programs and units (via dependencies) may + request state changes of units. In systemd, these requests are + encapsulated as 'jobs' and maintained in a job queue. Jobs may + succeed or can fail, their execution is ordered based on the + ordering dependencies of the units they have been scheduled + for.</para> + + <para>On boot systemd activates the target unit + <filename>default.target</filename> whose job is to activate + on-boot services and other on-boot units by pulling them in via + dependencies. Usually the unit name is just an alias (symlink) for + either <filename>graphical.target</filename> (for fully-featured + boots into the UI) or <filename>multi-user.target</filename> (for + limited console-only boots for use in embedded or server + environments, or similar; a subset of graphical.target). However, + it is at the discretion of the administrator to configure it as an + alias to any other target unit. See + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about these target units.</para> + + <para>Processes systemd spawns are placed in individual Linux + control groups named after the unit which they belong to in the + private systemd hierarchy. (see <ulink + url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink> + for more information about control groups, or short "cgroups"). + systemd uses this to effectively keep track of processes. Control + group information is maintained in the kernel, and is accessible + via the file system hierarchy (beneath + <filename>/sys/fs/cgroup/systemd/</filename>), or in tools such as + <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> + (<command>ps xawf -eo pid,user,cgroup,args</command> is + particularly useful to list all processes and the systemd units + they belong to.).</para> + + <para>systemd is compatible with the SysV init system to a large + degree: SysV init scripts are supported and simply read as an + alternative (though limited) configuration file format. The SysV + <filename>/dev/initctl</filename> interface is provided, and + compatibility implementations of the various SysV client tools are + available. In addition to that, various established Unix + functionality such as <filename>/etc/fstab</filename> or the + <filename>utmp</filename> database are supported.</para> + + <para>systemd has a minimal transaction system: if a unit is + requested to start up or shut down it will add it and all its + dependencies to a temporary transaction. Then, it will verify if + the transaction is consistent (i.e. whether the ordering of all + units is cycle-free). If it is not, systemd will try to fix it up, + and removes non-essential jobs from the transaction that might + remove the loop. Also, systemd tries to suppress non-essential + jobs in the transaction that would stop a running service. Finally + it is checked whether the jobs of the transaction contradict jobs + that have already been queued, and optionally the transaction is + aborted then. If all worked out and the transaction is consistent + and minimized in its impact it is merged with all already + outstanding jobs and added to the run queue. Effectively this + means that before executing a requested operation, systemd will + verify that it makes sense, fixing it if possible, and only + failing if it really cannot work.</para> + + <para>Systemd contains native implementations of various tasks + that need to be executed as part of the boot process. For example, + it sets the hostname or configures the loopback network device. It + also sets up and mounts various API file systems, such as + <filename>/sys</filename> or <filename>/proc</filename>.</para> + + <para>For more information about the concepts and + ideas behind systemd, please refer to the + <ulink url="http://0pointer.de/blog/projects/systemd.html">Original Design Document</ulink>.</para> + + <para>Note that some but not all interfaces provided + by systemd are covered by the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface + Stability Promise</ulink>.</para> + + <para>Units may be generated dynamically at boot and system + manager reload time, for example based on other configuration + files or parameters passed on the kernel command line. For details + see the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/Generators">Generators Specification</ulink>.</para> + + <para>Systems which invoke systemd in a container or initrd + environment should implement the + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container Interface</ulink> or + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/InitrdInterface">initrd Interface</ulink> + specifications, respectively.</para> + </refsect1> + + <refsect1> + <title>Directories</title> + + <variablelist> + <varlistentry> + <term>System unit directories</term> + + <listitem><para>The systemd system manager reads unit + configuration from various directories. Packages that want to + install unit files shall place them in the directory returned + by <command>pkg-config systemd + --variable=systemdsystemunitdir</command>. Other directories + checked are <filename>/usr/local/lib/systemd/system</filename> + and <filename>/usr/lib/systemd/system</filename>. User + configuration always takes precedence. <command>pkg-config + systemd --variable=systemdsystemconfdir</command> returns the + path of the system configuration directory. Packages should + alter the content of these directories only with the + <command>enable</command> and <command>disable</command> + commands of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool. Full list of directories is provided in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>User unit directories</term> + + <listitem><para>Similar rules apply for the user unit + directories. However, here the + <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory specification</ulink> is followed to find + units. Applications should place their unit files in the + directory returned by <command>pkg-config systemd + --variable=systemduserunitdir</command>. Global configuration + is done in the directory reported by <command>pkg-config + systemd --variable=systemduserconfdir</command>. The + <command>enable</command> and <command>disable</command> + commands of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool can handle both global (i.e. for all users) and private + (for one user) enabling/disabling of units. Full list of + directories is provided in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>SysV init scripts directory</term> + + <listitem><para>The location of the SysV init script directory + varies between distributions. If systemd cannot find a native + unit file for a requested service, it will look for a SysV + init script of the same name (with the + <filename>.service</filename> suffix + removed).</para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>SysV runlevel link farm directory</term> + + <listitem><para>The location of the SysV runlevel link farm + directory varies between distributions. systemd will take the + link farm into account when figuring out whether a service + shall be enabled. Note that a service unit with a native unit + configuration file cannot be started by activating it in the + SysV runlevel link farm.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Signals</title> + + <variablelist> + <varlistentry> + <term><constant>SIGTERM</constant></term> + + <listitem><para>Upon receiving this signal the systemd system + manager serializes its state, reexecutes itself and + deserializes the saved state again. This is mostly equivalent + to <command>systemctl daemon-reexec</command>.</para> + + <para>systemd user managers will start the + <filename>exit.target</filename> unit when this signal is + received. This is mostly equivalent to <command>systemctl + --user start exit.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGINT</constant></term> + + <listitem><para>Upon receiving this signal the systemd system + manager will start the + <filename>ctrl-alt-del.target</filename> unit. This is mostly + equivalent to <command>systemctl start + ctl-alt-del.target</command>. If this signal is received more + often than 7 times per 2s an immediate reboot is triggered. + Note that pressing Ctrl-Alt-Del on the console will trigger + this signal. Hence, if a reboot is hanging pressing + Ctrl-Alt-Del more than 7 times in 2s is a relatively safe way + to trigger an immediate reboot.</para> + + <para>systemd user managers treat this signal the same way as + <constant>SIGTERM</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGWINCH</constant></term> + + <listitem><para>When this signal is received the systemd + system manager will start the + <filename>kbrequest.target</filename> unit. This is mostly + equivalent to <command>systemctl start + kbrequest.target</command>.</para> + + <para>This signal is ignored by systemd user + managers.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGPWR</constant></term> + + <listitem><para>When this signal is received the systemd + manager will start the <filename>sigpwr.target</filename> + unit. This is mostly equivalent to <command>systemctl start + sigpwr.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGUSR1</constant></term> + + <listitem><para>When this signal is received the systemd + manager will try to reconnect to the D-Bus + bus.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGUSR2</constant></term> + + <listitem><para>When this signal is received the systemd + manager will log its complete state in human readable form. + The data logged is the same as printed by + <command>systemd-analyze dump</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGHUP</constant></term> + + <listitem><para>Reloads the complete daemon configuration. + This is mostly equivalent to <command>systemctl + daemon-reload</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+0</constant></term> + + <listitem><para>Enters default mode, starts the + <filename>default.target</filename> unit. This is mostly + equivalent to <command>systemctl start + default.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+1</constant></term> + + <listitem><para>Enters rescue mode, starts the + <filename>rescue.target</filename> unit. This is mostly + equivalent to <command>systemctl isolate + rescue.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+2</constant></term> + + <listitem><para>Enters emergency mode, starts the + <filename>emergency.service</filename> unit. This is mostly + equivalent to <command>systemctl isolate + emergency.service</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+3</constant></term> + + <listitem><para>Halts the machine, starts the + <filename>halt.target</filename> unit. This is mostly + equivalent to <command>systemctl start + halt.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+4</constant></term> + + <listitem><para>Powers off the machine, starts the + <filename>poweroff.target</filename> unit. This is mostly + equivalent to <command>systemctl start + poweroff.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+5</constant></term> + + <listitem><para>Reboots the machine, starts the + <filename>reboot.target</filename> unit. This is mostly + equivalent to <command>systemctl start + reboot.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+6</constant></term> + + <listitem><para>Reboots the machine via kexec, starts the + <filename>kexec.target</filename> unit. This is mostly + equivalent to <command>systemctl start + kexec.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+13</constant></term> + + <listitem><para>Immediately halts the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+14</constant></term> + + <listitem><para>Immediately powers off the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+15</constant></term> + + <listitem><para>Immediately reboots the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+16</constant></term> + + <listitem><para>Immediately reboots the machine with kexec.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+20</constant></term> + + <listitem><para>Enables display of status messages on the + console, as controlled via + <varname>systemd.show_status=1</varname> on the kernel command + line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+21</constant></term> + + <listitem><para>Disables display of + status messages on the console, as + controlled via + <varname>systemd.show_status=0</varname> + on the kernel command + line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+22</constant></term> + <term><constant>SIGRTMIN+23</constant></term> + + <listitem><para>Sets the log level to <literal>debug</literal> + (or <literal>info</literal> on + <constant>SIGRTMIN+23</constant>), as controlled via + <varname>systemd.log_level=debug</varname> (or + <varname>systemd.log_level=info</varname> on + <constant>SIGRTMIN+23</constant>) on the kernel command + line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+24</constant></term> + + <listitem><para>Immediately exits the manager (only available + for --user instances).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+26</constant></term> + <term><constant>SIGRTMIN+27</constant></term> + <term><constant>SIGRTMIN+28</constant></term> + + <listitem><para>Sets the log level to + <literal>journal-or-kmsg</literal> (or + <literal>console</literal> on + <constant>SIGRTMIN+27</constant>, <literal>kmsg</literal> on + <constant>SIGRTMIN+28</constant>), as controlled via + <varname>systemd.log_target=journal-or-kmsg</varname> (or + <varname>systemd.log_target=console</varname> on + <constant>SIGRTMIN+27</constant> or + <varname>systemd.log_target=kmsg</varname> on + <constant>SIGRTMIN+28</constant>) on the kernel command + line.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$SYSTEMD_LOG_LEVEL</varname></term> + <listitem><para>systemd reads the log level from this + environment variable. This can be overridden with + <option>--log-level=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_LOG_TARGET</varname></term> + <listitem><para>systemd reads the log target from this + environment variable. This can be overridden with + <option>--log-target=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_LOG_COLOR</varname></term> + <listitem><para>Controls whether systemd highlights important + log messages. This can be overridden with + <option>--log-color=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_LOG_LOCATION</varname></term> + <listitem><para>Controls whether systemd prints the code + location along with log messages. This can be overridden with + <option>--log-location=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_CONFIG_HOME</varname></term> + <term><varname>$XDG_CONFIG_DIRS</varname></term> + <term><varname>$XDG_DATA_HOME</varname></term> + <term><varname>$XDG_DATA_DIRS</varname></term> + + <listitem><para>The systemd user manager uses these variables + in accordance to the <ulink + url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory specification</ulink> to find its + configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_UNIT_PATH</varname></term> + + <listitem><para>Controls where systemd looks for unit + files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_SYSVINIT_PATH</varname></term> + + <listitem><para>Controls where systemd looks for SysV init + scripts.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_SYSVRCND_PATH</varname></term> + + <listitem><para>Controls where systemd looks for SysV init + script runlevel link farms.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDS</varname></term> + + <listitem><para>Set by systemd for supervised processes during + socket-based activation. See + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$NOTIFY_SOCKET</varname></term> + + <listitem><para>Set by systemd for supervised processes for + status and start-up completion notification. See + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information. </para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Kernel Command Line</title> + + <para>When run as system instance systemd parses a number of + kernel command line arguments<footnote><para>If run inside a Linux + container these arguments may be passed as command line arguments + to systemd itself, next to any of the command line options listed + in the Options section above. If run outside of Linux containers, + these arguments are parsed from <filename>/proc/cmdline</filename> + instead.</para></footnote>:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>systemd.unit=</varname></term> + <term><varname>rd.systemd.unit=</varname></term> + + <listitem><para>Overrides the unit to activate on boot. + Defaults to <filename>default.target</filename>. This may be + used to temporarily boot into a different boot unit, for + example <filename>rescue.target</filename> or + <filename>emergency.service</filename>. See + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about these units. The option prefixed with + <literal>rd.</literal> is honored only in the initial RAM disk + (initrd), while the one that is not prefixed only in the main + system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.dump_core=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, systemd dumps core when it crashes. + Otherwise, no core dump is created. Defaults to + <option>true</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.crash_shell=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, systemd spawns a shell when it crashes. + Otherwise, no shell is spawned. Defaults to + <option>false</option>, for security reasons, as the shell is + not protected by any password + authentication.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.crash_chvt=</varname></term> + + <listitem><para>Takes an integer argument. If positive systemd + activates the specified virtual terminal when it crashes. + Defaults to <constant>-1</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.confirm_spawn=</varname></term> + + <listitem><para>Takes a boolean argument. If + <option>true</option>, asks for confirmation when spawning + processes. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.show_status=</varname></term> + + <listitem><para>Takes a boolean argument or the constant + <constant>auto</constant>. If <option>true</option>, shows + terse service status updates on the console during bootup. + <constant>auto</constant> behaves like <option>false</option> + until a service fails or there is a significant delay in boot. + Defaults to <option>true</option>, unless + <option>quiet</option> is passed as kernel command line option + in which case it defaults to + <constant>auto</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.log_target=</varname></term> + <term><varname>systemd.log_level=</varname></term> + <term><varname>systemd.log_color=</varname></term> + <term><varname>systemd.log_location=</varname></term> + + <listitem><para>Controls log output, with the same effect as + the <varname>$SYSTEMD_LOG_TARGET</varname>, + <varname>$SYSTEMD_LOG_LEVEL</varname>, + <varname>$SYSTEMD_LOG_COLOR</varname>, + <varname>$SYSTEMD_LOG_LOCATION</varname> environment variables + described above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.default_standard_output=</varname></term> + <term><varname>systemd.default_standard_error=</varname></term> + <listitem><para>Controls default standard output and error + output for services, with the same effect as the + <option>--default-standard-output=</option> and + <option>--default-standard-error=</option> command line + arguments described above, respectively.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.setenv=</varname></term> + + <listitem><para>Takes a string argument in the form + VARIABLE=VALUE. May be used to set default environment + variables to add to forked child processes. May be used more + than once to set multiple variables.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>quiet</varname></term> + + <listitem><para>Turn off status output at boot, much like + <varname>systemd.show_status=false</varname> would. Note that + this option is also read by the kernel itself and disables + kernel log output. Passing this option hence turns off the + usual output from both the system manager and the kernel. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>debug</varname></term> + + <listitem><para>Turn on debugging output. This is equivalent + to <varname>systemd.log_level=debug</varname>. Note that this + option is also read by the kernel itself and enables kernel + debug output. Passing this option hence turns on the debug + output from both the system manager and the + kernel.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>emergency</varname></term> + <term><varname>-b</varname></term> + + <listitem><para>Boot into emergency mode. This is equivalent + to <varname>systemd.unit=emergency.target</varname> and + provided for compatibility reasons and to be easier to + type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>rescue</varname></term> + <term><varname>single</varname></term> + <term><varname>s</varname></term> + <term><varname>S</varname></term> + <term><varname>1</varname></term> + + <listitem><para>Boot into rescue mode. This is equivalent to + <varname>systemd.unit=rescue.target</varname> and provided for + compatibility reasons and to be easier to + type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>2</varname></term> + <term><varname>3</varname></term> + <term><varname>4</varname></term> + <term><varname>5</varname></term> + + <listitem><para>Boot into the specified legacy SysV runlevel. + These are equivalent to + <varname>systemd.unit=runlevel2.target</varname>, + <varname>systemd.unit=runlevel3.target</varname>, + <varname>systemd.unit=runlevel4.target</varname>, and + <varname>systemd.unit=runlevel5.target</varname>, + respectively, and provided for compatibility reasons and to be + easier to type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>locale.LANG=</varname></term> + <term><varname>locale.LANGUAGE=</varname></term> + <term><varname>locale.LC_CTYPE=</varname></term> + <term><varname>locale.LC_NUMERIC=</varname></term> + <term><varname>locale.LC_TIME=</varname></term> + <term><varname>locale.LC_COLLATE=</varname></term> + <term><varname>locale.LC_MONETARY=</varname></term> + <term><varname>locale.LC_MESSAGES=</varname></term> + <term><varname>locale.LC_PAPER=</varname></term> + <term><varname>locale.LC_NAME=</varname></term> + <term><varname>locale.LC_ADDRESS=</varname></term> + <term><varname>locale.LC_TELEPHONE=</varname></term> + <term><varname>locale.LC_MEASUREMENT=</varname></term> + <term><varname>locale.LC_IDENTIFICATION=</varname></term> + + <listitem><para>Set the system locale to use. This overrides + the settings in <filename>/etc/locale.conf</filename>. For + more information see + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <para>For other kernel command line parameters understood by + components of the core OS, please refer to + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Sockets and FIFOs</title> + + <variablelist> + <varlistentry> + <term><filename>/run/systemd/notify</filename></term> + + <listitem><para>Daemon status notification socket. This is an + <constant>AF_UNIX</constant> datagram socket and is used to + implement the daemon notification logic as implemented by + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><filename>/run/systemd/shutdownd</filename></term> + + <listitem><para>Used internally by the + <citerefentry><refentrytitle>shutdown</refentrytitle><manvolnum>8</manvolnum></citerefentry> + tool to implement delayed shutdowns. This is an + <constant>AF_UNIX</constant> datagram + socket.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/run/systemd/private</filename></term> + + <listitem><para>Used internally as communication channel + between + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and the systemd process. This is an + <constant>AF_UNIX</constant> stream socket. This interface is + private to systemd and should not be used in external + projects.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/dev/initctl</filename></term> + + <listitem><para>Limited compatibility support for the SysV + client interface, as implemented by the + <filename>systemd-initctl.service</filename> unit. This is a + named pipe in the file system. This interface is obsolete and + should not be used in new applications.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + The <ulink url="http://www.freedesktop.org/wiki/Software/systemd/">systemd Homepage</ulink>, + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-notify</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml index ac2db98853..99aa07a1cc 100644 --- a/man/sysusers.d.xml +++ b/man/sysusers.d.xml @@ -20,245 +20,204 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> <refentry id="sysusers.d" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sysusers.d</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>sysusers.d</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>sysusers.d</refname> - <refpurpose>Declarative allocation of system users and groups</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/usr/lib/sysusers.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-sysusers</command> uses the - files from <filename>sysusers.d</filename> directory - to create system users and groups at package - installation or boot time. This tool may be used to - allocate system users and groups only, it is not - useful for creating non-system users and groups, as it - accesses <filename>/etc/passwd</filename> and - <filename>/etc/group</filename> directly, bypassing - any more complex user databases, for example any - database involving NIS or LDAP.</para> - </refsect1> - - <refsect1> - <title>Configuration Format</title> - - <para>Each configuration file shall be named in the - style of - <filename><replaceable>package</replaceable>.conf</filename> - or - <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>. - The second variant should be used when it is desirable - to make it easy to override just this part of - configuration.</para> - - <para>The file format is one line per user or group - containing name, ID, GECOS field description and home directory:</para> - - <programlisting># Type Name ID GECOS + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sysusers.d</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>sysusers.d</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>sysusers.d</refname> + <refpurpose>Declarative allocation of system users and groups</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/usr/lib/sysusers.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-sysusers</command> uses the files from + <filename>sysusers.d</filename> directory to create system users + and groups at package installation or boot time. This tool may be + used to allocate system users and groups only, it is not useful + for creating non-system users and groups, as it accesses + <filename>/etc/passwd</filename> and + <filename>/etc/group</filename> directly, bypassing any more + complex user databases, for example any database involving NIS or + LDAP.</para> + </refsect1> + + <refsect1> + <title>Configuration Format</title> + + <para>Each configuration file shall be named in the style of + <filename><replaceable>package</replaceable>.conf</filename> or + <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>. + The second variant should be used when it is desirable to make it + easy to override just this part of configuration.</para> + + <para>The file format is one line per user or group containing + name, ID, GECOS field description and home directory:</para> + + <programlisting># Type Name ID GECOS u httpd 440 "HTTP User" u authd /usr/bin/authd "Authorization user" g input - - m authd input u root 0 "Superuser" /root</programlisting> - <refsect2> - <title>Type</title> - - <para>The type consists of a single - letter. The following line types are - understood:</para> - - <variablelist> - <varlistentry> - <term><varname>u</varname></term> - <listitem><para>Create a - system user and group of the - specified name should they not - exist yet. The user's primary - group will be set to the group - bearing the same name. The - user's shell will be set to - <filename>/sbin/nologin</filename>, - the home directory to the - specified home directory, or - <filename>/</filename> if none - is given. The account will be - created disabled, so that - logins are not - allowed.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>g</varname></term> - <listitem><para>Create a - system group of the specified - name should it not exist - yet. Note that - <varname>u</varname> - implicitly create a matching - group. The group will be - created with no password - set.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>m</varname></term> - <listitem><para>Add a user to - a group. If the user or group - are not existing yet, they - will be implicitly - created.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>r</varname></term> - <listitem><para>Add a range of - numeric UIDs/GIDs to the pool - to allocate new UIDs and GIDs - from. If no line of this type - is specified the range of - UIDs/GIDs is set to some - compiled-in default. Note that - both UIDs and GIDs are - allocated from the same pool, - in order to ensure that users - and groups of the same name - are likely to carry the same - numeric UID and - GID.</para></listitem> - </varlistentry> - - </variablelist> - </refsect2> - - <refsect2> - <title>Name</title> - - <para>The name field specifies the user or - group name. It should be shorter than 31 - characters and avoid any non-ASCII characters, - and not begin with a numeric character. It is - strongly recommended to pick user and group - names that are unlikely to clash with normal - users created by the administrator. A good - scheme to guarantee this is by prefixing all - system and group names with the underscore, - and avoiding too generic names.</para> - - <para>For <varname>m</varname> lines this - field should contain the user name to add to a - group.</para> - - <para>For lines of type <varname>r</varname> - this field should be set to - <literal>-</literal>.</para> - </refsect2> - - <refsect2> - <title>ID</title> - - <para>For <varname>u</varname> and - <varname>g</varname> the numeric 32bit UID or - GID of the user/group. Do not use IDs 65535 or - 4294967295, as they have special placeholder - meanings. Specify <literal>-</literal> for - automatic UID/GID allocation for the user or - group. Alternatively, specify an absolute path - in the file system. In this case the UID/GID - is read from the path's owner/group. This is - useful to create users whose UID/GID match the - owners of pre-existing files (such as SUID or - SGID binaries).</para> - - <para>For <varname>m</varname> lines this - field should contain the group name to add to - a user to.</para> - - <para>For lines of type <varname>r</varname> - this field should be set to a UID/GID range in - the format <literal>FROM-TO</literal> where - both values are formatted as decimal ASCII - numbers. Alternatively, a single UID/GID may - be specified formatted as decimal ASCII - numbers.</para> - </refsect2> - - <refsect2> - <title>GECOS</title> - - <para>A short, descriptive string for users to - be created, enclosed in quotation marks. Note - that this field may not contain colons.</para> - - <para>Only applies to lines of type - <varname>u</varname> and should otherwise be - left unset, or be set to - <literal>-</literal>.</para> - </refsect2> - - <refsect2> - <title>Home Directory</title> - - <para>The home directory for a new system - user. If omitted defaults to the root - directory. It is recommended to not - unnecessarily specify home directories for - system users, unless software strictly - requires one to be set.</para> - - <para>Only applies to lines of type - <varname>u</varname> and should otherwise be - left unset, or be set to - <literal>-</literal>.</para> - </refsect2> - - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - - <refsect1> - <title>Idempotence</title> - - <para>Note that <command>systemd-sysusers</command> - will do nothing if the specified users or groups - already exist, so normally there no reason to override - <filename>sysusers.d</filename> vendor configuration, - except to block certain users or groups from being - created.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + <refsect2> + <title>Type</title> + + <para>The type consists of a single letter. The following line + types are understood:</para> + + <variablelist> + <varlistentry> + <term><varname>u</varname></term> + <listitem><para>Create a system user and group of the + specified name should they not exist yet. The user's primary + group will be set to the group bearing the same name. The + user's shell will be set to + <filename>/sbin/nologin</filename>, the home directory to + the specified home directory, or <filename>/</filename> if + none is given. The account will be created disabled, so that + logins are not allowed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>g</varname></term> + <listitem><para>Create a system group of the specified name + should it not exist yet. Note that <varname>u</varname> + implicitly create a matching group. The group will be + created with no password set.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>m</varname></term> + <listitem><para>Add a user to a group. If the user or group + are not existing yet, they will be implicitly + created.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>r</varname></term> + <listitem><para>Add a range of numeric UIDs/GIDs to the pool + to allocate new UIDs and GIDs from. If no line of this type + is specified the range of UIDs/GIDs is set to some + compiled-in default. Note that both UIDs and GIDs are + allocated from the same pool, in order to ensure that users + and groups of the same name are likely to carry the same + numeric UID and GID.</para></listitem> + </varlistentry> + + </variablelist> + </refsect2> + + <refsect2> + <title>Name</title> + + <para>The name field specifies the user or group name. It should + be shorter than 31 characters and avoid any non-ASCII + characters, and not begin with a numeric character. It is + strongly recommended to pick user and group names that are + unlikely to clash with normal users created by the + administrator. A good scheme to guarantee this is by prefixing + all system and group names with the underscore, and avoiding too + generic names.</para> + + <para>For <varname>m</varname> lines this field should contain + the user name to add to a group.</para> + + <para>For lines of type <varname>r</varname> this field should + be set to <literal>-</literal>.</para> + </refsect2> + + <refsect2> + <title>ID</title> + + <para>For <varname>u</varname> and <varname>g</varname> the + numeric 32bit UID or GID of the user/group. Do not use IDs 65535 + or 4294967295, as they have special placeholder meanings. + Specify <literal>-</literal> for automatic UID/GID allocation + for the user or group. Alternatively, specify an absolute path + in the file system. In this case the UID/GID is read from the + path's owner/group. This is useful to create users whose UID/GID + match the owners of pre-existing files (such as SUID or SGID + binaries).</para> + + <para>For <varname>m</varname> lines this field should contain + the group name to add to a user to.</para> + + <para>For lines of type <varname>r</varname> this field should + be set to a UID/GID range in the format + <literal>FROM-TO</literal> where both values are formatted as + decimal ASCII numbers. Alternatively, a single UID/GID may be + specified formatted as decimal ASCII numbers.</para> + </refsect2> + + <refsect2> + <title>GECOS</title> + + <para>A short, descriptive string for users to be created, + enclosed in quotation marks. Note that this field may not + contain colons.</para> + + <para>Only applies to lines of type <varname>u</varname> and + should otherwise be left unset, or be set to + <literal>-</literal>.</para> + </refsect2> + + <refsect2> + <title>Home Directory</title> + + <para>The home directory for a new system user. If omitted + defaults to the root directory. It is recommended to not + unnecessarily specify home directories for system users, unless + software strictly requires one to be set.</para> + + <para>Only applies to lines of type <varname>u</varname> and + should otherwise be left unset, or be set to + <literal>-</literal>.</para> + </refsect2> + + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + + <refsect1> + <title>Idempotence</title> + + <para>Note that <command>systemd-sysusers</command> will do + nothing if the specified users or groups already exist, so + normally there no reason to override + <filename>sysusers.d</filename> vendor configuration, except to + block certain users or groups from being created.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/telinit.xml b/man/telinit.xml index 33ea118bcb..02d31fbd46 100644 --- a/man/telinit.xml +++ b/man/telinit.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,174 +22,158 @@ --> <refentry id="telinit" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>telinit</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>telinit</refentrytitle> - <manvolnum>8</manvolnum> - </refmeta> - - <refnamediv> - <refname>telinit</refname> - <refpurpose>Change SysV runlevel</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>telinit <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>telinit</command> may be used to change - the SysV system runlevel. Since the concept of SysV - runlevels is obsolete the runlevel requests - will be transparently translated into systemd unit - activation requests.</para> - - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--help</option></term> - - <xi:include href="standard-options.xml" xpointer="help-text" /> - </varlistentry> - - <varlistentry> - <term><option>--no-wall</option></term> - - <listitem><para>Do not send wall - message before - reboot/halt/power-off.</para></listitem> - </varlistentry> - </variablelist> - - <para>The following commands are understood:</para> - - <variablelist> - <varlistentry> - <term><command>0</command></term> - - <listitem><para>Power-off the - machine. This is translated into an - activation request for - <filename>poweroff.target</filename> - and is equivalent to - <command>systemctl - poweroff</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>6</command></term> - - <listitem><para>Reboot the - machine. This is translated into an - activation request for - <filename>reboot.target</filename> and - is equivalent to <command>systemctl - reboot</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>2</command></term> - <term><command>3</command></term> - <term><command>4</command></term> - <term><command>5</command></term> - - <listitem><para>Change the SysV - runlevel. This is translated into an - activation request for - <filename>runlevel2.target</filename>, - <filename>runlevel3.target</filename>, - ... and is equivalent to - <command>systemctl isolate - runlevel2.target</command>, - <command>systemctl isolate - runlevel3.target</command>, - ...</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>1</command></term> - <term><command>s</command></term> - <term><command>S</command></term> - - <listitem><para>Change into system - rescue mode. This is translated into - an activation request for - <filename>rescue.target</filename> and - is equivalent to <command>systemctl - rescue</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>q</command></term> - <term><command>Q</command></term> - - <listitem><para>Reload daemon - configuration. This is equivalent to - <command>systemctl - daemon-reload</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>u</command></term> - <term><command>U</command></term> - - <listitem><para>Serialize state, - reexecute daemon and deserialize state - again. This is equivalent to - <command>systemctl - daemon-reexec</command>.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <refsect1> - <title>Notes</title> - - <para>This is a legacy command available for compatibility - only. It should not be used anymore, as the concept of - runlevels is obsolete.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>telinit</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>telinit</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>telinit</refname> + <refpurpose>Change SysV runlevel</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>telinit <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>telinit</command> may be used to change the SysV + system runlevel. Since the concept of SysV runlevels is obsolete + the runlevel requests will be transparently translated into + systemd unit activation requests.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + + <xi:include href="standard-options.xml" xpointer="help-text" /> + </varlistentry> + + <varlistentry> + <term><option>--no-wall</option></term> + + <listitem><para>Do not send wall message before + reboot/halt/power-off.</para></listitem> + </varlistentry> + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>0</command></term> + + <listitem><para>Power-off the machine. This is translated into + an activation request for <filename>poweroff.target</filename> + and is equivalent to <command>systemctl + poweroff</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>6</command></term> + + <listitem><para>Reboot the machine. This is translated into an + activation request for <filename>reboot.target</filename> and + is equivalent to <command>systemctl + reboot</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>2</command></term> + <term><command>3</command></term> + <term><command>4</command></term> + <term><command>5</command></term> + + <listitem><para>Change the SysV runlevel. This is translated + into an activation request for + <filename>runlevel2.target</filename>, + <filename>runlevel3.target</filename>, ... and is equivalent + to <command>systemctl isolate runlevel2.target</command>, + <command>systemctl isolate runlevel3.target</command>, + ...</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>1</command></term> + <term><command>s</command></term> + <term><command>S</command></term> + + <listitem><para>Change into system rescue mode. This is + translated into an activation request for + <filename>rescue.target</filename> and is equivalent to + <command>systemctl rescue</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>q</command></term> + <term><command>Q</command></term> + + <listitem><para>Reload daemon configuration. This is + equivalent to <command>systemctl + daemon-reload</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>u</command></term> + <term><command>U</command></term> + + <listitem><para>Serialize state, reexecute daemon and + deserialize state again. This is equivalent to + <command>systemctl daemon-reexec</command>.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>This is a legacy command available for compatibility only. + It should not be used anymore, as the concept of runlevels is + obsolete.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/timedatectl.xml b/man/timedatectl.xml index f3edb8d61a..98ec013ebb 100644 --- a/man/timedatectl.xml +++ b/man/timedatectl.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,232 +22,211 @@ --> <refentry id="timedatectl" conditional='ENABLE_TIMEDATED' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>timedatectl</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>timedatectl</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>timedatectl</refname> - <refpurpose>Control the system time and date</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>timedatectl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>timedatectl</command> may be used to - query and change the system clock and its - settings.</para> - - <para>Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the system time zone for mounted (but not - booted) system images.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--no-ask-password</option></term> - - <listitem><para>Do not query the user - for authentication for privileged - operations.</para></listitem> - </varlistentry> - - <varlistentry> - <term><option>--adjust-system-clock</option></term> - - <listitem><para>If - <command>set-local-rtc</command> is - invoked and this option is passed, the - system clock is synchronized from the - RTC again, taking the new setting into - account. Otherwise, the RTC is - synchronized from the system - clock.</para></listitem> - </varlistentry> - - <xi:include href="user-system-options.xml" xpointer="host" /> - <xi:include href="user-system-options.xml" xpointer="machine" /> - - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - <xi:include href="standard-options.xml" xpointer="no-pager" /> - </variablelist> - - <para>The following commands are understood:</para> - - <variablelist> - <varlistentry> - <term><command>status</command></term> - - <listitem><para>Show current settings - of the system clock and - RTC.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-time [TIME]</command></term> - - <listitem><para>Set the system clock - to the specified time. This will also - update the RTC time accordingly. The time - may be specified in the format - "2012-10-30 - 18:17:16".</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-timezone [TIMEZONE]</command></term> - - <listitem><para>Set the system time - zone to the specified value. Available - timezones can be listed with - <command>list-timezones</command>. If - the RTC is configured to be in the - local time, this will also update the - RTC time. This call will alter the - <filename>/etc/localtime</filename> - symlink. See - <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more - information.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>list-timezones</command></term> - - <listitem><para>List available time - zones, one per line. Entries from the - list can be set as the system - timezone with - <command>set-timezone</command>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-local-rtc [BOOL]</command></term> - - <listitem><para>Takes a boolean - argument. If <literal>0</literal>, the - system is configured to maintain the - RTC in universal time. If - <literal>1</literal>, it will maintain - the RTC in local time instead. Note - that maintaining the RTC in the local - timezone is not fully supported and - will create various problems with time - zone changes and daylight saving - adjustments. If at all possible, keep the - RTC in UTC mode. Note that invoking this - will also synchronize the RTC from the - system clock, unless - <option>--adjust-system-clock</option> is - passed (see above). This command will - change the 3rd line of - <filename>/etc/adjtime</filename>, as - documented in - <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><command>set-ntp [BOOL]</command></term> - - <listitem><para>Takes a boolean - argument. Controls whether NTP based - network time synchronization is - enabled (if - available).</para></listitem> - </varlistentry> - - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure - code otherwise.</para> - </refsect1> - - <xi:include href="less-variables.xml" /> - - <refsect1> - <title>Examples</title> - <para>Show current settings: - <programlisting>$ timedatectl + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>timedatectl</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>timedatectl</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>timedatectl</refname> + <refpurpose>Control the system time and date</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>timedatectl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>timedatectl</command> may be used to query and + change the system clock and its settings.</para> + + <para>Use + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + to initialize the system time zone for mounted (but not booted) + system images.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--no-ask-password</option></term> + + <listitem><para>Do not query the user for authentication for + privileged operations.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--adjust-system-clock</option></term> + + <listitem><para>If <command>set-local-rtc</command> is invoked + and this option is passed, the system clock is synchronized + from the RTC again, taking the new setting into account. + Otherwise, the RTC is synchronized from the system + clock.</para></listitem> + </varlistentry> + + <xi:include href="user-system-options.xml" xpointer="host" /> + <xi:include href="user-system-options.xml" xpointer="machine" /> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + <xi:include href="standard-options.xml" xpointer="no-pager" /> + </variablelist> + + <para>The following commands are understood:</para> + + <variablelist> + <varlistentry> + <term><command>status</command></term> + + <listitem><para>Show current settings + of the system clock and + RTC.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-time [TIME]</command></term> + + <listitem><para>Set the system clock to the specified time. + This will also update the RTC time accordingly. The time may + be specified in the format "2012-10-30 + 18:17:16".</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-timezone [TIMEZONE]</command></term> + + <listitem><para>Set the system time zone to the specified + value. Available timezones can be listed with + <command>list-timezones</command>. If the RTC is configured to + be in the local time, this will also update the RTC time. This + call will alter the <filename>/etc/localtime</filename> + symlink. See + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>list-timezones</command></term> + + <listitem><para>List available time zones, one per line. + Entries from the list can be set as the system timezone with + <command>set-timezone</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-local-rtc [BOOL]</command></term> + + <listitem><para>Takes a boolean argument. If + <literal>0</literal>, the system is configured to maintain the + RTC in universal time. If <literal>1</literal>, it will + maintain the RTC in local time instead. Note that maintaining + the RTC in the local timezone is not fully supported and will + create various problems with time zone changes and daylight + saving adjustments. If at all possible, keep the RTC in UTC + mode. Note that invoking this will also synchronize the RTC + from the system clock, unless + <option>--adjust-system-clock</option> is passed (see above). + This command will change the 3rd line of + <filename>/etc/adjtime</filename>, as documented in + <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><command>set-ntp [BOOL]</command></term> + + <listitem><para>Takes a boolean argument. Controls whether NTP + based network time synchronization is enabled (if + available).</para></listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned, a non-zero failure + code otherwise.</para> + </refsect1> + + <xi:include href="less-variables.xml" /> + + <refsect1> + <title>Examples</title> + <para>Show current settings: + <programlisting>$ timedatectl Local time: Fri, 2012-11-02 09:26:46 CET Universal time: Fri, 2012-11-02 08:26:46 UTC - RTC time: Fri, 2012-11-02 08:26:45 - Timezone: Europe/Warsaw + RTC time: Fri, 2012-11-02 08:26:45 + Timezone: Europe/Warsaw UTC offset: +0100 NTP enabled: no NTP synchronized: no RTC in local TZ: no DST active: no Last DST change: CEST → CET, DST became inactive - Sun, 2012-10-28 02:59:59 CEST - Sun, 2012-10-28 02:00:00 CET + Sun, 2012-10-28 02:59:59 CEST + Sun, 2012-10-28 02:00:00 CET Next DST change: CET → CEST, DST will become active - the clock will jump one hour forward - Sun, 2013-03-31 01:59:59 CET - Sun, 2013-03-31 03:00:00 CEST</programlisting> - </para> + the clock will jump one hour forward + Sun, 2013-03-31 01:59:59 CET + Sun, 2013-03-31 03:00:00 CEST</programlisting> + </para> - <para>Enable an NTP daemon (chronyd): - <programlisting>$ timedatectl set-ntp true + <para>Enable an NTP daemon (chronyd): + <programlisting>$ timedatectl set-ntp true ==== AUTHENTICATING FOR org.freedesktop.timedate1.set-ntp === Authentication is required to control whether network time synchronization shall be enabled. Authenticating as: user Password: ******** ==== AUTHENTICATION COMPLETE ===</programlisting> - <programlisting>$ systemctl status chronyd.service + <programlisting>$ systemctl status chronyd.service chronyd.service - NTP client/server - Loaded: loaded (/usr/lib/systemd/system/chronyd.service; enabled) - Active: active (running) since Fri, 2012-11-02 09:36:25 CET; 5s ago + Loaded: loaded (/usr/lib/systemd/system/chronyd.service; enabled) + Active: active (running) since Fri, 2012-11-02 09:36:25 CET; 5s ago ...</programlisting> - </para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>hwclock</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>date</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-timedated.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/timesyncd.conf.xml b/man/timesyncd.conf.xml index 1a56c2c5c4..805374a5f9 100644 --- a/man/timesyncd.conf.xml +++ b/man/timesyncd.conf.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,98 +23,90 @@ --> <refentry id="timesyncd.conf" conditional='ENABLE_TIMESYNCD' - xmlns:xi="http://www.w3.org/2001/XInclude"> - <refentryinfo> - <title>timesyncd.conf</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>timesyncd.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>timesyncd.conf</refname> - <refname>timesyncd.conf.d</refname> - <refpurpose>Network Time Synchronization configuration files</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/systemd/timesyncd.conf</filename></para> - <para><filename>/etc/systemd/timesyncd.conf.d/*.conf</filename></para> - <para><filename>/run/systemd/timesyncd.conf.d/*.conf</filename></para> - <para><filename>/usr/lib/systemd/timesyncd.conf.d/*.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>These configuration files control NTP network time - synchronization.</para> - - </refsect1> - - <xi:include href="standard-conf.xml" xpointer="confd" /> - <xi:include href="standard-conf.xml" xpointer="conf" /> - - <refsect1> - <title>Options</title> - - <variablelist class='network-directives'> - - <varlistentry> - <term><varname>NTP=</varname></term> - <listitem><para>A space separated list - of NTP servers host names or IP - addresses. During runtime this list is - combined with any per-interface NTP - servers acquired from - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. systemd-timesyncd - will contact all configured system or - per-interface servers in turn until - one is found that responds. This - setting defaults to the empty - list.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>FallbackNTP=</varname></term> - <listitem><para>A space separated list - of NTP server host names or IP - addresses to be used as the fallback - NTP servers. Any per-interface NTP - servers obtained from - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - take precedence over this setting, as - do any servers set via - <varname>NTP=</varname> above. This - setting is hence only used if no other - NTP server information is known. If - this option is not given, a - compiled-in list of NTP servers is - used instead.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>timesyncd.conf</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>timesyncd.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>timesyncd.conf</refname> + <refname>timesyncd.conf.d</refname> + <refpurpose>Network Time Synchronization configuration files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/systemd/timesyncd.conf</filename></para> + <para><filename>/etc/systemd/timesyncd.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/timesyncd.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/timesyncd.conf.d/*.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These configuration files control NTP network time + synchronization.</para> + + </refsect1> + + <xi:include href="standard-conf.xml" xpointer="confd" /> + <xi:include href="standard-conf.xml" xpointer="conf" /> + + <refsect1> + <title>Options</title> + + <variablelist class='network-directives'> + + <varlistentry> + <term><varname>NTP=</varname></term> + <listitem><para>A space separated list of NTP servers host + names or IP addresses. During runtime this list is combined + with any per-interface NTP servers acquired from + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + systemd-timesyncd will contact all configured system or + per-interface servers in turn until one is found that + responds. This setting defaults to the empty + list.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FallbackNTP=</varname></term> + <listitem><para>A space separated list of NTP server host + names or IP addresses to be used as the fallback NTP servers. + Any per-interface NTP servers obtained from + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + take precedence over this setting, as do any servers set via + <varname>NTP=</varname> above. This setting is hence only used + if no other NTP server information is known. If this option is + not given, a compiled-in list of NTP servers is used + instead.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> diff --git a/man/vconsole.conf.xml b/man/vconsole.conf.xml index 02df2e810a..a29075a161 100644 --- a/man/vconsole.conf.xml +++ b/man/vconsole.conf.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,125 +23,118 @@ --> <refentry id="vconsole.conf" conditional='ENABLE_VCONSOLE'> - <refentryinfo> - <title>vconsole.conf</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>vconsole.conf</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>vconsole.conf</refname> - <refpurpose>Configuration file for the virtual console</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/vconsole.conf</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <filename>/etc/vconsole.conf</filename> file - configures the virtual console, i.e. keyboard mapping - and console font. It is applied at boot by - <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> - - <para>The basic file format of the - <filename>vconsole.conf</filename> is a - newline-separated list of environment-like - shell-compatible variable assignments. It is possible - to source the configuration from shell scripts, - however, beyond mere variable assignments no shell - features are supported, allowing applications to read - the file without implementing a shell compatible - execution engine.</para> - - <para>Note that the kernel command line options - <varname>vconsole.keymap=</varname>, - <varname>vconsole.keymap.toggle=</varname>, - <varname>vconsole.font=</varname>, - <varname>vconsole.font.map=</varname>, - <varname>vconsole.font.unimap=</varname> may be used - to override the console settings at boot.</para> - - <para>Depending on the operating system other - configuration files might be checked for configuration - of the virtual console as well, however only as - fallback.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - - <varlistentry> - <term><varname>KEYMAP=</varname></term> - <term><varname>KEYMAP_TOGGLE=</varname></term> - - <listitem><para>Configures the key - mapping table for the - keyboard. <varname>KEYMAP=</varname> - defaults to <literal>us</literal> if - not set. The - <varname>KEYMAP_TOGGLE=</varname> can - be used to configure a second toggle - keymap and is by default - unset.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>FONT=</varname></term> - <term><varname>FONT_MAP=</varname></term> - <term><varname>FONT_UNIMAP=</varname></term> - - <listitem><para>Configures the console - font, the console map and the unicode - font map.</para></listitem> - </varlistentry> - - </variablelist> - </refsect1> - - <refsect1> - <title>Example</title> - - <example> - <title>German keyboard and console</title> - - <para><filename>/etc/vconsole.conf</filename>:</para> - - <programlisting>KEYMAP=de-latin1 + <refentryinfo> + <title>vconsole.conf</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>vconsole.conf</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>vconsole.conf</refname> + <refpurpose>Configuration file for the virtual console</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/vconsole.conf</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/vconsole.conf</filename> file configures + the virtual console, i.e. keyboard mapping and console font. It is + applied at boot by + <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + + <para>The basic file format of the + <filename>vconsole.conf</filename> is a newline-separated list of + environment-like shell-compatible variable assignments. It is + possible to source the configuration from shell scripts, however, + beyond mere variable assignments no shell features are supported, + allowing applications to read the file without implementing a + shell compatible execution engine.</para> + + <para>Note that the kernel command line options + <varname>vconsole.keymap=</varname>, + <varname>vconsole.keymap.toggle=</varname>, + <varname>vconsole.font=</varname>, + <varname>vconsole.font.map=</varname>, + <varname>vconsole.font.unimap=</varname> may be used + to override the console settings at boot.</para> + + <para>Depending on the operating system other configuration files + might be checked for configuration of the virtual console as well, + however only as fallback.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + + <varlistentry> + <term><varname>KEYMAP=</varname></term> + <term><varname>KEYMAP_TOGGLE=</varname></term> + + <listitem><para>Configures the key mapping table for the + keyboard. <varname>KEYMAP=</varname> defaults to + <literal>us</literal> if not set. The + <varname>KEYMAP_TOGGLE=</varname> can be used to configure a + second toggle keymap and is by default + unset.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FONT=</varname></term> + <term><varname>FONT_MAP=</varname></term> + <term><varname>FONT_UNIMAP=</varname></term> + + <listitem><para>Configures the console font, the console map + and the unicode font map.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> + + <example> + <title>German keyboard and console</title> + + <para><filename>/etc/vconsole.conf</filename>:</para> + + <programlisting>KEYMAP=de-latin1 FONT=eurlatgr</programlisting> - </example> - - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> - </refsect1> + </example> + + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-localed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> </refentry> |