SYSTEMD.SCOPE(5)

💅 NAME 💅

ok so this is systemd.scope — the whole vibe of Scope unit configuration, bestie. that's it, that's the name ✨

---

🎀 SYNOPSIS 🎀

scope.scope

---

🌸 DESCRIPTION 🌸

okay so here's the tea: scope units are not configured through unit configuration files, periodt. like, there's no .scope file you go edit, no cap. they only get created programmatically, through the bus interfaces of systemd. the way that works is they're named kinda like filenames, and any unit whose name ends in .scope is a scope unit, full stop 🫶

so what do scope units even do? they manage a set of system processes. and here's where they differ from service units, bestie: scope units manage externally created processes, and they do not fork off processes on their own. not their job, never was 💅

the main purpose of scope units is grouping worker processes of a system service — for organization, and for managing resources. very main character energy, lowkey 🦋

you can also use systemd-run --scope to easily launch a command in a new scope unit straight from the command line. iconic, honestly.

if you wanna know how to make use of scope units from programs, go look at the New Control Group Interfaces[1] for an introduction 👑

now for the big one — note that unlike service units, scope units have no "main" process. all processes in the scope are equivalent, no favorites 🙈. the lifecycle of the scope unit is therefore not bound to the lifetime of one specific process, but to the existence of at least one process in the scope. which also means the exit statuses of these processes are not relevant for the scope unit failure state.

scope units can still enter a failure state — like, for resource exhaustion or stop timeouts being reached — but not because programs inside them terminated uncleanly. and 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. that's on you, bestie, not on systemd 😭

---

🔥 AUTOMATIC DEPENDENCIES 🔥

✨ Implicit Dependencies ✨

implicit dependencies may be added as a result of resource control parameters, as documented in systemd.resource-control(5). sneaky but valid 💜

💖 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. so if you're out here doing early boot or late system shutdown stuff, you're the only one who should be disabling the DefaultDependencies= option. everyone else, leave it alone 🎀

---

👑 OPTIONS 👑

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 — those are documented in systemd.kill(5) and systemd.resource-control(5). the options specific to the [Scope] section of scope units are the following, and yes we're going through all of them 💅

• 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. business as usual 🫶
• 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 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. no clock, no problem ⭐

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. there's always more settings, bestie 😭

---

🌈 SEE ALSO 🌈

systemd(1), systemd-run(1), systemd.unit(5), systemd.resource-control(5), systemd.service(5), systemd.directives(7).

---

📝 NOTES 📝

1. New Control Group Interfaces https://systemd.io/CONTROL_GROUP_INTERFACE
2. Control Group v2 https://docs.kernel.org/admin-guide/cgroup-v2.html

---

and that's the whole page, babe 🧚 this one's from systemd 262.1 — scope units stay slaying, go forth and group your worker processes responsibly 💖✨🎀