mirror of
https://github.com/systemd/systemd
synced 2024-07-22 18:55:10 +00:00
d8e1613ed2
For some unit types we have hundreds of options, and the reader may easily miss that more options are described in other pages. We already mentioned this in the introduction and then at the top of the option list, but it can't hurt to repeat the information. Also, add an (almost empty) Options section for the unit types which don't have any custom options. It is nicer to have the same page structure in all cases, so people can jump between pages for different types more easily.
133 lines
5.6 KiB
XML
133 lines
5.6 KiB
XML
<?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>Socket 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'>
|
|
<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>
|
|
</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>
|