]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/systemd-nspawn.xml
util: detect page size runtime.
[thirdparty/systemd.git] / man / systemd-nspawn.xml
CommitLineData
8f7a3c14
LP
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 hierachy, 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>/dev/.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 seperation 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 </variablelist>
143
144 </refsect1>
145
146 <refsect1>
147 <title>Example 1</title>
148
149 <programlisting># debootstrap --arch=amd64 unstable debian-tree/
150# systemd-nspawn -D debian-tree/</programlisting>
151
152 <para>This installs a minimal Debian unstable
153 distribution into the directory
154 <filename>debian-tree/</filename> and then spawns a
155 shell in a namespace container in it.</para>
156
157 </refsect1>
158
159 <refsect1>
160 <title>Example 2</title>
161
162 <programlisting># mock --init
163# systemd-nspawn -D /var/lib/mock/fedora-rawhide-x86_64/root/ /bin/systemd systemd.log_level=debug</programlisting>
164
165 <para>This installs a minimal Fedora distribution into
166 a subdirectory of <filename>/var/lib/mock/</filename>
167 and then boots an OS in a namespace container in it,
168 with systemd as init system, configured for debug
169 logging.</para>
170
171 </refsect1>
172
173 <refsect1>
174 <title>Exit status</title>
175
176 <para>The exit code of the program executed in the
177 container is returned.</para>
178 </refsect1>
179
180 <refsect1>
181 <title>See Also</title>
182 <para>
183 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
184 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
185 <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>
186 <citerefentry><refentrytitle>mock</refentrytitle><manvolnum>1</manvolnum></citerefentry>
187 </para>
188 </refsect1>
189
190</refentry>