|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | AUTOMATIC DEPENDENCIES | OPTIONS | SEE ALSO | NOTES | COLOPHON |
|
|
|
SYSTEMD.SCOPE(5) systemd.scope SYSTEMD.SCOPE(5)
systemd.scope - Scope unit configuration
scope.scope
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.
The main purpose of scope units is grouping worker processes of a
system service for organization and for managing resources.
systemd-run --scope may be used to easily launch a command in a
new scope unit from the command line.
See the New Control Group Interfaces[1] for an introduction on how
to make use of scope units from programs.
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.
Implicit Dependencies
Implicit dependencies may be added as result of resource control
parameters as documented in systemd.resource-control(5).
Default Dependencies
The following dependencies are added unless DefaultDependencies=no
is set:
• Scope units will automatically have dependencies of type
Conflicts= and Before= 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 DefaultDependencies= option.
Scope files may include a [Unit] section, which is described in
systemd.unit(5).
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:
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 but the unit is 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].
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.
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.
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.
Check systemd.unit(5), systemd.exec(5), and systemd.kill(5) for
more settings.
systemd(1), systemd-run(1), systemd.unit(5),
systemd.resource-control(5), systemd.service(5),
systemd.directives(7).
1. New Control Group Interfaces
https://systemd.io/CONTROL_GROUP_INTERFACE
2. Control Group v2
https://docs.kernel.org/admin-guide/cgroup-v2.html
This page is part of the systemd (systemd system and service
manager) project. Information about the project can be found at
⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a
bug report for this manual page, see
⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
This page was obtained from the project's upstream Git repository
⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11. (At that
time, the date of the most recent commit that was found in the
repository was 2025-08-11.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
systemd 258~rc2 SYSTEMD.SCOPE(5)
Pages that refer to this page: systemd(1), systemd-run(1), environment.d(5), logind.conf(5), systemd.kill(5), systemd.resource-control(5), systemd.slice(5), systemd.unit(5), user@.service(5), systemd.directives(7), systemd.index(7), systemd.syntax(7), pam_systemd(8)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|