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 Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 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   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser 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>/sys/fs/selinux</filename>. Network
  73                 interfaces and the system clock may not be changed
  74                 from within the container. Device nodes may not be
  75                 created. The host system cannot be rebooted and kernel
  76                 modules may not be loaded from within the
  77                 container.</para>
  78
  79                 <para>Note that even though these security precautions
  80                 are taken <command>systemd-nspawn</command> is not
  81                 suitable for secure container setups. Many of the
  82                 security features may be circumvented and are hence
  83                 primarily useful to avoid accidental changes to the
  84                 host system from the container. The intended use of
  85                 this program is debugging and testing as well as
  86                 building of packages, distributions and software
  87                 involved with boot and systems management.</para>
  88
  89                 <para>In contrast to
  90                 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  91                 <command>systemd-nspawn</command> may be used to boot
  92                 full Linux-based operating systems in a
  93                 container.</para>
  94
  95                 <para>Use a tool like
  96                 <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  97                 or
  98                 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  99                 to set up an OS directory tree suitable as file system
 100                 hierarchy for <command>systemd-nspawn</command>
 101                 containers.</para>
 102
 103                 <para>Note that <command>systemd-nspawn</command> will
 104                 mount file systems private to the container to
 105                 <filename>/dev</filename>,
 106                 <filename>/run</filename> and similar. These will
 107                 not be visible outside of the container, and their
 108                 contents will be lost when the container exits.</para>
 109
 110                 <para>Note that running two
 111                 <command>systemd-nspawn</command> containers from the
 112                 same directory tree will not make processes in them
 113                 see each other. The PID namespace separation of the
 114                 two containers is complete and the containers will
 115                 share very few runtime objects except for the
 116                 underlying file system.</para>
 117
 118                 <para><command>systemd-nspawn</command> implements the
 119                 <ulink
 120                 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
 121                 Interface</ulink> specification.</para>
 122         </refsect1>
 123
 124         <refsect1>
 125                 <title>Options</title>
 126
 127                 <para>If no arguments are passed the container is set
 128                 up and a shell started in it, otherwise the passed
 129                 command and arguments are executed in it. The
 130                 following options are understood:</para>
 131
 132                 <variablelist>
 133                         <varlistentry>
 134                                 <term><option>--help</option></term>
 135                                 <term><option>-h</option></term>
 136
 137                                 <listitem><para>Prints a short help
 138                                 text and exits.</para></listitem>
 139                         </varlistentry>
 140
 141                         <varlistentry>
 142                                 <term><option>--directory=</option></term>
 143                                 <term><option>-D</option></term>
 144
 145                                 <listitem><para>Directory to use as
 146                                 file system root for the namespace
 147                                 container. If omitted the current
 148                                 directory will be
 149                                 used.</para></listitem>
 150                         </varlistentry>
 151
 152                         <varlistentry>
 153                                 <term><option>--boot</option></term>
 154                                 <term><option>-b</option></term>
 155
 156                                 <listitem><para>Automatically search
 157                                 for an init binary and invoke it
 158                                 instead of a shell or a user supplied
 159                                 program.</para></listitem>
 160                         </varlistentry>
 161
 162                         <varlistentry>
 163                                 <term><option>--user=</option></term>
 164                                 <term><option>-u</option></term>
 165
 166                                 <listitem><para>Run the command
 167                                 under specified user, create home
 168                                 directory and cd into it. As rest
 169                                 of systemd-nspawn, this is not
 170                                 the security feature and limits
 171                                 against accidental changes only.
 172                                 </para></listitem>
 173                         </varlistentry>
 174
 175                         <varlistentry>
 176                                 <term><option>--uuid=</option></term>
 177
 178                                 <listitem><para>Set the specified uuid
 179                                 for the container. The init system
 180                                 will initialize
 181                                 <filename>/etc/machine-id</filename>
 182                                 from this if this file is not set yet.
 183                                 </para></listitem>
 184                         </varlistentry>
 185
 186                         <varlistentry>
 187                                 <term><option>--controllers=</option></term>
 188                                 <term><option>-C</option></term>
 189
 190                                 <listitem><para>Makes the container appear in
 191                                 other hierarchies that the name=systemd:/ one.
 192                                 Takes a comma-separated list of controllers.
 193                                 </para></listitem>
 194                         </varlistentry>
 195
 196                         <varlistentry>
 197                                 <term><option>--private-network</option></term>
 198
 199                                 <listitem><para>Turn off networking in
 200                                 the container. This makes all network
 201                                 interfaces unavailable in the
 202                                 container, with the exception of the
 203                                 loopback device.</para></listitem>
 204                         </varlistentry>
 205
 206                         <varlistentry>
 207                                 <term><option>--read-only</option></term>
 208
 209                                 <listitem><para>Mount the root file
 210                                 system read only for the
 211                                 container.</para></listitem>
 212                         </varlistentry>
 213
 214                         <varlistentry>
 215                                 <term><option>--capability=</option></term>
 216
 217                                 <listitem><para>List one or more
 218                                 additional capabilities to grant the
 219                                 container. Takes a comma separated
 220                                 list of capability names, see
 221                                 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 222                                 for more information. Note that the
 223                                 the following capabilities will be
 224                                 granted in any way: CAP_CHOWN,
 225                                 CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
 226                                 CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
 227                                 CAP_KILL, CAP_LEASE,
 228                                 CAP_LINUX_IMMUTABLE,
 229                                 CAP_NET_BIND_SERVICE,
 230                                 CAP_NET_BROADCAST, CAP_NET_RAW,
 231                                 CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
 232                                 CAP_SETUID, CAP_SYS_ADMIN,
 233                                 CAP_SYS_CHROOT, CAP_SYS_NICE,
 234                                 CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
 235                                 CAP_SYS_RESOURCE, CAP_SYS_BOOT.</para></listitem>
 236                         </varlistentry>
 237
 238                         <varlistentry>
 239                                 <term><option>--link-journal=</option></term>
 240
 241                                 <listitem><para>Control whether the
 242                                 container's journal shall be made
 243                                 visible to the host system. If enabled
 244                                 allows viewing the container's journal
 245                                 files from the host (but not vice
 246                                 versa). Takes one of
 247                                 <literal>no</literal>,
 248                                 <literal>host</literal>,
 249                                 <literal>guest</literal>,
 250                                 <literal>auto</literal>. If
 251                                 <literal>no</literal> the journal is
 252                                 not linked. If <literal>host</literal>
 253                                 the journal files are stored on the
 254                                 host file system (beneath the host's
 255                                 <filename>/var/log/journal</filename>)
 256                                 and a per-machine subdirectory of this
 257                                 directory is created and bind mounted
 258                                 into the container at the same
 259                                 location. If <literal>guest</literal>
 260                                 the journal files are stored on the
 261                                 guest file system (beneath the guest's
 262                                 <filename>/var/log/journal</filename>)
 263                                 and a per-machine subdirectory of this
 264                                 directory is symlinked into the host
 265                                 at the same location. If
 266                                 <literal>auto</literal> (the default)
 267                                 and the subdirectory of
 268                                 <filename>/var/log/journal</filename>
 269                                 exists as directory it is bind mounted
 270                                 into the container, but nothing is
 271                                 done otherwise. Effectively, booting a
 272                                 container once with
 273                                 <literal>guest</literal> or
 274                                 <literal>host</literal> will link the
 275                                 journal persistantly if further one
 276                                 the default of <literal>auto</literal>
 277                                 is used.</para></listitem>
 278                         </varlistentry>
 279
 280                         <varlistentry>
 281                                 <term><option>-j</option></term>
 282
 283                                 <listitem><para>Equivalent to
 284                                 <option>--link-journal=guest</option>.</para></listitem>
 285                         </varlistentry>
 286                 </variablelist>
 287
 288         </refsect1>
 289
 290         <refsect1>
 291                 <title>Example 1</title>
 292
 293                 <programlisting># yum --releasever=17 --nogpgcheck --installroot ~/fedora-tree/ install yum passwd vim-minimal rootfiles systemd
 294 # systemd-nspawn -D ~/fedora-tree /usr/lib/systemd/systemd</programlisting>
 295
 296                 <para>This installs a minimal Fedora distribution into
 297                 the directory <filename>~/fedora-tree/</filename>
 298                 and then boots an OS in a namespace container in it,
 299                 with systemd as init system.</para>
 300         </refsect1>
 301
 302         <refsect1>
 303                 <title>Example 2</title>
 304
 305                 <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/
 306 # systemd-nspawn -D ~/debian-tree/</programlisting>
 307
 308                 <para>This installs a minimal Debian unstable
 309                 distribution into the directory
 310                 <filename>~/debian-tree/</filename> and then spawns a
 311                 shell in a namespace container in it.</para>
 312
 313         </refsect1>
 314
 315         <refsect1>
 316                 <title>Exit status</title>
 317
 318                 <para>The exit code of the program executed in the
 319                 container is returned.</para>
 320         </refsect1>
 321
 322         <refsect1>
 323                 <title>See Also</title>
 324                 <para>
 325                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 326                         <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 327                         <citerefentry><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 328                         <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 329                 </para>
 330         </refsect1>
 331
 332 </refentry>