summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
Diffstat (limited to 'man')
-rw-r--r--man/machinectl.xml189
-rw-r--r--man/systemd.exec.xml41
2 files changed, 209 insertions, 21 deletions
diff --git a/man/machinectl.xml b/man/machinectl.xml
index a5eb3f08e4..6cf405ed29 100644
--- a/man/machinectl.xml
+++ b/man/machinectl.xml
@@ -1,4 +1,4 @@
-<?xml version='1.0'?> <!--*-nxml-*-->
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
@@ -65,6 +65,43 @@
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
virtual machine and container registration manager
<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+
+ <para><command>machinectl</command> may be used to execute
+ operations on machines and images. Machines in this sense are
+ considered running instances of:</para>
+
+ <itemizedlist>
+ <listitem><para>Virtual Machines (VMs) that virtualize hardware
+ to run full operating system (OS) instances (including their kernels)
+ in a virtualized environment on top of the host OS.</para></listitem>
+
+ <listitem><para>Containers that share the hardware and
+ OS kernel with the host OS, in order to run
+ OS userspace instances on top the host OS.</para></listitem>
+
+ <listitem><para>The host system itself</para></listitem>
+ </itemizedlist>
+
+ <para>Machines are identified by names that follow the same rules
+ as UNIX and DNS host names, for details see below. Machines are
+ instantiated from disk or file system images, that frequently but not
+ necessarily carry the same name as machines running from
+ them. Images in this sense are considered:</para>
+
+ <itemizedlist>
+ <listitem><para>Directory trees containing an OS, including its
+ top-level directories <filename>/usr</filename>,
+ <filename>/etc</filename>, and so on.</para></listitem>
+
+ <listitem><para>btrfs subvolumes containing OS trees, similar to
+ normal directory trees.</para></listitem>
+
+ <listitem><para>Binary "raw" disk images containing MBR or GPT
+ partition tables and Linux file system partitions.</para></listitem>
+
+ <listitem><para>The file system tree of the host OS itself.</para></listitem>
+ </itemizedlist>
+
</refsect1>
<refsect1>
@@ -138,6 +175,30 @@
</varlistentry>
<varlistentry>
+ <term><option>--uid=</option></term>
+
+ <listitem><para>When used with the <command>shell</command>
+ command, chooses the user ID to open the interactive shell
+ session as. If this switch is not specified, defaults to
+ <literal>root</literal>. Note that this switch is not
+ supported for the <command>login</command> command (see
+ below).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--setenv=</option></term>
+
+ <listitem><para>When used with the <command>shell</command>
+ command, sets an environment variable to pass to the executed
+ shell. Takes a pair of environment variable name and value,
+ separated by <literal>=</literal> as argument. This switch
+ may be used multiple times to set multiple environment
+ variables. Note that this switch is not supported for the
+ <command>login</command> command (see
+ below).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>--mkdir</option></term>
<listitem><para>When used with <command>bind</command> creates
@@ -145,7 +206,6 @@
mount.</para></listitem>
</varlistentry>
-
<varlistentry>
<term><option>--read-only</option></term>
@@ -247,9 +307,11 @@
<term><command>list</command></term>
<listitem><para>List currently running (online) virtual
- machines and containers. To enumerate container images that
- can be started, use <command>list-images</command> (see
- below).</para></listitem>
+ machines and containers. To enumerate machine images that can
+ be started, use <command>list-images</command> (see
+ below). Note that this command hides the special
+ <literal>.host</literal> machine by default. Use the
+ <option>--all</option> switch to show it.</para></listitem>
</varlistentry>
<varlistentry>
@@ -267,7 +329,7 @@
</varlistentry>
<varlistentry>
- <term><command>show</command> <replaceable>NAME</replaceable>...</term>
+ <term><command>show</command> [<replaceable>NAME</replaceable>...]</term>
<listitem><para>Show properties of one or more registered
virtual machines or containers or the manager itself. If no
@@ -316,21 +378,66 @@
</varlistentry>
<varlistentry>
- <term><command>login</command> <replaceable>NAME</replaceable></term>
-
- <listitem><para>Open an interactive terminal login session to
- a container. This will create a TTY connection to a specific
- container and asks for the execution of a getty on it. Note
- that this is only supported for containers running
+ <term><command>login</command> [<replaceable>NAME</replaceable>]</term>
+
+ <listitem><para>Open an interactive terminal login session in
+ a container or on the local host. If an argument is supplied
+ it refers to the container machine to connect to. If none is
+ specified, or the container name is specified as the empty
+ string, or the special machine name <literal>.host</literal>
+ (see below) is specified, the connection is made to the local
+ host instead. This will create a TTY connection to a specific
+ container or the local host and asks for the execution of a
+ getty on it. Note that this is only supported for containers
+ running
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
as init system.</para>
<para>This command will open a full login prompt on the
- container, which then asks for username and password. Use
+ container or the local host, which then asks for username and
+ password. Use <command>shell</command> (see below) or
+ <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ with the <option>--machine=</option> switch to directly invoke
+ a single command, either interactively or in the
+ background.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>shell</command> [[<replaceable>NAME</replaceable>@]<replaceable>NAME</replaceable> [<replaceable>PATH</replaceable> [<replaceable>ARGUMENTS</replaceable>...]]] </term>
+
+ <listitem><para>Open an interactive shell session in a
+ container or on the local host. The first argument refers to
+ the container machine to connect to. If none is specified, or
+ the machine name is specified as the empty string, or the
+ special machine name <literal>.host</literal> (see below) is
+ specified, the connection is made to the local host
+ instead. This works similar to <command>login</command> but
+ immediately invokes a user process. This command runs the
+ specified executable with the specified arguments, or
+ <filename>/bin/sh</filename> if none is specified. By default
+ opens a <literal>root</literal> shell, but by using
+ <option>--uid=</option>, or by prefixing the machine name with
+ a username and an <literal>@</literal> character, a different
+ user may be selected. Use <option>--setenv=</option> to set
+ environment variables for the executed process.</para>
+
+ <para>When using the <command>shell</command> command without
+ arguments (thus invoking the executed shell or command on the
+ local host) it is similar in many ways to a <citerefentry
+ project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ session, but unlike <command>su</command> completely isolates
+ the new session from the originating session, so that it
+ shares no process or session properties, and is in a clean and
+ well-defined state. It will be tracked in a new utmp, login,
+ audit and keyring session, and will not inherit an environment
+ variables or resource limits, among other properties.</para>
+
+ <para>Note that the
<citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- with the <option>--machine=</option> switch to invoke a single
- command, either interactively or in the background within a
- local container.</para></listitem>
+ may be used in place of the <command>shell</command> command,
+ and allows more detailed, low-level configuration of the
+ invoked unit. However, it is frequently more privileged than
+ the <command>shell</command> command.</para></listitem>
</varlistentry>
<varlistentry>
@@ -453,7 +560,7 @@
</varlistentry>
<varlistentry>
- <term><command>image-status</command> <replaceable>NAME</replaceable>...</term>
+ <term><command>image-status</command> [<replaceable>NAME</replaceable>...]</term>
<listitem><para>Show terse status information about one or
more container or VM images. This function is intended to
@@ -463,7 +570,7 @@
</varlistentry>
<varlistentry>
- <term><command>show-image</command> <replaceable>NAME</replaceable>...</term>
+ <term><command>show-image</command> [<replaceable>NAME</replaceable>...]</term>
<listitem><para>Show properties of one or more registered
virtual machine or container images, or the manager itself. If
@@ -766,6 +873,41 @@
</refsect1>
<refsect1>
+ <title>Machine and Image Names</title>
+
+ <para>The <command>machinectl</command> tool operates on machines
+ and images, whose names must be chosen following strict
+ rules. Machine names must be suitable for use as host names
+ following a conservative subset of DNS and UNIX/Linux
+ semantics. Specifically, they must consist of one or more
+ non-empty label strings, separated by dots. No leading or trailing
+ dots are allowed. No sequences of multiple dots are allowed. The
+ label strings may only consists of alphanumeric characters as well
+ as the dash and underscore. The maximum length of a machine name
+ is 64 characters.</para>
+
+ <para>A special machine with the name <literal>.host</literal>
+ refers to the running host system itself. This is useful for execution
+ operations or inspecting the host system as well. Not that
+ <command>machinectl list</command> will not show this special
+ machine unless the <option>--all</option> switch is specified.</para>
+
+ <para>Requirements on image names are less strict, however must be
+ valid UTF-8, must be suitable as file names (hence not be the
+ single or double dot, and not include a slash), and may not
+ contain control characters. Since many operations search for an
+ image by the name of a requested machine it is recommended to name
+ images in the same strict fashion as machines.</para>
+
+ <para>A special image with the name <literal>.host</literal>
+ refers to the image of the running host system. It is hence
+ conceptually maps to the special <literal>.host</literal> machine
+ name described above. Note that <command>machinectl
+ list-images</command> won't show this special image either, unless
+ <option>--all</option> is specified.</para>
+ </refsect1>
+
+ <refsect1>
<title>Files and Directories</title>
<para>Machine images are preferably stored in
@@ -872,6 +1014,17 @@
current directory.</para>
</example>
+ <example>
+ <title>Create a new shell session</title>
+
+ <programlisting># machinectl shell --uid=lennart</programlisting>
+
+ <para>This creates a new shell session on the local host, for
+ the user ID <literal>lennart</literal>, in a <citerefentry
+ project='die-net'><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>-like
+ fashion.</para>
+ </example>
+
</refsect1>
<refsect1>
diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 8fd75d274e..cb11199ad3 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -1,3 +1,4 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
@@ -911,10 +912,16 @@
<term><varname>UtmpIdentifier=</varname></term>
<listitem><para>Takes a four character identifier string for
- an utmp/wtmp entry for this service. This should only be set
- for services such as <command>getty</command> implementations
+ an <citerefentry
+ project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ and wtmp entry for this service. This should only be
+ set for services such as <command>getty</command>
+ implementations (such as <citerefentry
+ project='die-net'><refentrytitle>agetty</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
where utmp/wtmp entries must be created and cleared before and
- after execution. If the configured string is longer than four
+ after execution, or for services that shall be executed as if
+ they were run by a <command>getty</command> process (see
+ below). If the configured string is longer than four
characters, it is truncated and the terminal four characters
are used. This setting interprets %I style string
replacements. This setting is unset by default, i.e. no
@@ -923,6 +930,34 @@
</varlistentry>
<varlistentry>
+ <term><varname>UtmpMode=</varname></term>
+
+ <listitem><para>Takes one of <literal>init</literal>,
+ <literal>login</literal> or <literal>user</literal>. If
+ <varname>UtmpIdentifier=</varname> is set, controls which
+ type of <citerefentry
+ project='man-pages'><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry>/wtmp
+ entries for this service are generated. This setting has no
+ effect unless <varname>UtmpIdentifier=</varname> is set
+ too. If <literal>init</literal> is set, only an
+ <constant>INIT_PROCESS</constant> entry is generated and the
+ invoked process must implement a <command>getty</command>
+ compatible utmp/wtmp logic. If <literal>login</literal> is
+ set, first an <constant>INIT_PROCESS</constant> entry,
+ followed by an <constant>LOGIN_PROCESS</constant> entry is
+ generated. In this case the invoked process must implement a
+ <citerefentry
+ project='die-net'><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible
+ utmp/wtmp logic. If <literal>user</literal> is set, first an
+ <constant>INIT_PROCESS</constant> entry, then a
+ <constant>LOGIN_PROCESS</constant> entry and finally an
+ <constant>USER_PROCESS</constant> entry is generated. In this
+ case the invoked process may be any process that is suitable
+ to be run as session leader. Defaults to
+ <literal>init</literal>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><varname>SELinuxContext=</varname></term>
<listitem><para>Set the SELinux security context of the