You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

216 lines
9.4 KiB

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