1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
'\" t
.TH "SYSTEMD\&.SCOPE" "5" "" "systemd 255" "systemd.scope"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd.scope \- Scope unit configuration
.SH "SYNOPSIS"
.PP
\fIscope\fR\&.scope
.SH "DESCRIPTION"
.PP
Scope units are not configured via unit configuration files, but are only created programmatically using the bus interfaces of systemd\&. They are named similar to filenames\&. A unit whose name ends in
"\&.scope"
refers to a scope unit\&. Scopes units manage a set of system processes\&. Unlike service units, scope units manage externally created processes, and do not fork off processes on its own\&.
.PP
The main purpose of scope units is grouping worker processes of a system service for organization and for managing resources\&.
.PP
\fBsystemd\-run \fR\fB\fB\-\-scope\fR\fR
may be used to easily launch a command in a new scope unit from the command line\&.
.PP
See the
\m[blue]\fBNew Control Group Interfaces\fR\m[]\&\s-2\u[1]\d\s+2
for an introduction on how to make use of scope units from programs\&.
.PP
Note that, unlike service units, scope units have no "main" process: all processes in the scope are equivalent\&. The lifecycle of the scope unit is thus not bound to the lifetime of one specific process, but to the existence of at least one process in the scope\&. This also means that the exit statuses of these processes are not relevant for the scope unit failure state\&. Scope units may still enter a failure state, for example due to resource exhaustion or stop timeouts being reached, but not due to programs inside of them terminating uncleanly\&. Since processes managed as scope units generally remain children of the original process that forked them off, it is also the job of that process to collect their exit statuses and act on them as needed\&.
.SH "AUTOMATIC DEPENDENCIES"
.SS "Implicit Dependencies"
.PP
Implicit dependencies may be added as result of resource control parameters as documented in
\fBsystemd.resource-control\fR(5)\&.
.SS "Default Dependencies"
.PP
The following dependencies are added unless
\fIDefaultDependencies=no\fR
is set:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Scope units will automatically have dependencies of type
\fIConflicts=\fR
and
\fIBefore=\fR
on
shutdown\&.target\&. These ensure that scope units are removed prior to system shutdown\&. Only scope units involved with early boot or late system shutdown should disable
\fIDefaultDependencies=\fR
option\&.
.RE
.SH "OPTIONS"
.PP
Scope files may include a [Unit] section, which is described in
\fBsystemd.unit\fR(5)\&.
.PP
Scope files may include a [Scope] section, which carries information about the scope and the units it contains\&. A number of options that may be used in this section are shared with other unit types\&. These options are documented in
\fBsystemd.kill\fR(5)
and
\fBsystemd.resource-control\fR(5)\&. The options specific to the [Scope] section of scope units are the following:
.PP
\fIOOMPolicy=\fR
.RS 4
Configure the out\-of\-memory (OOM) killing policy for the kernel and the userspace OOM killer
\fBsystemd-oomd.service\fR(8)\&. On Linux, when memory becomes scarce to the point that the kernel has trouble allocating memory for itself, it might decide to kill a running process in order to free up memory and reduce memory pressure\&. Note that
systemd\-oomd\&.service
is a more flexible solution that aims to prevent out\-of\-memory situations for the userspace too, not just the kernel, by attempting to terminate services earlier, before the kernel would have to act\&.
.sp
This setting takes one of
\fBcontinue\fR,
\fBstop\fR
or
\fBkill\fR\&. If set to
\fBcontinue\fR
and a process in the unit is killed by the OOM killer, this is logged but the unit continues running\&. If set to
\fBstop\fR
the event is logged but the unit is terminated cleanly by the service manager\&. If set to
\fBkill\fR
and one of the unit\*(Aqs processes is killed by the OOM killer the kernel is instructed to kill all remaining processes of the unit too, by setting the
memory\&.oom\&.group
attribute to
\fB1\fR; also see kernel page
\m[blue]\fBControl Group v2\fR\m[]\&\s-2\u[2]\d\s+2\&.
.sp
Defaults to the setting
\fIDefaultOOMPolicy=\fR
in
\fBsystemd-system.conf\fR(5)
is set to, except for units where
\fIDelegate=\fR
is turned on, where it defaults to
\fBcontinue\fR\&.
.sp
Use the
\fIOOMScoreAdjust=\fR
setting to configure whether processes of the unit shall be considered preferred or less preferred candidates for process termination by the Linux OOM killer logic\&. See
\fBsystemd.exec\fR(5)
for details\&.
.sp
This setting also applies to
\fBsystemd-oomd.service\fR(8)\&. Similarly to the kernel OOM kills performed by the kernel, this setting determines the state of the unit after
\fBsystemd\-oomd\fR
kills a cgroup associated with it\&.
.sp
Added in version 243\&.
.RE
.PP
\fIRuntimeMaxSec=\fR
.RS 4
Configures a maximum time for the scope to run\&. If this is used and the scope has been active for longer than the specified time it is terminated and put into a failure state\&. Pass
"infinity"
(the default) to configure no runtime limit\&.
.sp
Added in version 244\&.
.RE
.PP
\fIRuntimeRandomizedExtraSec=\fR
.RS 4
This option modifies
\fIRuntimeMaxSec=\fR
by increasing the maximum runtime by an evenly distributed duration between 0 and the specified value (in seconds)\&. If
\fIRuntimeMaxSec=\fR
is unspecified, then this feature will be disabled\&.
.sp
Added in version 250\&.
.RE
.PP
Check
\fBsystemd.unit\fR(5),
\fBsystemd.exec\fR(5), and
\fBsystemd.kill\fR(5)
for more settings\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsystemd-run\fR(1),
\fBsystemd.unit\fR(5),
\fBsystemd.resource-control\fR(5),
\fBsystemd.service\fR(5),
\fBsystemd.directives\fR(7)\&.
.SH "NOTES"
.IP " 1." 4
New Control Group Interfaces
.RS 4
\%https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface
.RE
.IP " 2." 4
Control Group v2
.RS 4
\%https://docs.kernel.org/admin-guide/cgroup-v2.html
.RE
|
