man/systemd-nspawn.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2010 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU General Public License as published by
  12   the Free Software Foundation; either version 2 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   General Public License for more details.
  19
  20   You should have received a copy of the GNU General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="systemd-nspawn">
  25
  26         <refentryinfo>
  27                 <title>systemd-nspawn</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>systemd-nspawn</refentrytitle>
  42                 <manvolnum>1</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>systemd-nspawn</refname>
  47                 <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose>
  48         </refnamediv>
  49
  50         <refsynopsisdiv>
  51                 <cmdsynopsis>
  52                         <command>systemd-nspawn <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">COMMAND</arg> <arg choice="opt" rep="repeat">ARGS</arg></command>
  53                 </cmdsynopsis>
  54         </refsynopsisdiv>
  55
  56         <refsect1>
  57                 <title>Description</title>
  58
  59                 <para><command>systemd-nspawn</command> may be used to
  60                 run a command or OS in a light-weight namespace
  61                 container. In many ways it is similar to
  62                 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  63                 but more powerful since it fully virtualizes the file
  64                 system hierarchy, as well as the process tree, the
  65                 various IPC subsystems and the host and domain
  66                 name.</para>
  67
  68                 <para><command>systemd-nspawn</command> limits access
  69                 to various kernel interfaces in the container to
  70                 read-only, such as <filename>/sys</filename>,
  71                 <filename>/proc/sys</filename> or
  72                 <filename>/selinux</filename>. Network interfaces and
  73                 the system clock may not be changed from within the
  74                 container. Device nodes may not be created. The host
  75                 system cannot be rebooted and kernel modules may not
  76                 be loaded from within the container.</para>
  77
  78                 <para>Note that even though these security precautions
  79                 are taken <command>systemd-nspawn</command> is not
  80                 suitable for secure container setups. Many of the
  81                 security features may be circumvented and are hence
  82                 primarily useful to avoid accidental changes to the
  83                 host system from the container. The intended use of
  84                 this program is debugging and testing as well as
  85                 building of packages, distributions and software
  86                 involved with boot and systems management.</para>
  87
  88                 <para>In contrast to
  89                 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  90                 <command>systemd-nspawn</command> may be used to boot
  91                 full Linux-based operating systems in a
  92                 container.</para>
  93
  94                 <para>Use a tool like
  95                 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry> or <citerefentry><refentrytitle>mock</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  96                 to set up an OS directory tree suitable as file system
  97                 hierarchy for <command>systemd-nspawn</command> containers.</para>
  98
  99                 <para>Note that <command>systemd-nspawn</command> will
 100                 mount file systems private to the container to
 101                 <filename>/dev</filename>,
 102                 <filename>/run</filename> and similar. These will
 103                 not be visible outside of the container, and their
 104                 contents will be lost when the container exits.</para>
 105
 106                 <para>Note that running two
 107                 <command>systemd-nspawn</command> containers from the
 108                 same directory tree will not make processes in them
 109                 see each other. The PID namespace separation of the
 110                 two containers is complete and the containers will
 111                 share very few runtime objects except for the
 112                 underlying file system.</para>
 113         </refsect1>
 114
 115         <refsect1>
 116                 <title>Options</title>
 117
 118                 <para>If no arguments are passed the container is set
 119                 up and a shell started in it, otherwise the passed
 120                 command and arguments are executed in it. The
 121                 following options are understood:</para>
 122
 123                 <variablelist>
 124                         <varlistentry>
 125                                 <term><option>--help</option></term>
 126
 127                                 <listitem><para>Prints a short help
 128                                 text and exits.</para></listitem>
 129                         </varlistentry>
 130
 131                         <varlistentry>
 132                                 <term><option>--directory=</option></term>
 133                                 <term><option>--D</option></term>
 134
 135                                 <listitem><para>Directory to use as
 136                                 file system root for the namespace
 137                                 container. If omitted the current
 138                                 directory will be
 139                                 used.</para></listitem>
 140                         </varlistentry>
 141
 142                         <varlistentry>
 143                                 <term><option>--user=</option></term>
 144                                 <term><option>--u</option></term>
 145
 146                                 <listitem><para>Run the command
 147                                 under specified user, create home
 148                                 directory and cd into it. As rest
 149                                 of systemd-nspawn, this is not
 150                                 the security feature and limits
 151                                 against accidental changes only.
 152                                 </para></listitem>
 153                         </varlistentry>
 154
 155                 </variablelist>
 156
 157         </refsect1>
 158
 159         <refsect1>
 160                 <title>Example 1</title>
 161
 162                 <programlisting># debootstrap --arch=amd64 unstable debian-tree/
 163 # systemd-nspawn -D debian-tree/</programlisting>
 164
 165                 <para>This installs a minimal Debian unstable
 166                 distribution into the directory
 167                 <filename>debian-tree/</filename> and then spawns a
 168                 shell in a namespace container in it.</para>
 169
 170         </refsect1>
 171
 172         <refsect1>
 173                 <title>Example 2</title>
 174
 175                 <programlisting># mock --init
 176 # systemd-nspawn -D /var/lib/mock/fedora-rawhide-x86_64/root/ /bin/systemd systemd.log_level=debug</programlisting>
 177
 178                 <para>This installs a minimal Fedora distribution into
 179                 a subdirectory of <filename>/var/lib/mock/</filename>
 180                 and then boots an OS in a namespace container in it,
 181                 with systemd as init system, configured for debug
 182                 logging.</para>
 183
 184         </refsect1>
 185
 186         <refsect1>
 187                 <title>Exit status</title>
 188
 189                 <para>The exit code of the program executed in the
 190                 container is returned.</para>
 191         </refsect1>
 192
 193         <refsect1>
 194                 <title>See Also</title>
 195                 <para>
 196                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 197                         <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 198                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 199                         <citerefentry><refentrytitle>mock</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 200                 </para>
 201         </refsect1>
 202
 203 </refentry>