systemd-nspawn.xml 9.93 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
<?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
11
12
  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
13
14
15
16
17
  (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
18
  Lesser General Public License for more details.
19

20
  You should have received a copy of the GNU Lesser General Public License
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
  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
64
                system hierarchy, as well as the process tree, the
65
66
67
68
69
70
71
                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
Lennart Poettering's avatar
Lennart Poettering committed
72
73
74
75
76
77
                <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>
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

                <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>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry> or <citerefentry><refentrytitle>mock</refentrytitle><manvolnum>1</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>,
Kay Sievers's avatar
Kay Sievers committed
103
                <filename>/run</filename> and similar. These will
104
105
106
107
108
109
                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
110
                see each other. The PID namespace separation of the
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
                two containers is complete and the containers will
                share very few runtime objects except for the
                underlying file system.</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>
127
                                <term><option>-h</option></term>
128
129
130
131
132
133
134

                                <listitem><para>Prints a short help
                                text and exits.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--directory=</option></term>
135
                                <term><option>-D</option></term>
136
137
138
139
140
141
142
143

                                <listitem><para>Directory to use as
                                file system root for the namespace
                                container. If omitted the current
                                directory will be
                                used.</para></listitem>
                        </varlistentry>

144
145
                        <varlistentry>
                                <term><option>--user=</option></term>
Lennart Poettering's avatar
Lennart Poettering committed
146
                                <term><option>-u</option></term>
147
148
149
150
151
152
153
154
155
156

                                <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>

157
158
159
160
161
162
163
164
165
166
                        <varlistentry>
                                <term><option>--controllers=</option></term>
                                <term><option>-C</option></term>

                                <listitem><para>Makes the container appear in
                                other hierarchies that the name=systemd:/ one.
                                Takes a comma-separated list of controllers.
                                </para></listitem>
                        </varlistentry>

167
                        <varlistentry>
168
                                <term><option>--private-network</option></term>
169
170
171
172
173
174
175
176

                                <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>

177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
                </variablelist>

        </refsect1>

        <refsect1>
                <title>Example 1</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>Example 2</title>

                <programlisting># mock --init
198
# systemd-nspawn -D /var/lib/mock/fedora-rawhide-x86_64/root/ /sbin/init systemd.log_level=debug</programlisting>
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219

                <para>This installs a minimal Fedora distribution into
                a subdirectory of <filename>/var/lib/mock/</filename>
                and then boots an OS in a namespace container in it,
                with systemd as init system, configured for debug
                logging.</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>,
220
                        <citerefentry><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
221
222
223
224
225
                        <citerefentry><refentrytitle>mock</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>