"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
+ SPDX-License-Identifier: LGPL-2.1+
+
This file is part of systemd.
Copyright 2010 Lennart Poettering
<title>Options</title>
<para>If option <option>-b</option> is specified, the arguments
- are used as arguments for the init binary. Otherwise,
+ are used as arguments for the init program. Otherwise,
<replaceable>COMMAND</replaceable> specifies the program to launch
in the container, and the remaining arguments are used as
arguments for this program. If <option>--boot</option> is not used and
<term><option>--as-pid2</option></term>
<listitem><para>Invoke the shell or specified program as process ID (PID) 2 instead of PID 1 (init). By
- default, if neither this option nor <option>--boot</option> is used, the selected binary is run as process with
- PID 1, a mode only suitable for programs that are aware of the special semantics that the process with PID 1
- has on UNIX. For example, it needs to reap all processes reparented to it, and should implement
+ default, if neither this option nor <option>--boot</option> is used, the selected program is run as the process
+ with PID 1, a mode only suitable for programs that are aware of the special semantics that the process with
+ PID 1 has on UNIX. For example, it needs to reap all processes reparented to it, and should implement
<command>sysvinit</command> compatible signal handling (specifically: it needs to reboot on SIGINT, reexecute
on SIGTERM, reload configuration on SIGHUP, and so on). With <option>--as-pid2</option> a minimal stub init
- process is run as PID 1 and the selected binary is executed as PID 2 (and hence does not need to implement any
+ process is run as PID 1 and the selected program is executed as PID 2 (and hence does not need to implement any
special semantics). The stub init process will reap processes as necessary and react appropriately to
signals. It is recommended to use this mode to invoke arbitrary commands in containers, unless they have been
modified to run correctly as PID 1. Or in other words: this switch should be used for pretty much all commands,
<term><option>-b</option></term>
<term><option>--boot</option></term>
- <listitem><para>Automatically search for an init binary and invoke it as PID 1, instead of a shell or a user
+ <listitem><para>Automatically search for an init program and invoke it as PID 1, instead of a shell or a user
supplied program. If this option is used, arguments specified on the command line are used as arguments for the
- init binary. This option may not be combined with <option>--as-pid2</option>.</para>
+ init program. This option may not be combined with <option>--as-pid2</option>.</para>
<para>The following table explains the different modes of invocation and relationship to
<option>--as-pid2</option> (see above):</para>
<row>
<entry><option>--boot</option> specified</entry>
- <entry>An init binary as automatically searched and run as PID 1 in the container. The passed parameters are used as invocation parameters for this process.</entry>
+ <entry>An init program is automatically searched for and run as PID 1 in the container. The passed parameters are used as invocation parameters for this process.</entry>
</row>
</tbody>
</varlistentry>
<varlistentry>
+ <term><option>-S</option></term>
<term><option>--slice=</option></term>
<listitem><para>Make the container part of the specified slice, instead of the default
configured with <option>--network-veth</option>. If this
option is specified, the CAP_NET_ADMIN capability will be
added to the set of capabilities the container retains. The
- latter may be disabled by using
- <option>--drop-capability=</option>.</para></listitem>
+ latter may be disabled by using <option>--drop-capability=</option>.
+ If this option is not specified (or implied by one of the options
+ listed below), the container will have full access to the host network.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--network-namespace-path=</option></term>
+
+ <listitem><para>Takes the path to a file representing a kernel
+ network namespace that the container shall run in. The specified path
+ should refer to a (possibly bind-mounted) network namespace file, as
+ exposed by the kernel below <filename>/proc/$PID/ns/net</filename>.
+ This makes the container enter the given network namespace. One of the
+ typical use cases is to give a network namespace under
+ <filename>/run/netns</filename> created by <citerefentry
+ project='man-pages'><refentrytitle>ip-netns</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ for example, <option>--network-namespace-path=/run/netns/foo</option>.
+ Note that this option cannot be used together with other
+ network-related options, such as <option>--private-network</option>
+ or <option>--network-interface=</option>.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><option>--capability=</option></term>
- <listitem><para>List one or more additional capabilities to
- grant the container. Takes a comma-separated list of
- capability names, see
+ <listitem><para>List one or more additional capabilities to grant the container.
+ Takes a comma-separated list of capability names, see
<citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- for more information. Note that the following capabilities
- will be granted in any way: CAP_CHOWN, CAP_DAC_OVERRIDE,
- CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
- CAP_KILL, CAP_LEASE, CAP_LINUX_IMMUTABLE,
- CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_RAW,
- CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, CAP_SETUID,
- CAP_SYS_ADMIN, CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE,
- CAP_SYS_TTY_CONFIG, CAP_SYS_RESOURCE, CAP_SYS_BOOT,
- CAP_AUDIT_WRITE, CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN is
- retained if <option>--private-network</option> is specified.
- If the special value <literal>all</literal> is passed, all
- capabilities are retained.</para></listitem>
+ for more information. Note that the following capabilities will be granted in any way:
+ CAP_AUDIT_CONTROL, CAP_AUDIT_WRITE, CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
+ CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, CAP_KILL, CAP_LEASE, CAP_LINUX_IMMUTABLE,
+ CAP_MKNOD, CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_RAW, CAP_SETFCAP,
+ CAP_SETGID, CAP_SETPCAP, CAP_SETUID, CAP_SYS_ADMIN, CAP_SYS_BOOT, CAP_SYS_CHROOT,
+ CAP_SYS_NICE, CAP_SYS_PTRACE, CAP_SYS_RESOURCE, CAP_SYS_TTY_CONFIG. Also CAP_NET_ADMIN
+ is retained if <option>--private-network</option> is specified. If the special value
+ <literal>all</literal> is passed, all capabilities are retained.</para></listitem>
</varlistentry>
<varlistentry>
<option>norbind</option> are allowed, controlling whether to create a recursive or a regular bind
mount. Defaults to "rbind". Backslash escapes are interpreted, so <literal>\:</literal> may be used to embed
colons in either path. This option may be specified multiple times for creating multiple independent bind
- mount points. The <option>--bind-ro=</option> option creates read-only bind mounts.</para></listitem>
+ mount points. The <option>--bind-ro=</option> option creates read-only bind mounts.</para>
+
+ <para>Note that when this option is used in combination with <option>--private-users</option>, the resulting
+ mount points will be owned by the <constant>nobody</constant> user. That's because the mount and its files and
+ directories continue to be owned by the relevant host users and groups, which do not exist in the container,
+ and thus show up under the wildcard UID 65534 (nobody). If such bind mounts are created, it is recommended to
+ make them read-only, using <option>--bind-ro=</option>.</para></listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><option>--keep-unit</option></term>
- <listitem><para>Instead of creating a transient scope unit to
- run the container in, simply register the service or scope
- unit <command>systemd-nspawn</command> has been invoked in
- with
- <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
- This has no effect if <option>--register=no</option> is used.
- This switch should be used if
- <command>systemd-nspawn</command> is invoked from within a
- service unit, and the service unit's sole purpose is to run a
- single <command>systemd-nspawn</command> container. This
- option is not available if run from a user
- session.</para>
+ <listitem><para>Instead of creating a transient scope unit to run the container in, simply use the service or
+ scope unit <command>systemd-nspawn</command> has been invoked in. If <option>--register=yes</option> is set
+ this unit is registered with
+ <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
+ switch should be used if <command>systemd-nspawn</command> is invoked from within a service unit, and the
+ service unit's sole purpose is to run a single <command>systemd-nspawn</command> container. This option is not
+ available if run from a user session.</para>
<para>Note that passing <option>--keep-unit</option> disables the effect of <option>--slice=</option> and
- <option>--property=</option>.</para></listitem>
+ <option>--property=</option>. Use <option>--keep-unit</option> and <option>--register=no</option> in
+ combination to disable any kind of unit allocation or registration with
+ <command>systemd-machined</command>.</para></listitem>
</varlistentry>
<varlistentry>
<title>Examples</title>
<example>
- <title>Download a Fedora image and start a shell in it</title>
+ <title>Download a
+ <ulink url="https://getfedora.org">Fedora</ulink> image and start a shell in it</title>
<programlisting># machinectl pull-raw --verify=no \
https://download.fedoraproject.org/pub/fedora/linux/releases/25/CloudImages/x86_64/images/Fedora-Cloud-Base-25-1.3.x86_64.raw.xz
<example>
<title>Build and boot a minimal Fedora distribution in a container</title>
- <programlisting># dnf -y --releasever=25 --installroot=/srv/mycontainer \
+ <programlisting># dnf -y --releasever=27 --installroot=/var/lib/machines/f27container \
--disablerepo='*' --enablerepo=fedora --enablerepo=updates install \
systemd passwd dnf fedora-release vim-minimal
-# systemd-nspawn -bD /srv/mycontainer</programlisting>
+# systemd-nspawn -bD /var/lib/machines/f27container</programlisting>
<para>This installs a minimal Fedora distribution into the
- directory <filename noindex='true'>/srv/mycontainer/</filename>
- and then boots an OS in a namespace container in it.</para>
+ directory <filename noindex='true'>/var/lib/machines/f27container</filename>
+ and then boots an OS in a namespace container in it. Because the installation
+ is located underneath the standard <filename>/var/lib/machines/</filename>
+ directory, it is also possible to start the machine using
+ <command>systemd-nspawn -M f27container</command>.</para>
</example>
<example>
<title>Spawn a shell in a container of a minimal Debian unstable distribution</title>
- <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
+ <programlisting># debootstrap unstable ~/debian-tree/
# systemd-nspawn -D ~/debian-tree/</programlisting>
<para>This installs a minimal Debian unstable distribution into
the directory <filename>~/debian-tree/</filename> and then
spawns a shell in a namespace container in it.</para>
+
+ <para><command>debootstrap</command> supports
+ <ulink url="https://www.debian.org">Debian</ulink>,
+ <ulink url="https://www.ubuntu.com">Ubuntu</ulink>,
+ and <ulink url="https://www.tanglu.org">Tanglu</ulink>
+ out of the box, so the same command can be used to install any of those. For other
+ distributions from the Debian family, a mirror has to be specified, see
+ <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+ </para>
</example>
<example>
- <title>Boot a minimal Arch Linux distribution in a container</title>
+ <title>Boot a minimal
+ <ulink url="https://www.archlinux.org">Arch Linux</ulink> distribution in a container</title>
<programlisting># pacstrap -c -d ~/arch-tree/ base
# systemd-nspawn -bD ~/arch-tree/</programlisting>
</example>
<example>
- <title>Install the OpenSUSE Tumbleweed rolling distribution</title>
+ <title>Install the
+ <ulink url="https://software.opensuse.org/distributions/tumbleweed">OpenSUSE Tumbleweed</ulink>
+ rolling distribution</title>
<programlisting># zypper --root=/var/lib/machines/tumbleweed ar -c \
https://download.opensuse.org/tumbleweed/repo/oss tumbleweed
projects / thirdparty / systemd.git / blobdiff