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>Socket 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      <varlistentry>
109        <term><varname>RuntimeMaxSec=</varname></term>
110
111        <listitem><para>Configures a maximum time for the scope to run. If this is used and the scope has been
112        active for longer than the specified time it is terminated and put into a failure state. Pass
113        <literal>infinity</literal> (the default) to configure no runtime limit.</para></listitem>
114      </varlistentry>
115
116      <varlistentry>
117        <term><varname>RuntimeRandomizedExtraSec=</varname></term>
118
119        <listitem><para>This option modifies <varname>RuntimeMaxSec=</varname> by increasing the maximum runtime by an
120        evenly distributed duration between 0 and the specified value (in seconds). If <varname>RuntimeMaxSec=</varname> is
121        unspecified, then this feature will be disabled.
122        </para></listitem>
123      </varlistentry>
124    </variablelist>
125
126    <xi:include href="systemd.service.xml" xpointer="shared-unit-options" />
127  </refsect1>
128
129  <refsect1>
130    <title>See Also</title>
131    <para>
132      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
133      <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
134      <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
135      <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
136      <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
137      <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
138    </para>
139  </refsect1>
140
141</refentry>
142