1SYSTEMD.SCOPE(5) systemd.scope SYSTEMD.SCOPE(5)
2
6 systemd.scope - Scope unit configuration
7
9 scope.scope
10
12 Scope units are not configured via unit configuration files, but are
13 only created programmatically using the bus interfaces of systemd. They
14 are named similar to filenames. A unit whose name ends in ".scope"
15 refers to a scope unit. Scopes units manage a set of system processes.
16 Unlike service units, scope units manage externally created processes,
17 and do not fork off processes on its own.
18 The main purpose of scope units is grouping worker processes of a
20 system service for organization and for managing resources.
21 systemd-run --scope may be used to easily launch a command in a new
23 scope unit from the command line.
24 See the New Control Group Interfaces[1] for an introduction on how to
26 make use of scope units from programs.
27 Note that, unlike service units, scope units have no "main" process:
29 all processes in the scope are equivalent. The lifecycle of the scope
30 unit is thus not bound to the lifetime of one specific process, but to
31 the existence of at least one process in the scope. This also means
32 that the exit statuses of these processes are not relevant for the
33 scope unit failure state. Scope units may still enter a failure state,
34 for example due to resource exhaustion or stop timeouts being reached,
35 but not due to programs inside of them terminating uncleanly. Since
36 processes managed as scope units generally remain children of the
37 original process that forked them off, it is also the job of that
38 process to collect their exit statuses and act on them as needed.
39
41 Implicit Dependencies
42 Implicit dependencies may be added as result of resource control
43 parameters as documented in systemd.resource-control(5).
44 Default Dependencies
46 The following dependencies are added unless DefaultDependencies=no is
47 set:
48 • Scope units will automatically have dependencies of type Conflicts=
50 and Before= on shutdown.target. These ensure that scope units are
51 removed prior to system shutdown. Only scope units involved with
52 early boot or late system shutdown should disable
53 DefaultDependencies= option.
54
56 Scope files may include a [Unit] section, which is described in
57 systemd.unit(5).
58 Scope files may include a [Scope] section, which carries information
60 about the scope and the units it contains. A number of options that may
61 be used in this section are shared with other unit types. These options
62 are documented in systemd.kill(5) and systemd.resource-control(5). The
63 options specific to the [Scope] section of scope units are the
64 following:
65 OOMPolicy=
67 Configure the out-of-memory (OOM) killing policy for the kernel and
68 the userspace OOM killer systemd-oomd.service(8). On Linux, when
69 memory becomes scarce to the point that the kernel has trouble
70 allocating memory for itself, it might decide to kill a running
71 process in order to free up memory and reduce memory pressure. Note
72 that systemd-oomd.service is a more flexible solution that aims to
73 prevent out-of-memory situations for the userspace too, not just
74 the kernel, by attempting to terminate services earlier, before the
75 kernel would have to act.
76 This setting takes one of continue, stop or kill. If set to
78 continue and a process in the unit is killed by the OOM killer,
79 this is logged but the unit continues running. If set to stop the
80 event is logged but the unit is terminated cleanly by the service
81 manager. If set to kill and one of the unit's processes is killed
82 by the OOM killer the kernel is instructed to kill all remaining
83 processes of the unit too, by setting the memory.oom.group
84 attribute to 1; also see kernel documentation[2].
85 Defaults to the setting DefaultOOMPolicy= in systemd-system.conf(5)
87 is set to, except for units where Delegate= is turned on, where it
88 defaults to continue.
89 Use the OOMScoreAdjust= setting to configure whether processes of
91 the unit shall be considered preferred or less preferred candidates
92 for process termination by the Linux OOM killer logic. See
93 systemd.exec(5) for details.
94 This setting also applies to systemd-oomd.service(8). Similarly to
96 the kernel OOM kills performed by the kernel, this setting
97 determines the state of the unit after systemd-oomd kills a cgroup
98 associated with it.
99 RuntimeMaxSec=
101 Configures a maximum time for the scope to run. If this is used and
102 the scope has been active for longer than the specified time it is
103 terminated and put into a failure state. Pass "infinity" (the
104 default) to configure no runtime limit.
105 RuntimeRandomizedExtraSec=
107 This option modifies RuntimeMaxSec= by increasing the maximum
108 runtime by an evenly distributed duration between 0 and the
109 specified value (in seconds). If RuntimeMaxSec= is unspecified,
110 then this feature will be disabled.
111 Check systemd.unit(5), systemd.exec(5), and systemd.kill(5) for more
113 settings.
114
116 systemd(1), systemd-run(1), systemd.unit(5), systemd.resource-
117 control(5), systemd.service(5), systemd.directives(7).
118
120 1. New Control Group Interfaces
121 https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface
122 2. kernel documentation
124 https://docs.kernel.org/admin-guide/cgroup-v2.html
125systemd 253 SYSTEMD.SCOPE(5)