diff options
Diffstat (limited to 'man/systemd-nspawn.xml')
| -rw-r--r-- | man/systemd-nspawn.xml | 331 |
1 files changed, 331 insertions, 0 deletions
diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml new file mode 100644 index 0000000000..fef5c2c83a --- /dev/null +++ b/man/systemd-nspawn.xml @@ -0,0 +1,331 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd-nspawn"> + + <refentryinfo> + <title>systemd-nspawn</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-nspawn</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-nspawn</refname> + <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-nspawn <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">COMMAND</arg> <arg choice="opt" rep="repeat">ARGS</arg></command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-nspawn</command> may be used to + run a command or OS in a light-weight namespace + container. In many ways it is similar to + <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + but more powerful since it fully virtualizes the file + system hierarchy, as well as the process tree, the + various IPC subsystems and the host and domain + name.</para> + + <para><command>systemd-nspawn</command> limits access + to various kernel interfaces in the container to + read-only, such as <filename>/sys</filename>, + <filename>/proc/sys</filename> or + <filename>/sys/fs/selinux</filename>. Network + interfaces and the system clock may not be changed + from within the container. Device nodes may not be + created. The host system cannot be rebooted and kernel + modules may not be loaded from within the + container.</para> + + <para>Note that even though these security precautions + are taken <command>systemd-nspawn</command> is not + suitable for secure container setups. Many of the + security features may be circumvented and are hence + primarily useful to avoid accidental changes to the + host system from the container. The intended use of + this program is debugging and testing as well as + building of packages, distributions and software + involved with boot and systems management.</para> + + <para>In contrast to + <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <command>systemd-nspawn</command> may be used to boot + full Linux-based operating systems in a + container.</para> + + <para>Use a tool like + <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry> + or + <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry> + to set up an OS directory tree suitable as file system + hierarchy for <command>systemd-nspawn</command> + containers.</para> + + <para>Note that <command>systemd-nspawn</command> will + mount file systems private to the container to + <filename>/dev</filename>, + <filename>/run</filename> and similar. These will + not be visible outside of the container, and their + contents will be lost when the container exits.</para> + + <para>Note that running two + <command>systemd-nspawn</command> containers from the + same directory tree will not make processes in them + see each other. The PID namespace separation of the + two containers is complete and the containers will + share very few runtime objects except for the + underlying file system.</para> + + <para><command>systemd-nspawn</command> implements the + <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container + Interface</ulink> specification.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>If no arguments are passed the container is set + up and a shell started in it, otherwise the passed + command and arguments are executed in it. The + following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--help</option></term> + <term><option>-h</option></term> + + <listitem><para>Prints a short help + text and exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--directory=</option></term> + <term><option>-D</option></term> + + <listitem><para>Directory to use as + file system root for the namespace + container. If omitted the current + directory will be + used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--boot</option></term> + <term><option>-b</option></term> + + <listitem><para>Automatically search + for an init binary and invoke it + instead of a shell or a user supplied + program.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--user=</option></term> + <term><option>-u</option></term> + + <listitem><para>Run the command + under specified user, create home + directory and cd into it. As rest + of systemd-nspawn, this is not + the security feature and limits + against accidental changes only. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--uuid=</option></term> + + <listitem><para>Set the specified uuid + for the container. The init system + will initialize + <filename>/etc/machine-id</filename> + from this if this file is not set yet. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--controllers=</option></term> + <term><option>-C</option></term> + + <listitem><para>Makes the container appear in + other hierarchies than the name=systemd:/ one. + Takes a comma-separated list of controllers. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--private-network</option></term> + + <listitem><para>Turn off networking in + the container. This makes all network + interfaces unavailable in the + container, with the exception of the + loopback device.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--read-only</option></term> + + <listitem><para>Mount the root file + system read only for the + container.</para></listitem> + </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 + <citerefentry><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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--link-journal=</option></term> + + <listitem><para>Control whether the + container's journal shall be made + visible to the host system. If enabled + allows viewing the container's journal + files from the host (but not vice + versa). Takes one of + <literal>no</literal>, + <literal>host</literal>, + <literal>guest</literal>, + <literal>auto</literal>. If + <literal>no</literal>, the journal is + not linked. If <literal>host</literal>, + the journal files are stored on the + host file system (beneath + <filename>/var/log/journal/<machine-id></filename>) + and the subdirectory is bind-mounted + into the container at the same + location. If <literal>guest</literal>, + the journal files are stored on the + guest file system (beneath + <filename>/var/log/journal/<machine-id></filename>) + and the subdirectory is symlinked into the host + at the same location. If + <literal>auto</literal> (the default), + and the right subdirectory of + <filename>/var/log/journal</filename> + exists, it will be bind mounted + into the container. If the + subdirectory doesn't exist, no + linking is performed. Effectively, + booting a container once with + <literal>guest</literal> or + <literal>host</literal> will link the + journal persistently if further on + the default of <literal>auto</literal> + is used.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-j</option></term> + + <listitem><para>Equivalent to + <option>--link-journal=guest</option>.</para></listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Example 1</title> + + <programlisting># yum --releasever=17 --nogpgcheck --installroot ~/fedora-tree/ install yum passwd vim-minimal rootfiles systemd +# systemd-nspawn -D ~/fedora-tree /usr/lib/systemd/systemd</programlisting> + + <para>This installs a minimal Fedora distribution into + the directory <filename>~/fedora-tree/</filename> + and then boots an OS in a namespace container in it, + with systemd as init system.</para> + </refsect1> + + <refsect1> + <title>Example 2</title> + + <programlisting># debootstrap --arch=amd64 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> + + </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> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |