| SYSTEMD.SCOPE(5) | systemd.scope | SYSTEMD.SCOPE(5) |
.SH "NAME" systemd.scope - Scope unit configuration
.SH "SYNOPSIS"
.PP scope.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. Scope units manage a set of system processes. Unlike service units,
scope units manage externally created processes, and do not fork off
processes on their own.
.PP The main purpose of scope units is grouping worker processes of a system
service for organization and for managing resources.
.PP systemd-run --scope may be used to easily launch a
command in a new scope unit from the command line.
.PP See the New Control Group Interfaces[1] 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 systemd.resource-control(5).
.SS "Default Dependencies"
.PP The following dependencies are added unless DefaultDependencies=no
is set:
.SH "OPTIONS"
.PP Scope files may include a [Unit] section, which is described in
systemd.unit(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 systemd.kill(5) and systemd.resource-control(5).
The options specific to the [Scope] section of scope units are the
following:
.PP OOMPolicy=
Configure the out-of-memory (OOM) killing policy for the kernel and the
userspace OOM killer systemd-oomd.service(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.
This setting takes one of continue, stop or kill. If set to continue and a process in the unit is killed by the OOM killer, this is logged but the unit continues running. If set to stop the event is logged and the unit's processes are terminated cleanly by the service manager. If set to kill and one of the unit's 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 1; also see kernel page Control Group v2[2]. In case of both stop and kill, the service ultimately ends up in the oom-kill failed state after which Restart= may apply.
Defaults to the setting DefaultOOMPolicy= in systemd-system.conf(5) is set to, except for units where Delegate= is turned on, where it defaults to continue.
Use the OOMScoreAdjust= 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 systemd.exec(5) for details.
This setting also applies to systemd-oomd.service(8). Similarly to the kernel OOM kills performed by the kernel, this setting determines the state of the unit after systemd-oomd kills a cgroup associated with it.
Added in version 253.
.RE
.PP RuntimeMaxSec=
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.
Added in version 244.
.RE
.PP RuntimeRandomizedExtraSec=
This option modifies RuntimeMaxSec= by increasing the maximum runtime
by an evenly distributed duration between 0 and the specified value (in
seconds). If RuntimeMaxSec= is unspecified, then this feature will be
disabled.
Added in version 250.
.RE
.PP Check systemd.unit(5), systemd.exec(5), and
systemd.kill(5) for more settings.
.SH "SEE ALSO"
.PP systemd(1), systemd-run(1), systemd.unit(5),
systemd.resource-control(5), systemd.service(5),
systemd.directives(7).
NOTES
- 1.
- New Control Group Interfaces
- 2.
- Control Group v2
| systemd 262.2 |