[systemd-commits] 4 commits - TODO man/pam_systemd.xml man/systemctl.xml man/systemd.cgroup.xml man/systemd.scope.xml man/systemd.slice.xml man/systemd.snapshot.xml src/systemctl
Lennart Poettering
lennart at kemper.freedesktop.org
Fri Jul 19 10:29:19 PDT 2013
TODO | 1
man/pam_systemd.xml | 140 ++++++++--------------------------------------
man/systemctl.xml | 107 ++++++-----------------------------
man/systemd.cgroup.xml | 6 +
man/systemd.scope.xml | 33 ++++------
man/systemd.slice.xml | 34 +++++++++--
man/systemd.snapshot.xml | 2
src/systemctl/systemctl.c | 2
8 files changed, 94 insertions(+), 231 deletions(-)
New commits:
commit 83787333bd75f3fb5d2d844a5d5dbf68d93f7f3f
Author: Lennart Poettering <lennart at poettering.net>
Date: Fri Jul 19 19:28:16 2013 +0200
man: update documentation of systemctl cgroup commands
diff --git a/TODO b/TODO
index 0b11599..33308ef 100644
--- a/TODO
+++ b/TODO
@@ -46,7 +46,6 @@ CGroup Rework Completion:
* introduce high-level settings for RT budget, swappiness
* wiki: document new bus APIs of PID 1 (transient units, Reloading signal)
-* review: systemctl commands
* Send SIGHUP and SIGTERM in session scopes
diff --git a/man/systemctl.xml b/man/systemctl.xml
index 9820517..4bfce95 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -433,10 +433,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
is lost on reboot, the changes are lost too.</para>
<para>Similar, when used with
- <command>set-cgroup-attr</command>,
- <command>unset-cgroup-attr</command>,
- <command>set-cgroup</command> and
- <command>unset-cgroup</command>, make changes only
+ <command>set-property</command> make changes only
temporarily, so that they are lost on the next
reboot.</para>
</listitem>
@@ -719,93 +716,28 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
</varlistentry>
<varlistentry>
- <term><command>get-cgroup-attr <replaceable>NAME</replaceable> <replaceable>ATTRIBUTE</replaceable>...</command></term>
+ <term><command>set-property <replaceable>NAME</replaceable> <replaceable>ASSIGNMENT</replaceable>...</command></term>
<listitem>
- <para>Retrieve the specified control group attributes of the
- specified unit. Takes a unit name and one or more attribute
- names such as <literal>cpu.shares</literal>. This will
- output the current values of the specified attributes,
- separated by new-lines. For attributes that take a list of
- items, the output will be newline-separated, too. This
- operation will always try to retrieve the data in question
- from the kernel first, and if that is not available, use the
- configured values instead. Instead of low-level control
- group attribute names, high-level pretty names may be used,
- as used for unit execution environment configuration, see
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details. For example, passing
- <literal>memory.limit_in_bytes</literal> and
- <literal>MemoryLimit</literal> is equivalent.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>set-cgroup-attr <replaceable>NAME</replaceable> <replaceable>ATTRIBUTE</replaceable> <replaceable>VALUE</replaceable>...</command></term>
-
- <listitem>
- <para>Set the specified control group attribute of the
- specified unit to the specified value. Takes a unit
- name and an attribute name such as
- <literal>cpu.shares</literal>, plus one or more values
- (multiple values may only be used for attributes that take
- multiple values). This operation will immediately update the
- kernel attribute for this unit and persistently store this
- setting for later reboots (unless <option>--runtime</option>
- is passed, in which case the setting is not saved
- persistently and only valid until the next reboot.) Instead
- of low-level control group attribute names, high-level pretty
- names may be used, as used for unit execution environment
- configuration, see
- <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details. For example, passing
- <literal>memory.limit_in_bytes</literal> and
- <literal>MemoryLimit</literal> is equivalent. This operation
- will implicitly create a control group for the unit in the
- controller the attribute belongs to, if needed. For
- attributes that take multiple values, this operation will
- append the specified values to the previously set values
- list (use <command>unset-cgroup-attr</command> to reset the
- list explicitly). For attributes that take a single value
- only, the list will be reset implicitly.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>unset-cgroup-attr <replaceable>NAME</replaceable> <replaceable>ATTRIBUTE</replaceable>...</command></term>
+ <para>Set the specified unit properties at runtime where
+ this is supported. This allows changing configuration
+ parameter properties such as resource management controls at
+ runtime. Not all properties may be changed at runtime, but
+ many resource management settings (primarily those in
+ <citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
+ may. The changes are applied instantly, and stored on disk
+ for future boots, unless <option>--runtime</option> is
+ passed in which case the settings only apply until the next
+ reboot. The syntax of the property assignment follows
+ closely the syntax of assignments in unit files.</para>
- <listitem><para>Unset the specified control group attributes
- of the specified unit. Takes a unit name and one or more
- attribut names such as <literal>cpu.shares</literal>. This
- operation might or might not have an immediate effect on the
- current kernel attribute value. This will remove any
- persistently stored configuration values for this attribute
- (as set with <command>set-cgroup-attr</command> before),
- unless <option>--runtime</option> is passed, in which case the
- configuration is reset only until the next reboot. Again,
- high-level control group attributes may be used instead of the
- low-level kernel ones. For attributes which take multiple
- values, all currently set values are reset.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>set-cgroup <replaceable>NAME</replaceable> <replaceable>CGROUP</replaceable>...</command></term>
- <term><command>unset-cgroup <replaceable>NAME</replaceable> <replaceable>CGROUP</replaceable>...</command></term>
+ <para>Example: <command>systemctl set-property foobar.service CPUShares=777</command></para>
- <listitem><para>Add or remove a unit to/from a specific
- control group hierarchy and/or control group path. Takes a
- unit name, plus a control group specification in the syntax
- <replaceable>CONTROLLER</replaceable>:<replaceable>PATH</replaceable>
- or <replaceable>CONTROLLER</replaceable>. In the latter syntax
- (where the path is omitted), the default unit control group
- path is implied. Examples: <literal>cpu</literal> or
- <literal>cpu:/foo/bar</literal>. If a unit is removed from a
- control group hierarchy, all its processes will be moved to the
- root group of the hierarchy and all control group attributes
- will be reset. These operations are immediately reflected in
- the kernel hierarchy, and stored persistently to disk (unless
- <option>--runtime</option> is passed).</para>
+ <para>Note that this command allows changing multiple
+ properties at the same time, which is preferable over
+ setting them individually. Like unit file configuration
+ settings assigning the empty list to list parameters will
+ reset the list.</para>
</listitem>
</varlistentry>
@@ -1354,6 +1286,7 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.cgroupq</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>
diff --git a/src/systemctl/systemctl.c b/src/systemctl/systemctl.c
index c9f9981..9f47b2c 100644
--- a/src/systemctl/systemctl.c
+++ b/src/systemctl/systemctl.c
@@ -4788,7 +4788,7 @@ static int systemctl_help(void) {
" list-jobs List jobs\n"
" cancel [JOB...] Cancel all, one, or more jobs\n\n"
"Status Commands:\n"
- " dump Dump server status\n"
+ " dump Dump server status\n\n"
"Snapshot Commands:\n"
" snapshot [NAME] Create a snapshot\n"
" delete [NAME...] Remove one or more snapshots\n\n"
commit 847ae0ae7f29e7bfb245d692409fc2948eab7d1d
Author: Lennart Poettering <lennart at poettering.net>
Date: Fri Jul 19 19:16:47 2013 +0200
man: update documentation of slice units a bit
diff --git a/TODO b/TODO
index 79be347..0b11599 100644
--- a/TODO
+++ b/TODO
@@ -46,7 +46,7 @@ CGroup Rework Completion:
* introduce high-level settings for RT budget, swappiness
* wiki: document new bus APIs of PID 1 (transient units, Reloading signal)
-* review: slice units, systemctl commands
+* review: systemctl commands
* Send SIGHUP and SIGTERM in session scopes
diff --git a/man/systemd.scope.xml b/man/systemd.scope.xml
index 1400f8f..ff41c92 100644
--- a/man/systemd.scope.xml
+++ b/man/systemd.scope.xml
@@ -63,7 +63,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
processes on its own.</para>
<para>The main purpose of scope units is grouping worker processes
- of a system service for organization and resource management.</para>
+ 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
diff --git a/man/systemd.slice.xml b/man/systemd.slice.xml
index 5376921..7ddef85 100644
--- a/man/systemd.slice.xml
+++ b/man/systemd.slice.xml
@@ -55,14 +55,34 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<title>Description</title>
<para>A unit configuration file whose name ends in
- <literal>.slice</literal> encodes information about a slice
- created by systemd to manage resources used by a certain group of
+ <literal>.slice</literal> encodes information about a slice which
+ is a concept for hierarchially managing resources of a group of
processes. This management is performed by creating a node in the
- control group tree. Those processes are part of different units,
- usually <literal>.service</literal> units (see
- <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+ control group tree. Units that manage processes (primarilly scope
+ and service units) may be assigned to a specific slice. For each
+ slice certain resource limits may the be set, that apply to all
+ processes of all units contained in that slice. Slices are
+ organized hierarchially in a tree. The name of the slice encodes
+ the location in the tree. The name consists of a "-" separated
+ series of names, which describes the path to the slice from the
+ root slice. The root slice is named,
+ <filename>-.slice</filename>. Example:
+ <filename>foo-bar.slice</filename> is a slice that is located
+ within <filename>foo.slice</filename>, which in turn is located in
+ the root slice <filename>-.slice</filename>.
</para>
+ <para>By default service and scope units are placed in
+ <filename>system.slice</filename>, virtual machines and containers
+ registered with
+ <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ are found in <filename>machine.slice</filename>, and user sessions
+ handled by
+ <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ in <filename>user.slice</filename>. See
+ <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for more information.</para>
+
<para>See
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for the common options of all unit configuration
@@ -92,7 +112,9 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+ <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
</para>
</refsect1>
commit 9365b048c0c9f62ef7f696216ba049e6b4c2f2e5
Author: Lennart Poettering <lennart at poettering.net>
Date: Fri Jul 19 19:04:17 2013 +0200
man: update scope unit man page a bit
diff --git a/TODO b/TODO
index a4535b5..79be347 100644
--- a/TODO
+++ b/TODO
@@ -46,7 +46,7 @@ CGroup Rework Completion:
* introduce high-level settings for RT budget, swappiness
* wiki: document new bus APIs of PID 1 (transient units, Reloading signal)
-* review: scope units, slice units, systemctl commands
+* review: slice units, systemctl commands
* Send SIGHUP and SIGTERM in session scopes
diff --git a/man/systemd.cgroup.xml b/man/systemd.cgroup.xml
index c2a823e..12b19f5 100644
--- a/man/systemd.cgroup.xml
+++ b/man/systemd.cgroup.xml
@@ -44,7 +44,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<refnamediv>
<refname>systemd.cgroup</refname>
- <refpurpose>Cgroup configuration unit settings</refpurpose>
+ <refpurpose>Control Group configuration unit settings</refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -66,6 +66,10 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
configuration options which configure the control group settings
for spawned processes.</para>
+ <para>Control Groups is a concept for organizing processes in a
+ hierarch tree of named groups for the purpose of resource
+ management.</para>
+
<para>This man page lists the configuration options shared by
those six unit types. See
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
diff --git a/man/systemd.scope.xml b/man/systemd.scope.xml
index 126440a..1400f8f 100644
--- a/man/systemd.scope.xml
+++ b/man/systemd.scope.xml
@@ -54,25 +54,20 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<refsect1>
<title>Description</title>
- <para>A unit configuration file whose name ends in
- <literal>.scope</literal> encodes information about a unit created
- by systemd to encapsulate processes not launched by systemd
- itself. This management is performed by creating a node in the
- control group tree. Processes are moved into the scope by means
- of the D-Bus API.
- <command>systemd-run <option>--scope</option></command> can be
- used to easily launch a command in a new scope unit.</para>
-
- <para>See
- <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for the common options of all unit configuration
- files. The common configuration items are configured
- in the generic [Unit] and [Install] sections. The
- scope specific configuration options are configured in
- the [Scope] section. Currently, only generic cgroup settings
- as described in
- <citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>7</manvolnum></citerefentry> are allowed.
- </para>
+ <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 resource management.</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>Unless <varname>DefaultDependencies=false</varname>
is used, scope units will implicitly have dependencies of
diff --git a/man/systemd.snapshot.xml b/man/systemd.snapshot.xml
index 4e8d5a9..1bb074a 100644
--- a/man/systemd.snapshot.xml
+++ b/man/systemd.snapshot.xml
@@ -56,7 +56,7 @@
<para>Snapshot units are not configured via unit
configuration files. Nonetheless they are named
- similar to filenames. A unit name whose name ends in
+ similar to filenames. A unit whose name ends in
<literal>.snapshot</literal> refers to a dynamic
snapshot of the systemd runtime state.</para>
commit 3e2f69b779aa0f3466ebb45837e8507baa0832f7
Author: Lennart Poettering <lennart at poettering.net>
Date: Fri Jul 19 18:52:09 2013 +0200
man: update pam_systemd documentation to current state of the code
diff --git a/TODO b/TODO
index ffd845b..a4535b5 100644
--- a/TODO
+++ b/TODO
@@ -46,7 +46,7 @@ CGroup Rework Completion:
* introduce high-level settings for RT budget, swappiness
* wiki: document new bus APIs of PID 1 (transient units, Reloading signal)
-* review: scope units, slice units, pam_system, systemctl commands
+* review: scope units, slice units, systemctl commands
* Send SIGHUP and SIGTERM in session scopes
diff --git a/man/pam_systemd.xml b/man/pam_systemd.xml
index 4e5cdf2..1d924bc 100644
--- a/man/pam_systemd.xml
+++ b/man/pam_systemd.xml
@@ -80,29 +80,32 @@
an independent session counter is
used.</para></listitem>
- <listitem><para>A new control group
- <filename>/user/$USER/$XDG_SESSION_ID</filename>
- is created and the login process moved into
- it.</para></listitem>
+ <listitem><para>A new systemd scope unit is
+ created for the session. If this is the first
+ concurrent session of the user an implicit
+ slice below <filename>user.slice</filename> is
+ automatically created and the scope placed in
+ it. In instance of the system service
+ <filename>user at .service</filename> which runt
+ the systemd user manager
+ instance.</para></listitem>
</orderedlist>
<para>On logout, this module ensures the following:</para>
<orderedlist>
- <listitem><para>If
- <varname>$XDG_SESSION_ID</varname> is set and
- <option>kill-session-processes=1</option> specified, all
- remaining processes in the
- <filename>/user/$USER/$XDG_SESSION_ID</filename>
- control group are killed and the control group
- is removed.</para></listitem>
-
- <listitem><para>If the last subgroup of the
- <filename>/user/$USER</filename> control group
- was removed the
+ <listitem><para>If this is enabled all
+ processes of the session are terminated. If
+ the last concurrent session of a user ends his
+ user systemd instance will be terminated too,
+ and so will the user's slice
+ unit.</para></listitem>
+
+ <listitem><para>If the las concurrent session
+ of a user ends the
<varname>$XDG_RUNTIME_DIR</varname> directory
- and all its contents are
- removed, too.</para></listitem>
+ and all its contents are removed,
+ too.</para></listitem>
</orderedlist>
<para>If the system was not booted up with systemd as
@@ -117,79 +120,6 @@
<para>The following options are understood:</para>
<variablelist class='pam-directives'>
- <varlistentry>
- <term><option>kill-session-processes=</option></term>
-
- <listitem><para>Takes a boolean
- argument. If true, all processes
- created by the user during his session
- and from his session will be
- terminated when he logs out from his
- session.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>kill-only-users=</option></term>
-
- <listitem><para>Takes a comma-separated
- list of usernames or
- numeric user IDs as argument. If this
- option is used, the effect of the
- <option>kill-session-processes=</option> options
- will apply only to the listed
- users. If this option is not used, the
- option applies to all local
- users. Note that
- <option>kill-exclude-users=</option>
- takes precedence over this list and is
- hence subtracted from the list
- specified here.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>kill-exclude-users=</option></term>
-
- <listitem><para>Takes a comma-separated
- list of usernames or
- numeric user IDs as argument. Users
- listed in this argument will not be
- subject to the effect of
- <option>kill-session-processes=</option>.
- Note that this option takes precedence
- over
- <option>kill-only-users=</option>, and
- hence whatever is listed for
- <option>kill-exclude-users=</option>
- is guaranteed to never be killed by
- this PAM module, independent of any
- other configuration
- setting.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>controllers=</option></term>
-
- <listitem><para>Takes a comma-separated
- list of control group
- controllers in which hierarchies a
- user/session control group will be
- created by default for each user
- logging in, in addition to the control
- group in the named 'name=systemd'
- hierarchy. If omitted, defaults to an
- empty list.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>reset-controllers=</option></term>
-
- <listitem><para>Takes a comma-separated
- list of control group
- controllers in which hierarchies the
- logged in processes will be reset to
- the root control
- group.</para></listitem>
- </varlistentry>
<varlistentry>
<term><option>class=</option></term>
@@ -209,29 +139,6 @@
operates.</para></listitem>
</varlistentry>
</variablelist>
-
- <para>Note that setting
- <varname>kill-session-processes=1</varname> will break tools
- like
- <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
-
- <para>Note that
- <varname>kill-session-processes=1</varname> is a
- stricter version of
- <varname>KillUserProcesses=1</varname> which may be
- configured system-wide in
- <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
- former kills processes of a session as soon as it
- ends; the latter kills processes as soon as the last
- session of the user ends.</para>
-
- <para>If the options are omitted they default to
- <option>kill-session-processes=0</option>,
- <option>kill-only-users=</option>,
- <option>kill-exclude-users=</option>,
- <option>controllers=</option>,
- <option>reset-controllers=</option>,
- <option>debug=no</option>.</para>
</refsect1>
<refsect1>
@@ -306,7 +213,7 @@ account required pam_unix.so
password required pam_unix.so
session required pam_unix.so
session required pam_loginuid.so
-session required pam_systemd.so kill-session-processes=1</programlisting>
+session required pam_systemd.so</programlisting>
</refsect1>
<refsect1>
@@ -319,7 +226,10 @@ session required pam_systemd.so kill-session-processes=1</programlisting>
<citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
More information about the systemd-commits
mailing list