HALF ECHO LEARN / REFERENCE COLLECTION
v262.2man/systemd-nspawn.xml
Git blob: 58d4c84b36c153168ad93674304585d3acdb4455
Lines 2001–2180 of 2,180
<variablelist>
<varlistentry>
<term><option>--system</option></term>
<term><option>--user</option></term>
<listitem><para>Specify whether to run in system or user scope. This controls which service manager and
machined instance to interact with, as well as operational defaults such as user namespace mode and
private networking. If neither is specified, <option>--system</option> is implied when running as
root, <option>--user</option> otherwise.</para>
<para>Note: for backwards compatibility, <option>--user</option> followed by a positional argument
is interpreted as the deprecated <option>--user=<replaceable>NAME</replaceable></option> form (now
<option>--uid=</option>). To use <option>--user</option> for scope selection when positional
arguments follow, separate them with <literal>--</literal>.</para>
<xi:include href="version-info.xml" xpointer="v261"/></listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="no-pager" />
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
<xi:include href="standard-options.xml" xpointer="no-ask-password" />
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>Hotkeys</title>
<para>When invoked in interactive mode (i.e. the default <option>--console=interactive</option>), a few
special keyboard shortcuts are understood that control the container runtime. These shortcuts need to be
typed within 1s to have effect, otherwise they will be forwarded to the container as regular
keypresses.</para>
<variablelist>
<varlistentry>
<term>Ctrl-] Ctrl-] Ctrl-]</term>
<listitem><para>Immediately terminate the container, killing all processes.</para></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-] Ctrl-] r</term>
<listitem><para>Issue a reboot request to the container.</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
<varlistentry>
<term>Ctrl-] Ctrl-] p</term>
<listitem><para>Issue a shutdown request to the container.</para>
<xi:include href="version-info.xml" xpointer="v258"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="common-variables.xml" />
<refsect1>
<title>Examples</title>
<xi:include href="importctl.xml" xpointer="example-import-tar" />
<example>
<title>Build and boot a minimal Fedora distribution in a container</title>
<programlisting># dnf -y --releasever=&fedora_latest_version; --installroot=/var/lib/machines/f&fedora_latest_version; \
--use-host-config --setopt=install_weak_deps=0 \
--repo=fedora --repo=updates install \
passwd dnf fedora-release nano util-linux systemd systemd-networkd
# systemd-nspawn -bD /var/lib/machines/f&fedora_latest_version;</programlisting>
<para>(Omit <parameter>--use-host-config</parameter> when using <command>dnf</command> <= 4.)
This installs a minimal Fedora distribution into the directory
<filename index="false">/var/lib/machines/f&fedora_latest_version;</filename>
and then boots that OS in a namespace container. 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 f&fedora_latest_version;</command>.</para>
</example>
<example>
<title>Spawn a shell in a container of a minimal Debian unstable distribution</title>
<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 from this image in a namespace container.</para>
<para><command>debootstrap</command> supports
<ulink url="https://www.debian.org">Debian</ulink>,
and <ulink url="https://www.ubuntu.com">Ubuntu</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
<ulink url="https://www.archlinux.org">Arch Linux</ulink> distribution in a container</title>
<programlisting># pacstrap -c ~/arch-tree/ base
# systemd-nspawn -bD ~/arch-tree/</programlisting>
<para>This installs a minimal Arch Linux distribution into the
directory <filename>~/arch-tree/</filename> and then boots an OS
in a namespace container in it.</para>
</example>
<example>
<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
# zypper --root=/var/lib/machines/tumbleweed refresh
# zypper --root=/var/lib/machines/tumbleweed install --no-recommends \
systemd shadow zypper openSUSE-release vim
# systemd-nspawn -M tumbleweed passwd root
# systemd-nspawn -M tumbleweed -b</programlisting>
</example>
<example>
<title>Boot into an ephemeral snapshot of the host system</title>
<programlisting># systemd-nspawn -D / -xb</programlisting>
<para>This runs a copy of the host system in a snapshot which is removed immediately when the container
exits. All file system changes made during runtime will be lost on shutdown, hence.</para>
</example>
<example>
<title>Run a container with SELinux sandbox security contexts</title>
<programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container
# 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>
</example>
<example>
<title>Run a container with an OSTree deployment</title>
<programlisting># systemd-nspawn -b -i ~/image.raw \
--pivot-root=/ostree/deploy/$OS/deploy/$CHECKSUM:/sysroot \
--bind=+/sysroot/ostree/deploy/$OS/var:/var</programlisting>
</example>
</refsect1>
<refsect1>
<title>Exit status</title>
<para>The exit code of the program executed in the container is
returned.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry project='mankier'><refentrytitle>zypper</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-mountfsd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-nsresourced.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.mstack</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry project='url'><refentrytitle url='https://btrfs.readthedocs.io/en/latest/btrfs.html'>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>