"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
+ SPDX-License-Identifier: LGPL-2.1+
+
This file is part of systemd.
Copyright 2013 Zbigniew Jędrzejewski-Szmek
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>
+ <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>
+ as UNIX and DNS host names. For details, see below.</para>
+
+ <para>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 may be:</para>
<itemizedlist>
- <listitem><para>Directory trees containing an OS, including its
+ <listitem><para>Directory trees containing an OS, including the
top-level directories <filename>/usr</filename>,
<filename>/etc</filename>, and so on.</para></listitem>
<varlistentry>
<term><option>--mkdir</option></term>
- <listitem><para>When used with <command>bind</command>, creates
- the destination directory before applying the bind
- mount.</para></listitem>
+ <listitem><para>When used with <command>bind</command>, creates the destination file or directory before
+ applying the bind mount. Note that even though the name of this option suggests that it is suitable only for
+ directories, this option also creates the destination file node to mount over if the the object to mount is not
+ a directory, but a regular file, device node, socket or FIFO.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--read-only</option></term>
- <listitem><para>When used with <command>bind</command>, applies
- a read-only bind mount.</para>
+ <listitem><para>When used with <command>bind</command>, creates a read-only bind mount.</para>
<para>When used with <command>clone</command>, <command>import-raw</command> or <command>import-tar</command> a
read-only container or VM image is created.</para></listitem>
Defaults to 1. All addresses can be requested with <literal>all</literal>
as argument to <option>--max-addresses</option> . If the argument to
<option>--max-addresses</option> is less than the actual number
- of addresses,<literal>...</literal>follows the last address.
+ of addresses, <literal>...</literal>follows the last address.
If multiple addresses are to be written for a given machine, every
address except the first one is on a new line and is followed by
<literal>,</literal> if another address will be output afterwards. </para></listitem>
</varlistentry>
<xi:include href="user-system-options.xml" xpointer="host" />
- <xi:include href="user-system-options.xml" xpointer="machine" />
+
+ <varlistentry>
+ <term><option>-M</option></term>
+ <term><option>--machine=</option></term>
+
+ <listitem><para>Connect to
+ <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ running in a local container, to perform the specified operation within
+ the container.</para></listitem>
+ </varlistentry>
<xi:include href="standard-options.xml" xpointer="no-pager" />
<xi:include href="standard-options.xml" xpointer="no-legend" />
user may be selected. Use <option>--setenv=</option> to set
environment variables for the executed process.</para>
+ <para>Note that <command>machinectl shell</command> does not propagate the exit code/status of the invoked
+ shell process. Use <command>systemd-run</command> instead if that information is required (see below).</para>
+
<para>When using the <command>shell</command> command without
arguments, (thus invoking the executed shell or command on the
local host), it is in many ways similar to a <citerefentry
environment variables or resource limits, among other
properties.</para>
- <para>Note that
- <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- 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>
+ <para>Note that <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ with its <option>--machine=</option> switch may be used in place of the <command>machinectl shell</command>
+ command, and allows non-interactive operation, more detailed and low-level configuration of the invoked unit,
+ as well as access to runtime and exit code/status information of the invoked shell process. In particular, use
+ <command>systemd-run</command>'s <option>--wait</option> switch to propagate exit status information of the
+ invoked process. Use <command>systemd-run</command>'s <option>--pty</option> switch for acquiring an
+ interactive shell, similar to <command>machinectl shell</command>. In general, <command>systemd-run</command>
+ is preferable for scripting purposes. However, note that <command>systemd-run</command> might require higher
+ privileges than <command>machinectl shell</command>.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><command>bind</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
- <listitem><para>Bind mounts a directory from the host into the
- specified container. The first directory argument is the
- source directory on the host, the second directory argument
- is the destination directory in the container. When the
- latter is omitted, the destination path in the container is
- the same as the source path on the host. When combined with
- the <option>--read-only</option> switch, a ready-only bind
- mount is created. When combined with the
- <option>--mkdir</option> switch, the destination path is first
- created before the mount is applied. Note that this option is
- currently only supported for
- <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- containers.</para></listitem>
+ <listitem><para>Bind mounts a file or directory from the host into the specified container. The first path
+ argument is the source file or directory on the host, the second path argument is the destination file or
+ directory in the container. When the latter is omitted, the destination path in the container is the same as
+ the source path on the host. When combined with the <option>--read-only</option> switch, a ready-only bind
+ mount is created. When combined with the <option>--mkdir</option> switch, the destination path is first created
+ before the mount is applied. Note that this option is currently only supported for
+ <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> containers,
+ and only if user namespacing (<option>--private-users</option>) is not used. This command supports bind
+ mounting directories, regular files, device nodes, <constant>AF_UNIX</constant> socket nodes, as well as
+ FIFOs.</para></listitem>
</varlistentry>
<varlistentry>
system into a running container. Takes a container name,
followed by the source path on the host and the destination
path in the container. If the destination path is omitted, the
- same as the source path is used.</para></listitem>
- </varlistentry>
+ same as the source path is used.</para>
+ <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
+ group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
+ user and group (UID/GID 0).</para></listitem>
+ </varlistentry>
<varlistentry>
<term><command>copy-from</command> <replaceable>NAME</replaceable> <replaceable>PATH</replaceable> [<replaceable>PATH</replaceable>]</term>
into the host system. Takes a container name, followed by the
source path in the container the destination path on the host.
If the destination path is omitted, the same as the source path
- is used.</para></listitem>
+ is used.</para>
+
+ <para>If host and container share the same user and group namespace, file ownership by numeric user ID and
+ group ID is preserved for the copy, otherwise all files and directories in the copy will be owned by the root
+ user and group (UID/GID 0).</para></listitem>
</varlistentry>
</variablelist></refsect2>
is automatically derived from the last component of the URL,
with its suffix removed.</para>
- <para>The image is verified before it is made available,
- unless <option>--verify=no</option> is specified. Verification
- is done via SHA256SUMS and SHA256SUMS.gpg files that need to
- be made available on the same web server, under the same URL
- as the <filename>.tar</filename> file, but with the last
- component (the filename) of the URL replaced. With
- <option>--verify=checksum</option>, only the SHA256 checksum
- for the file is verified, based on the
- <filename>SHA256SUMS</filename> file. With
- <option>--verify=signature</option>, the SHA256SUMS file is
- first verified with detached GPG signature file
- <filename>SHA256SUMS.gpg</filename>. The public key for this
- verification step needs to be available in
+ <para>The image is verified before it is made available, unless
+ <option>--verify=no</option> is specified.
+ Verification is done either via an inline signed file with the name
+ of the image and the suffix <filename>.sha256</filename> or via
+ separate <filename>SHA256SUMS</filename> and
+ <filename>SHA256SUMS.gpg</filename> files.
+ The signature files need to be made available on the same web
+ server, under the same URL as the <filename>.tar</filename> file.
+ With <option>--verify=checksum</option>, only the SHA256 checksum
+ for the file is verified, based on the <filename>.sha256</filename>
+ suffixed file or the<filename>SHA256SUMS</filename> file.
+ With <option>--verify=signature</option>, the sha checksum file is
+ first verified with the inline signature in the
+ <filename>.sha256</filename> file or the detached GPG signature file
+ <filename>SHA256SUMS.gpg</filename>.
+ The public key for this verification step needs to be available in
<filename>/usr/lib/systemd/import-pubring.gpg</filename> or
<filename>/etc/systemd/import-pubring.gpg</filename>.</para>
qcow2 or raw disk image, possibly compressed with xz, gzip or
bzip2. If the second argument (the resulting image name) is
not specified, it is automatically derived from the file
- name. If the file name is passed as <literal>-</literal>, the
+ name. If the filename is passed as <literal>-</literal>, the
image is read from standard input, in which case the second
argument is mandatory.</para>
projects / thirdparty / systemd.git / blobdiff