man/systemd.scope.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd.scope" xmlns:xi="http://www.w3.org/2001/XInclude">
   7   <refentryinfo>
   8     <title>systemd.scope</title>
   9     <productname>systemd</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>systemd.scope</refentrytitle>
  14     <manvolnum>5</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>systemd.scope</refname>
  19     <refpurpose>Scope unit configuration</refpurpose>
  20   </refnamediv>
  21
  22   <refsynopsisdiv>
  23     <para><filename><replaceable>scope</replaceable>.scope</filename></para>
  24   </refsynopsisdiv>
  25
  26   <refsect1>
  27     <title>Description</title>
  28
  29     <para>Scope units are not configured via unit configuration files,
  30     but are only created programmatically using the bus interfaces of
  31     systemd. They are named similar to filenames. A unit whose name
  32     ends in <literal>.scope</literal> refers to a scope unit. Scopes
  33     units manage a set of system processes. Unlike service units, scope
  34     units manage externally created processes, and do not fork off
  35     processes on its own.</para>
  36
  37     <para>The main purpose of scope units is grouping worker processes
  38     of a system service for organization and for managing resources.</para>
  39
  40     <para><command>systemd-run <option>--scope</option></command> may
  41     be used to easily launch a command in a new scope unit from the
  42     command line.</para>
  43
  44     <para>See the <ulink
  45     url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface">New
  46     Control Group Interfaces</ulink> for an introduction on how to make
  47     use of scope units from programs.</para>
  48
  49     <para>Note that, unlike service units, scope units have no "main" process: all processes in the scope are
  50     equivalent. The lifecycle of the scope unit is thus not bound to the lifetime of one specific process,
  51     but to the existence of at least one process in the scope. This also means that the exit statuses of
  52     these processes are not relevant for the scope unit failure state. Scope units may still enter a failure
  53     state, for example due to resource exhaustion or stop timeouts being reached, but not due to programs
  54     inside of them terminating uncleanly. Since processes managed as scope units generally remain children of
  55     the original process that forked them off, it is also the job of that process to collect their exit
  56     statuses and act on them as needed.</para>
  57   </refsect1>
  58
  59   <refsect1>
  60     <title>Automatic Dependencies</title>
  61
  62     <refsect2>
  63       <title>Implicit Dependencies</title>
  64
  65       <para>Implicit dependencies may be added as result of
  66       resource control parameters as documented in
  67       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  68     </refsect2>
  69
  70     <refsect2>
  71       <title>Default Dependencies</title>
  72
  73       <para>The following dependencies are added unless
  74       <varname>DefaultDependencies=no</varname> is set:</para>
  75
  76       <itemizedlist>
  77         <listitem><para>Scope units will automatically have dependencies of
  78         type <varname>Conflicts=</varname> and
  79         <varname>Before=</varname> on
  80         <filename>shutdown.target</filename>. These ensure
  81         that scope units are removed prior to system
  82         shutdown. Only scope units involved with early boot or
  83         late system shutdown should disable
  84         <varname>DefaultDependencies=</varname> option.</para></listitem>
  85       </itemizedlist>
  86     </refsect2>
  87   </refsect1>
  88
  89   <refsect1>
  90     <title>Options</title>
  91
  92     <para>Scope files may include a [Unit] section, which is described in
  93     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  94     </para>
  95
  96     <para>Scope files may include a [Scope]
  97     section, which carries information about the scope and the
  98     units it contains. A number of options that may be used in
  99     this section are shared with other unit types. These options are
 100     documented in
 101     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 102     and
 103     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 104     The options specific to the [Scope] section
 105     of scope units are the following:</para>
 106
 107     <variablelist class='unit-directives'>
 108       <xi:include href="systemd.service.xml" xpointer="oom-policy" />
 109
 110       <varlistentry>
 111         <term><varname>RuntimeMaxSec=</varname></term>
 112
 113         <listitem><para>Configures a maximum time for the scope to run. If this is used and the scope has been
 114         active for longer than the specified time it is terminated and put into a failure state. Pass
 115         <literal>infinity</literal> (the default) to configure no runtime limit.</para>
 116
 117         <xi:include href="version-info.xml" xpointer="v244"/></listitem>
 118       </varlistentry>
 119
 120       <varlistentry>
 121         <term><varname>RuntimeRandomizedExtraSec=</varname></term>
 122
 123         <listitem><para>This option modifies <varname>RuntimeMaxSec=</varname> by increasing the maximum runtime by an
 124         evenly distributed duration between 0 and the specified value (in seconds). If <varname>RuntimeMaxSec=</varname> is
 125         unspecified, then this feature will be disabled.
 126         </para>
 127
 128         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 129       </varlistentry>
 130     </variablelist>
 131
 132     <xi:include href="systemd.service.xml" xpointer="shared-unit-options" />
 133   </refsect1>
 134
 135   <refsect1>
 136     <title>See Also</title>
 137     <para>
 138       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 139       <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 140       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 141       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 142       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 143       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 144     </para>
 145   </refsect1>
 146
 147 </refentry>