diff options
Diffstat (limited to 'man/systemd.scope.xml')
| -rw-r--r-- | man/systemd.scope.xml | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/man/systemd.scope.xml b/man/systemd.scope.xml new file mode 100644 index 0000000..95969bf --- /dev/null +++ b/man/systemd.scope.xml @@ -0,0 +1,143 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="systemd.scope" xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>systemd.scope</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.scope</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.scope</refname> + <refpurpose>Scope unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>scope</replaceable>.scope</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>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 <literal>.scope</literal> 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.</para> + + <para>The main purpose of scope units is grouping worker processes + of a system service for organization and for managing resources.</para> + + <para><command>systemd-run <option>--scope</option></command> may + be used to easily launch a command in a new scope unit from the + command line.</para> + + <para>See the <ulink + url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface">New + Control Group Interfaces</ulink> for an introduction on how to make + use of scope units from programs.</para> + + <para>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.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <refsect2> + <title>Implicit Dependencies</title> + + <para>Implicit dependencies may be added as result of + resource control parameters as documented in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + </refsect2> + + <refsect2> + <title>Default Dependencies</title> + + <para>The following dependencies are added unless + <varname>DefaultDependencies=no</varname> is set:</para> + + <itemizedlist> + <listitem><para>Scope units will automatically have dependencies of + type <varname>Conflicts=</varname> and + <varname>Before=</varname> on + <filename>shutdown.target</filename>. These ensure + that scope units are removed prior to system + shutdown. Only scope units involved with early boot or + late system shutdown should disable + <varname>DefaultDependencies=</varname> option.</para></listitem> + </itemizedlist> + </refsect2> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Scope files may include a [Unit] section, which is described in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>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 + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + The options specific to the [Scope] section + of scope units are the following:</para> + + <variablelist class='unit-directives'> + <xi:include href="systemd.service.xml" xpointer="oom-policy" /> + + <varlistentry> + <term><varname>RuntimeMaxSec=</varname></term> + + <listitem><para>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 + <literal>infinity</literal> (the default) to configure no runtime limit.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RuntimeRandomizedExtraSec=</varname></term> + + <listitem><para>This option modifies <varname>RuntimeMaxSec=</varname> by increasing the maximum runtime by an + evenly distributed duration between 0 and the specified value (in seconds). If <varname>RuntimeMaxSec=</varname> is + unspecified, then this feature will be disabled. + </para></listitem> + </varlistentry> + </variablelist> + + <xi:include href="systemd.service.xml" xpointer="shared-unit-options" /> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> + </refsect1> + +</refentry> |