f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering This file is part of systemd.
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering Copyright 2010 Lennart Poettering
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering systemd is free software; you can redistribute it and/or modify it
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering under the terms of the GNU Lesser General Public License as published by
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering (at your option) any later version.
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering systemd is distributed in the hope that it will be useful, but
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering Lesser General Public License for more details.
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering You should have received a copy of the GNU Lesser General Public License
8f7a3c1402a8de36b2c63935358a53510d2fe7c1Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek xmlns:xi="http://www.w3.org/2001/XInclude">
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>systemd-nspawn</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>systemd-nspawn</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>systemd-nspawn</command>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <arg choice="opt" rep="repeat">OPTIONS</arg>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <arg choice="opt"><replaceable>COMMAND</replaceable>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <arg choice="opt" rep="repeat">ARGS</arg>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>systemd-nspawn</command>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <arg choice="opt" rep="repeat">OPTIONS</arg>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <arg choice="opt" rep="repeat">ARGS</arg>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><command>systemd-nspawn</command> may be used to run a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek command or OS in a light-weight namespace container. In many ways
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek it is similar to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek but more powerful since it fully virtualizes the file system
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek hierarchy, as well as the process tree, the various IPC subsystems
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and the host and domain name.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><command>systemd-nspawn</command> limits access to various
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek kernel interfaces in the container to read-only, such as
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/sys</filename>, <filename>/proc/sys</filename> or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/sys/fs/selinux</filename>. Network interfaces and the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek system clock may not be changed from within the container. Device
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek nodes may not be created. The host system cannot be rebooted and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek kernel modules may not be loaded from within the container.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that even though these security precautions are taken
7de7ee62c5628a3c9e116f14aca63a35d06f5331Lennart Poettering <command>systemd-nspawn</command> is not suitable for fully secure
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container setups. Many of the security features may be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek circumvented and are hence primarily useful to avoid accidental
7de7ee62c5628a3c9e116f14aca63a35d06f5331Lennart Poettering changes to the host system from the container.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>In contrast to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek may be used to boot full Linux-based operating systems in a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Use a tool like
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to set up an OS directory tree suitable as file system hierarchy
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek for <command>systemd-nspawn</command> containers.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that <command>systemd-nspawn</command> will mount file
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek systems private to the container to <filename>/dev</filename>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/run</filename> and similar. These will not be visible
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek outside of the container, and their contents will be lost when the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container exits.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that running two <command>systemd-nspawn</command>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek containers from the same directory tree will not make processes in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek them see each other. The PID namespace separation of the two
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek containers is complete and the containers will share very few
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek runtime objects except for the underlying file system. Use
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>login</command> command to request an additional login
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek prompt in a running container.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><command>systemd-nspawn</command> implements the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Interface</ulink> specification.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>As a safety check <command>systemd-nspawn</command> will
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek verify the existence of <filename>/usr/lib/os-release</filename>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek or <filename>/etc/os-release</filename> in the container tree
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek before starting the container (see
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek It might be necessary to add this file to the container tree
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek manually if the OS of the container is too old to contain this
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek file out-of-the-box.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>If option <option>-b</option> is specified, the arguments
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek are used as arguments for the init binary. Otherwise,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <replaceable>COMMAND</replaceable> specifies the program to launch
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek in the container, and the remaining arguments are used as
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek arguments for this program. If <option>-b</option> is not used and
ff9b60f38bf68eba4a47cabff14547d92e083214Torstein Husebø no arguments are specified, a shell is launched in the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The following options are understood:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-D</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--directory=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Directory to use as file system root for the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>If neither <option>--directory=</option>, nor
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--image=</option> is specified the directory is
32b64cce23cd7fb35900a0613a1162e639f0c59cRichard Maw determined by searching for a directory named the same as the
32b64cce23cd7fb35900a0613a1162e639f0c59cRichard Maw machine name specified with <option>--machine=</option>. See
32b64cce23cd7fb35900a0613a1162e639f0c59cRichard Maw <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
32b64cce23cd7fb35900a0613a1162e639f0c59cRichard Maw section "Files and Directories" for the precise search path.</para>
32b64cce23cd7fb35900a0613a1162e639f0c59cRichard Maw <option>--image=</option>, nor <option>--machine=</option>
32b64cce23cd7fb35900a0613a1162e639f0c59cRichard Maw are specified, the current directory will
32b64cce23cd7fb35900a0613a1162e639f0c59cRichard Maw be used. May not be specified together with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--image=</option>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--template=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Directory or <literal>btrfs</literal>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek subvolume to use as template for the container's root
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek directory. If this is specified and the container's root
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek directory (as configured by <option>--directory=</option>)
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek does not yet exist it is created as <literal>btrfs</literal>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek subvolume and populated from this template tree. Ideally, the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specified template path refers to the root of a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>btrfs</literal> subvolume, in which case a simple
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek copy-on-write snapshot is taken, and populating the root
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek directory is instant. If the specified template path does not
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek refer to the root of a <literal>btrfs</literal> subvolume (or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek not even to a <literal>btrfs</literal> file system at all),
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the tree is copied, which can be substantially more
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek time-consuming. Note that if this option is used the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container's root directory (in contrast to the template
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek directory!) must be located on a <literal>btrfs</literal> file
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek system, so that the <literal>btrfs</literal> subvolume may be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek created. May not be specified together with
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering <para>Note that this switch leaves host name, machine ID and
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering all other settings that could identify the instance
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-x</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--ephemeral</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>If specified, the container is run with a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek temporary <literal>btrfs</literal> snapshot of its root
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek directory (as configured with <option>--directory=</option>),
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek that is removed immediately when the container terminates.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek This option is only supported if the root file system is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>btrfs</literal>. May not be specified together with
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering <para>Note that this switch leaves host name, machine ID and
3fe22bb4b6b5faf27683ad2e231b5a69b6e63a9eLennart Poettering all other settings that could identify the instance
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-i</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--image=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Disk image to mount the root directory for the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container from. Takes a path to a regular file or to a block
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek device node. The file or block device must contain
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>An MBR partition table with a single
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek partition of type 0x83 that is marked
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>A GUID partition table (GPT) with a single
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek partition of type
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek 0fc63daf-8483-4772-8e79-3d69d8477de4.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>A GUID partition table (GPT) with a marked
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek root partition which is mounted as the root directory of the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container. Optionally, GPT images may contain a home and/or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek a server data partition which are mounted to the appropriate
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek places in the container. All these partitions must be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek identified by the partition types defined by the <ulink
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Partitions Specification</ulink>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Any other partitions, such as foreign partitions, swap
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek partitions or EFI system partitions are not mounted. May not
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek be specified together with <option>--directory=</option>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--ephemeral</option>.</para></listitem>
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <varlistentry>
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <listitem><para>Invoke the shell or specified program as process ID (PID) 2 instead of PID 1 (init). By
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering default, if neither this option nor <option>--boot</option> is used, the selected binary is run as process with
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering PID 1, a mode only suitable for programs that are aware of the special semantics that the process with PID 1
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering has on UNIX. For example, it needs to reap all processes reparented to it, and should implement
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <command>sysvinit</command> compatible signal handling (specifically: it needs to reboot on SIGINT, reexecute
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering on SIGTERM, reload configuration on SIGHUP, and so on). With <option>--as-pid2</option> a minimal stub init
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering process is run as PID 1 and the selected binary is executed as PID 2 (and hence does not need to implement any
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering special semantics). The stub init process will reap processes as necessary and react appropriately to
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering signals. It is recommended to use this mode to invoke arbitrary commands in containers, unless they have been
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering modified to run correctly as PID 1. Or in other words: this switch should be used for pretty much all commands,
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering except when the command refers to an init or shell implementation, as these are generally capable of running
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering correctly as PID 1). This option may not be combined with <option>--boot</option> or
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-b</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--boot</option></term>
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <listitem><para>Automatically search for an init binary and invoke it as PID 1, instead of a shell or a user
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering supplied program. If this option is used, arguments specified on the command line are used as arguments for the
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering init binary. This option may not be combined with <option>--as-pid2</option> or
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <para>The following table explains the different modes of invocation and relationship to
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <option>--as-pid2</option> (see above):</para>
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <tgroup cols='2' align='left' colsep='1' rowsep='1'>
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <entry>Neither <option>--as-pid2</option> nor <option>--boot</option> specified</entry>
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <entry>The passed parameters are interpreted as command line, which is executed as PID 1 in the container.</entry>
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <entry><option>--as-pid2</option> specified</entry>
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <entry>The passed parameters are interpreted as command line, which are executed as PID 2 in the container. A stub init process is run as PID 1.</entry>
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <entry><option>--boot</option> specified</entry>
7732f92bad5f24a4bd03bb357af46da56b0ac94dLennart Poettering <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>
5f932eb9af7a5e4723855bcd776c2acaa2a31932Lennart Poettering <varlistentry>
5f932eb9af7a5e4723855bcd776c2acaa2a31932Lennart Poettering <listitem><para>Change to the specified working directory before invoking the process in the container. Expects
5f932eb9af7a5e4723855bcd776c2acaa2a31932Lennart Poettering an absolute path in the container's file system namespace.</para></listitem>
5f932eb9af7a5e4723855bcd776c2acaa2a31932Lennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-u</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--user=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>After transitioning into the container, change
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to the specified user-defined in the container's user
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek database. Like all other systemd-nspawn features, this is not
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek a security feature and provides protection against accidental
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek destructive operations only.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-M</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--machine=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Sets the machine name for this container. This
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek name may be used to identify this container during its runtime
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek (for example in tools like
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and similar), and is used to initialize the container's
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek hostname (which the container can choose to override,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek however). If not specified, the last component of the root
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek directory path of the container is used, possibly suffixed
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek with a random identifier in case <option>--ephemeral</option>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek mode is selected. If the root directory selected is the host's
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek root directory the host's hostname is used as default
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--uuid=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Set the specified UUID for the container. The
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek init system will initialize
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/etc/machine-id</filename> from this if this file is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--slice=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Make the container part of the specified
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek slice, instead of the default
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering <filename>machine.slice</filename>. This is only applies if
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering the machine is run in its own scope unit, i.e. if
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering <option>--keep-unit</option> is not used.</para>
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering </varlistentry>
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering <varlistentry>
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering <term><option>--property=</option></term>
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering <listitem><para>Set a unit property on the scope unit to
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering register for the machine. This only applies if the machine is
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering run in its own scope unit, i.e. if
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering <option>--keep-unit</option> is not used. Takes unit property
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering assignments in the same format as <command>systemctl
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering set-property</command>. This is useful to set memory limits
f36933fef605a7dccce8e3aecccff5152e522fa6Lennart Poettering and similar for machines.</para>
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering <varlistentry>
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering <term><option>--private-users=</option></term>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <listitem><para>Enables user namespacing. If enabled, the
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering container will run with its own private set of Unix user and
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering group ids (UIDs and GIDs). Takes none, one or two
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering colon-separated parameters: the first parameter specifies the
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering first host UID to assign to the container, the second
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering parameter specifies the number of host UIDs to assign to the
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering container. If the second parameter is omitted, 65536 UIDs are
7c918141edad0063a82411e0f9637e72a8aba223Jonathan Boulle assigned. If the first parameter is also omitted (and hence
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering no parameter passed at all), the first UID assigned to the
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering container is read from the owner of the root directory of the
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt container's directory tree. By default, no user namespacing is
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering applied.</para>
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering <para>Note that user namespacing currently requires OS trees
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering that are prepared for the UID shift that is being applied:
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering UIDs and GIDs used for file ownership or in file ACL entries
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering must be shifted to the container UID base that is
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering used during container runtime.</para>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <para>It is recommended to assign at least 65536 UIDs to each
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering container, so that the usable UID range in the container
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt covers 16 bit. For best security, do not assign overlapping UID
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering ranges to multiple containers. It is hence a good idea to use
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt the upper 16 bit of the host 32-bit UIDs as container
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt identifier, while the lower 16 bit encode the container UID
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>When user namespaces are used, the GID range assigned to
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering each container is always chosen identical to the UID
03cfe0d51499e86b1573d121337594719d9f2012Lennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--private-network</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Disconnect networking of the container from
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the host. This makes all network interfaces unavailable in the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container, with the exception of the loopback device and those
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specified with <option>--network-interface=</option> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek configured with <option>--network-veth</option>. If this
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek option is specified, the CAP_NET_ADMIN capability will be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek added to the set of capabilities the container retains. The
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek latter may be disabled by using
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--drop-capability=</option>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--network-interface=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Assign the specified network interface to the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container. This will remove the specified interface from the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek calling namespace and place it in the container. When the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container terminates, it is moved back to the host namespace.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Note that <option>--network-interface=</option> implies
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--private-network</option>. This option may be used
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek more than once to add multiple network interfaces to the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--network-macvlan=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Create a <literal>macvlan</literal> interface
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek of the specified Ethernet network interface and add it to the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container. A <literal>macvlan</literal> interface is a virtual
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek interface that adds a second MAC address to an existing
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek physical Ethernet link. The interface in the container will be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek named after the interface on the host, prefixed with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>mv-</literal>. Note that
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--network-macvlan=</option> implies
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--private-network</option>. This option may be used
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek more than once to add multiple network interfaces to the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--network-ipvlan=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Create an <literal>ipvlan</literal> interface
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek of the specified Ethernet network interface and add it to the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container. An <literal>ipvlan</literal> interface is a virtual
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek interface, similar to a <literal>macvlan</literal> interface,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek which uses the same MAC address as the underlying interface.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek The interface in the container will be named after the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek interface on the host, prefixed with <literal>iv-</literal>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Note that <option>--network-ipvlan=</option> implies
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--private-network</option>. This option may be used
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek more than once to add multiple network interfaces to the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-n</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--network-veth</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Create a virtual Ethernet link
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek (<literal>veth</literal>) between host and container. The host
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek side of the Ethernet link will be available as a network
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek interface named after the container's name (as specified with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--machine=</option>), prefixed with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>ve-</literal>. The container side of the Ethernet
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek link will be named <literal>host0</literal>. Note that
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--network-veth</option> implies
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--private-network</option>.</para></listitem>
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering <varlistentry>
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering <term><option>--network-veth-extra=</option></term>
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering <listitem><para>Adds an additional virtual Ethernet link
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering between host and container. Takes a colon-separated pair of
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering host interface name and container interface name. The latter
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering may be omitted in which case the container and host sides will
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering be assigned the same name. This switch is independent of
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering <option>--network-veth</option>, and -- in contrast -- may be
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering used multiple times, and allows configuration of the network
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering interface names. Note that <option>--network-bridge=</option>
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering has no effect on interfaces created with
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering <option>--network-veth-extra=</option>.</para></listitem>
f6d6bad1461a8f545a80955fadd7ee0c10db15bbLennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--network-bridge=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Adds the host side of the Ethernet link
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek created with <option>--network-veth</option> to the specified
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek bridge. Note that <option>--network-bridge=</option> implies
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--network-veth</option>. If this option is used, the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek host side of the Ethernet link will use the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>vb-</literal> prefix instead of
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>ve-</literal>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-p</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--port=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>If private networking is enabled, maps an IP
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek port on the host onto an IP port on the container. Takes a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek protocol specifier (either <literal>tcp</literal> or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>udp</literal>), separated by a colon from a host port
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek number in the range 1 to 65535, separated by a colon from a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container port number in the range from 1 to 65535. The
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek protocol specifier and its separating colon may be omitted, in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek which case <literal>tcp</literal> is assumed. The container
7c918141edad0063a82411e0f9637e72a8aba223Jonathan Boulle port number and its colon may be omitted, in which case the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek same port as the host port is implied. This option is only
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt supported if private networking is used, such as with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--network-veth</option> or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--network-bridge=</option>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-Z</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--selinux-context=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Sets the SELinux security context to be used
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to label processes in the container.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-L</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--selinux-apifs-context=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Sets the SELinux security context to be used
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to label files in the virtual API file systems in the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--capability=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>List one or more additional capabilities to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek grant the container. Takes a comma-separated list of
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek capability names, see
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek for more information. Note that the following capabilities
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek will be granted in any way: CAP_CHOWN, CAP_DAC_OVERRIDE,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek CAP_KILL, CAP_LEASE, CAP_LINUX_IMMUTABLE,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_RAW,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, CAP_SETUID,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek CAP_SYS_ADMIN, CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek CAP_SYS_TTY_CONFIG, CAP_SYS_RESOURCE, CAP_SYS_BOOT,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek CAP_AUDIT_WRITE, CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek retained if <option>--private-network</option> is specified.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek If the special value <literal>all</literal> is passed, all
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek capabilities are retained.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--drop-capability=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Specify one or more additional capabilities to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek drop for the container. This allows running the container with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek fewer capabilities than the default (see
c6c8f6e218995852350e5e35c080dec788c42c3fLennart Poettering <varlistentry>
c6c8f6e218995852350e5e35c080dec788c42c3fLennart Poettering <term><option>--kill-signal=</option></term>
c6c8f6e218995852350e5e35c080dec788c42c3fLennart Poettering <listitem><para>Specify the process signal to send to the
c6c8f6e218995852350e5e35c080dec788c42c3fLennart Poettering container's PID 1 when nspawn itself receives SIGTERM, in
c6c8f6e218995852350e5e35c080dec788c42c3fLennart Poettering order to trigger an orderly shutdown of the
c6c8f6e218995852350e5e35c080dec788c42c3fLennart Poettering container. Defaults to SIGRTMIN+3 if <option>--boot</option>
c6c8f6e218995852350e5e35c080dec788c42c3fLennart Poettering is used (on systemd-compatible init systems SIGRTMIN+3
c6c8f6e218995852350e5e35c080dec788c42c3fLennart Poettering triggers an orderly shutdown). Takes a signal name like
c6c8f6e218995852350e5e35c080dec788c42c3fLennart Poettering <literal>SIGHUP</literal>, <literal>SIGTERM</literal> or
c6c8f6e218995852350e5e35c080dec788c42c3fLennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--link-journal=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Control whether the container's journal shall
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek be made visible to the host system. If enabled, allows viewing
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the container's journal files from the host (but not vice
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek versa). Takes one of <literal>no</literal>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>host</literal>, <literal>try-host</literal>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>guest</literal>, <literal>try-guest</literal>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>auto</literal>. If <literal>no</literal>, the journal
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is not linked. If <literal>host</literal>, the journal files
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek are stored on the host file system (beneath
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and the subdirectory is bind-mounted into the container at the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek same location. If <literal>guest</literal>, the journal files
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek are stored on the guest file system (beneath
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>)
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and the subdirectory is symlinked into the host at the same
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek location. <literal>try-host</literal> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>try-guest</literal> do the same but do not fail if
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the host does not have persistent journalling enabled. If
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>auto</literal> (the default), and the right
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek subdirectory of <filename>/var/log/journal</filename> exists,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek it will be bind mounted into the container. If the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek subdirectory does not exist, no linking is performed.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Effectively, booting a container once with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>guest</literal> or <literal>host</literal> will link
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the journal persistently if further on the default of
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>auto</literal> is used.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-j</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--link-journal=try-guest</option>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--read-only</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Mount the root file system read-only for the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--bind=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--bind-ro=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Bind mount a file or directory from the host
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt into the container. Takes one of: a path argument — in which
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek case the specified path will be mounted from the host to the
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt same path in the container —, or a colon-separated pair of
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt paths — in which case the first specified path is the source
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek in the host, and the second path is the destination in the
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt container —, or a colon-separated triple of source path,
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt destination path and mount options. Mount options are
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt comma-separated and currently, only "rbind" and "norbind"
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt are allowed. Defaults to "rbind". Backslash escapes are interpreted, so
8ef24e7a4f4b4d464b66fa7d3f0acaa88800d6cbRichard Maw <literal>\:</literal> may be used to embed colons in either path.
8ef24e7a4f4b4d464b66fa7d3f0acaa88800d6cbRichard Maw This option may be specified multiple times for
64b282ef715bcc6f7896cc49a4a36db12ca35bbcLennart Poettering creating multiple independent bind mount points. The
64b282ef715bcc6f7896cc49a4a36db12ca35bbcLennart Poettering <option>--bind-ro=</option> option creates read-only bind
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--tmpfs=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Mount a tmpfs file system into the container.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Takes a single absolute path argument that specifies where to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek mount the tmpfs instance to (in which case the directory
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek access mode will be chosen as 0755, owned by root/root), or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek optionally a colon-separated pair of path and mount option
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt string that is used for mounting (in which case the kernel
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek default for access mode and owner will be chosen, unless
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek otherwise specified). This option is particularly useful for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek mounting directories such as <filename>/var</filename> as
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek tmpfs, to allow state-less systems, in particular when
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt Backslash escapes are interpreted in the path, so
ffcd3e89d55c870c94aa15ee94dab3e029a586cfRichard Maw <literal>\:</literal> may be used to embed colons in the path.
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering <varlistentry>
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering <term><option>--overlay-ro=</option></term>
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering <listitem><para>Combine multiple directory trees into one
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering overlay file system and mount it into the container. Takes a
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering list of colon-separated paths to the directory trees to
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering combine and the destination mount point.</para>
2eadf91ca15a982adf71b86e6ee035ac368e74bcRichard Maw <para>Backslash escapes are interpreted in the paths, so
2eadf91ca15a982adf71b86e6ee035ac368e74bcRichard Maw <literal>\:</literal> may be used to embed colons in the paths.
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering <para>If three or more paths are specified, then the last
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering specified path is the destination mount point in the
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering container, all paths specified before refer to directory trees
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering on the host and are combined in the specified order into one
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering overlay file system. The left-most path is hence the lowest
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering directory tree, the second-to-last path the highest directory
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering tree in the stacking order. If <option>--overlay-ro=</option>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt is used instead of <option>--overlay=</option>, a read-only
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering overlay file system is created. If a writable overlay file
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt system is created, all changes made to it are written to the
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering highest directory tree in the stacking order, i.e. the
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering second-to-last specified.</para>
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering <para>If only two paths are specified, then the second
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering specified path is used both as the top-level directory tree in
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering the stacking order as seen from the host, as well as the mount
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering point for the overlay file system in the container. At least
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering two paths have to be specified.</para>
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering <para>For details about overlay file systems, see <ulink
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering url="https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt">overlayfs.txt</ulink>. Note
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering that the semantics of overlay file systems are substantially
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering different from normal file systems, in particular regarding
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering reported device and inode information. Device and inode
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering information may change for a file while it is being written
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering to, and processes might see out-of-date versions of files at
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering times. Note that this switch automatically derives the
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering <literal>workdir=</literal> mount option for the overlay file
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering system from the top-level directory tree, making it a sibling
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering of it. It is hence essential that the top-level directory tree
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering is not a mount point itself (since the working directory must
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering be on the same file system as the top-most directory
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering tree). Also note that the <literal>lowerdir=</literal> mount
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering option receives the paths to stack in the opposite order of
5a8af538aee99741ab492506b4284fdd26b597d1Lennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--setenv=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Specifies an environment variable assignment
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to pass to the init process in the container, in the format
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>NAME=VALUE</literal>. This may be used to override
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the default variables or to set additional variables. This
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek parameter may be used more than once.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--share-system</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Allows the container to share certain system
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek facilities with the host. More specifically, this turns off
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek PID namespacing, UTS namespacing and IPC namespacing, and thus
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek allows the guest to see and interact more easily with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek processes outside of the container. Note that using this
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek option makes it impossible to start up a full Operating System
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek in the container, as an init system cannot operate in this
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek mode. It is only useful to run specific programs or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek applications this way, without involving an init system in the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek container. This option implies <option>--register=no</option>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek This option may not be combined with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--boot</option>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--register=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Controls whether the container is registered
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt Takes a boolean argument, which defaults to <literal>yes</literal>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek This option should be enabled when the container runs a full
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Operating System (more specifically: an init system), and is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek useful to ensure that the container is accessible via
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and shown by tools such as
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek If the container does not run an init system, it is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek recommended to set this option to <literal>no</literal>. Note
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek that <option>--share-system</option> implies
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <option>--register=no</option>. </para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--keep-unit</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Instead of creating a transient scope unit to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek run the container in, simply register the service or scope
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek unit <command>systemd-nspawn</command> has been invoked in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek This has no effect if <option>--register=no</option> is used.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek This switch should be used if
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <command>systemd-nspawn</command> is invoked from within a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek service unit, and the service unit's sole purpose is to run a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek single <command>systemd-nspawn</command> container. This
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek option is not available if run from a user
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--personality=</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Control the architecture ("personality")
3ba3a79df4ae094d1008c04a9af8d1ff970124c4Zbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek in the container. Currently, only <literal>x86</literal> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>x86-64</literal> are supported. This is useful when
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek running a 32-bit container on a 64-bit host. If this setting
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is not used, the personality reported in the container is the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek same as the one reported on the host.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>-q</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><option>--quiet</option></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Turns off any status output by the tool
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek itself. When this switch is used, the only output from nspawn
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek will be the console output of the container OS
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <term><option>--volatile=</option><replaceable>MODE</replaceable></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Boots the container in volatile mode. When no
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek mode parameter is passed or when mode is specified as
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <option>yes</option>, full volatile mode is enabled. This
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt means the root directory is mounted as a mostly unpopulated
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>tmpfs</literal> instance, and
cd72d2044ad28b475bf84a38ba6db45292467dd8Jan Engelhardt <filename>/usr</filename> from the OS tree is mounted into it
cd72d2044ad28b475bf84a38ba6db45292467dd8Jan Engelhardt in read-only mode (the system thus starts up with read-only OS
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek resources, but pristine state and configuration, any changes
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to the either are lost on shutdown). When the mode parameter
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt is specified as <option>state</option>, the OS tree is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek mounted read-only, but <filename>/var</filename> is mounted as
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt a <literal>tmpfs</literal> instance into it (the system thus
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek starts up with read-only OS resources and configuration, but
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt pristine state, and any changes to the latter are lost on
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek shutdown). When the mode parameter is specified as
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <option>no</option> (the default), the whole OS tree is made
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek available writable.</para>
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <para>Note that setting this to <option>yes</option> or
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <option>state</option> will only work correctly with
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek operating systems in the container that can boot up with only
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/usr</filename> mounted, and are able to populate
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/var</filename> automatically, as
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <varlistentry>
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <term><option>--settings=</option><replaceable>MODE</replaceable></term>
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <command>systemd-nspawn</command> shall search for and use
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering additional per-container settings from
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <filename>.nspawn</filename> files. Takes a boolean or the
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering special values <option>override</option> or
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>If enabled (the default), a settings file named after the
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering machine (as specified with the <option>--machine=</option>
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering setting, or derived from the directory or image file name)
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering with the suffix <filename>.nspawn</filename> is searched in
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <filename>/etc/systemd/nspawn/</filename> and
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <filename>/run/systemd/nspawn/</filename>. If it is found
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering there, its settings are read and used. If it is not found
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt there, it is subsequently searched in the same directory as the
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering image file or in the immediate parent of the root directory of
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt the container. In this case, if the file is found, its settings
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering will be also read and used, but potentially unsafe settings
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt are ignored. Note that in both these cases, settings on the
4f76ef0423a30ee672891056aeb5df2422947e1dThomas Hindoe Paaboel Andersen command line take precedence over the corresponding settings
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering from loaded <filename>.nspawn</filename> files, if both are
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering specified. Unsafe settings are considered all settings that
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering elevate the container's privileges or grant access to
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering additional resources such as files or directories of the
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering host. For details about the format and contents of
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>If this option is set to <option>override</option>, the
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt file is searched, read and used the same way, however, the order of
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering precedence is reversed: settings read from the
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <filename>.nspawn</filename> file will take precedence over
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering the corresponding command line options, if both are
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering specified.</para>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>If this option is set to <option>trusted</option>, the
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering file is searched, read and used the same way, but regardless
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt of being found in <filename>/etc/systemd/nspawn/</filename>,
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <filename>/run/systemd/nspawn/</filename> or next to the image
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering file or container root directory, all settings will take
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt effect, however, command line arguments still take precedence
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering over corresponding settings.</para>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>If disabled, no <filename>.nspawn</filename> file is read
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering and no settings except the ones on the command line are in
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering </varlistentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="standard-options.xml" xpointer="help" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="standard-options.xml" xpointer="version" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Download a Fedora image and start a shell in it</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz
e0ea94c1e2ab3930c85c6057189a2a829a13a800Lennart Poettering# systemd-nspawn -M Fedora-Cloud-Base-20141203-21</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This downloads an image using
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and opens a shell in it.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Build and boot a minimal Fedora distribution in a container</title>
09c76ef618de6d3a095164910ec3c96ec89e4cbcLennart Poettering <programlisting># dnf -y --releasever=23 --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora --enablerepo=updates install systemd passwd dnf fedora-release vim-minimal
2b3987a863975f5a1fa1754725e3d07a5d4f6478Lennart Poettering# systemd-nspawn -bD /srv/mycontainer</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This installs a minimal Fedora distribution into the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek directory <filename noindex='true'>/srv/mycontainer/</filename>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and then boots an OS in a namespace container in it.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Spawn a shell in a container of a minimal Debian unstable distribution</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
25f5971b5e0b3ab5b91a7d0359cd7f5a5094c1d0Lennart Poettering# systemd-nspawn -D ~/debian-tree/</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This installs a minimal Debian unstable distribution into
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the directory <filename>~/debian-tree/</filename> and then
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek spawns a shell in a namespace container in it.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Boot a minimal Arch Linux distribution in a container</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting># pacstrap -c -d ~/arch-tree/ base
68562936c243a2e2190a7232c4805ffd094e9b3bWilliam Giokas# systemd-nspawn -bD ~/arch-tree/</programlisting>
ff9b60f38bf68eba4a47cabff14547d92e083214Torstein Husebø <para>This installs a minimal Arch Linux distribution into the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek directory <filename>~/arch-tree/</filename> and then boots an OS
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek in a namespace container in it.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting># systemd-nspawn -D / -xb</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This runs a copy of the host system in a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>btrfs</literal> snapshot which is removed immediately
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek when the container exits. All file system changes made during
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek runtime will be lost on shutdown, hence.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Run a container with SELinux sandbox security contexts</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
a8828ed93878b4b4866d40ebfb660e54995ff72eDaniel J Walsh# systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The exit code of the program executed in the container is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek returned.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
f757855e81fc0bc116de372220096e532afb5cb8Lennart Poettering <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
3ba3a79df4ae094d1008c04a9af8d1ff970124c4Zbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>