40
67
see each other. The PID namespace separation of the
41
68
two containers is complete and the containers will
42
69
share very few runtime objects except for the
43
underlying file system.</p></div><div class="refsect1" title="Options"><a name="id421642"></a><h2>Options</h2><p>If no arguments are passed the container is set
44
up and a shell started in it, otherwise the passed
45
command and arguments are executed in it. The
46
following options are understood:</p><div class="variablelist"><dl><dt><span class="term"><code class="option">--help</code>, </span><span class="term"><code class="option">-h</code></span></dt><dd><p>Prints a short help
47
text and exits.</p></dd><dt><span class="term"><code class="option">--directory=</code>, </span><span class="term"><code class="option">-D</code></span></dt><dd><p>Directory to use as
70
underlying file system. It is however possible to
71
enter an existing container, see
72
<a class="link" href="#example-nsenter" title="Example 4">Example 4</a> below.
73
</p><p><span class="command"><strong>systemd-nspawn</strong></span> implements the
74
<a class="ulink" href="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface" target="_top">Container
75
Interface</a> specification.</p><p>As a safety check
76
<span class="command"><strong>systemd-nspawn</strong></span> will verify the
77
existance of <code class="filename">/etc/os-release</code> in
78
the container tree before starting the container (see
79
<a href="os-release.html"><span class="citerefentry"><span class="refentrytitle">os-release</span>(5)</span></a>). It
80
might be necessary to add this file to the container
81
tree manually if the OS of the container is too old to
82
contain this file out-of-the-box.</p><p>Note that the kernel auditing subsystem is
83
currently broken when used together with
84
containers. We hence recommend turning it off entirely
85
when using <span class="command"><strong>systemd-nspawn</strong></span> by
86
booting with <code class="literal">audit=0</code> on the kernel
87
command line, or by turning it off at kernel build
88
time. If auditing is enabled in the kernel operating
89
systems booted in an nspawn container might refuse
90
log-in attempts.</p></div><div class="refsect1"><a name="idm259782111488"></a><h2 id="Options">Options<a class="headerlink" title="Permalink to this headline" href="#Options">¶</a></h2><p>If option <code class="option">-b</code> is specified, the
91
arguments are used as arguments for the init
92
binary. Otherwise, <em class="replaceable"><code>COMMAND</code></em>
93
specifies the program to launch in the container, and
94
the remaining arguments are used as arguments for this
95
program. If <code class="option">-b</code> is not used and no
96
arguments are specifed, a shell is launched in the
97
container.</p><p>The following options are understood:</p><div class="variablelist"><dl class="variablelist"><dt id="-h"><span class="term"><code class="option">-h</code>, </span><span class="term"><code class="option">--help</code></span><a class="headerlink" title="Permalink to this term" href="#-h">¶</a></dt><dd><p>Prints a short help
98
text and exits.</p></dd><dt id="--version"><span class="term"><code class="option">--version</code></span><a class="headerlink" title="Permalink to this term" href="#--version">¶</a></dt><dd><p>Prints a version string
99
and exits.</p></dd><dt id="-D"><span class="term"><code class="option">-D</code>, </span><span class="term"><code class="option">--directory=</code></span><a class="headerlink" title="Permalink to this term" href="#-D">¶</a></dt><dd><p>Directory to use as
48
100
file system root for the namespace
49
101
container. If omitted the current
51
used.</p></dd><dt><span class="term"><code class="option">--user=</code>, </span><span class="term"><code class="option">-u</code></span></dt><dd><p>Run the command
103
used.</p></dd><dt id="-b"><span class="term"><code class="option">-b</code>, </span><span class="term"><code class="option">--boot</code></span><a class="headerlink" title="Permalink to this term" href="#-b">¶</a></dt><dd><p>Automatically search
104
for an init binary and invoke it
105
instead of a shell or a user supplied
106
program. If this option is used, arguments
107
specified on the command line are used
108
as arguments for the init binary.
109
</p></dd><dt id="-u"><span class="term"><code class="option">-u</code>, </span><span class="term"><code class="option">--user=</code></span><a class="headerlink" title="Permalink to this term" href="#-u">¶</a></dt><dd><p>Run the command
52
110
under specified user, create home
53
111
directory and cd into it. As rest
54
112
of systemd-nspawn, this is not
55
113
the security feature and limits
56
114
against accidental changes only.
57
</p></dd><dt><span class="term"><code class="option">--private-network</code></span></dt><dd><p>Turn off networking in
115
</p></dd><dt id="-M"><span class="term"><code class="option">-M</code>, </span><span class="term"><code class="option">--machine=</code></span><a class="headerlink" title="Permalink to this term" href="#-M">¶</a></dt><dd><p>Sets the machine name
116
for this container. This name may be
117
used to identify this container on the
118
host, and is used to initialize the
119
container's hostname (which the
120
container can choose to override,
121
however). If not specified the last
122
component of the root directory of the
123
container is used.</p></dd><dt id="--uuid="><span class="term"><code class="option">--uuid=</code></span><a class="headerlink" title="Permalink to this term" href="#--uuid=">¶</a></dt><dd><p>Set the specified uuid
124
for the container. The init system
126
<code class="filename">/etc/machine-id</code>
127
from this if this file is not set yet.
128
</p></dd><dt id="-C"><span class="term"><code class="option">-C</code>, </span><span class="term"><code class="option">--controllers=</code></span><a class="headerlink" title="Permalink to this term" href="#-C">¶</a></dt><dd><p>Makes the container appear in
129
other hierarchies than the name=systemd:/ one.
130
Takes a comma-separated list of controllers.
131
</p></dd><dt id="--private-network"><span class="term"><code class="option">--private-network</code></span><a class="headerlink" title="Permalink to this term" href="#--private-network">¶</a></dt><dd><p>Turn off networking in
58
132
the container. This makes all network
59
133
interfaces unavailable in the
60
134
container, with the exception of the
61
loopback device.</p></dd></dl></div></div><div class="refsect1" title="Example 1"><a name="id421726"></a><h2>Example 1</h2><pre class="programlisting"># debootstrap --arch=amd64 unstable debian-tree/
62
# systemd-nspawn -D debian-tree/</pre><p>This installs a minimal Debian unstable
135
loopback device.</p></dd><dt id="--read-only"><span class="term"><code class="option">--read-only</code></span><a class="headerlink" title="Permalink to this term" href="#--read-only">¶</a></dt><dd><p>Mount the root file
136
system read only for the
137
container.</p></dd><dt id="--capability="><span class="term"><code class="option">--capability=</code></span><a class="headerlink" title="Permalink to this term" href="#--capability=">¶</a></dt><dd><p>List one or more
138
additional capabilities to grant the
139
container. Takes a comma separated
140
list of capability names, see
141
<a href="capabilities.html"><span class="citerefentry"><span class="refentrytitle">capabilities</span>(7)</span></a>
142
for more information. Note that the
143
following capabilities will be granted
144
in any way: CAP_CHOWN,
145
CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH,
146
CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER,
149
CAP_NET_BIND_SERVICE,
150
CAP_NET_BROADCAST, CAP_NET_RAW,
151
CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP,
152
CAP_SETUID, CAP_SYS_ADMIN,
153
CAP_SYS_CHROOT, CAP_SYS_NICE,
154
CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG,
155
CAP_SYS_RESOURCE, CAP_SYS_BOOT,
157
CAP_AUDIT_CONTROL.</p></dd><dt id="--link-journal="><span class="term"><code class="option">--link-journal=</code></span><a class="headerlink" title="Permalink to this term" href="#--link-journal=">¶</a></dt><dd><p>Control whether the
158
container's journal shall be made
159
visible to the host system. If enabled
160
allows viewing the container's journal
161
files from the host (but not vice
163
<code class="literal">no</code>,
164
<code class="literal">host</code>,
165
<code class="literal">guest</code>,
166
<code class="literal">auto</code>. If
167
<code class="literal">no</code>, the journal is
168
not linked. If <code class="literal">host</code>,
169
the journal files are stored on the
170
host file system (beneath
171
<code class="filename">/var/log/journal/<em class="replaceable"><code>machine-id</code></em></code>)
172
and the subdirectory is bind-mounted
173
into the container at the same
174
location. If <code class="literal">guest</code>,
175
the journal files are stored on the
176
guest file system (beneath
177
<code class="filename">/var/log/journal/<em class="replaceable"><code>machine-id</code></em></code>)
178
and the subdirectory is symlinked into the host
179
at the same location. If
180
<code class="literal">auto</code> (the default),
181
and the right subdirectory of
182
<code class="filename">/var/log/journal</code>
183
exists, it will be bind mounted
184
into the container. If the
185
subdirectory doesn't exist, no
186
linking is performed. Effectively,
187
booting a container once with
188
<code class="literal">guest</code> or
189
<code class="literal">host</code> will link the
190
journal persistently if further on
191
the default of <code class="literal">auto</code>
192
is used.</p></dd><dt id="-j"><span class="term"><code class="option">-j</code></span><a class="headerlink" title="Permalink to this term" href="#-j">¶</a></dt><dd><p>Equivalent to
193
<code class="option">--link-journal=guest</code>.</p></dd><dt id="--bind="><span class="term"><code class="option">--bind=</code>, </span><span class="term"><code class="option">--bind-ro=</code></span><a class="headerlink" title="Permalink to this term" href="#--bind=">¶</a></dt><dd><p>Bind mount a file or
194
directory from the host into the
195
container. Either takes a path
196
argument -- in which case the
197
specified path will be mounted from
198
the host to the same path in the
199
container --, or a colon-separated
200
pair of paths -- in which case the
201
first specified path is the source in
202
the host, and the second path is the
203
destination in the container. The
204
<code class="option">--bind-ro=</code> option
205
creates read-only bind
206
mount.</p></dd></dl></div></div><div class="refsect1"><a name="idm259777421088"></a><h2 id="Example 1">Example 1<a class="headerlink" title="Permalink to this headline" href="#Example%201">¶</a></h2><pre class="programlisting"># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal
207
# systemd-nspawn -bD /srv/mycontainer</pre><p>This installs a minimal Fedora distribution into
208
the directory <code class="filename">/srv/mycontainer/</code> and
209
then boots an OS in a namespace container in
210
it.</p></div><div class="refsect1"><a name="idm259777418240"></a><h2 id="Example 2">Example 2<a class="headerlink" title="Permalink to this headline" href="#Example%202">¶</a></h2><pre class="programlisting"># debootstrap --arch=amd64 unstable ~/debian-tree/
211
# systemd-nspawn -D ~/debian-tree/</pre><p>This installs a minimal Debian unstable
63
212
distribution into the directory
64
<code class="filename">debian-tree/</code> and then spawns a
65
shell in a namespace container in it.</p></div><div class="refsect1" title="Example 2"><a name="id389146"></a><h2>Example 2</h2><pre class="programlisting"># mock --init
66
# systemd-nspawn -D /var/lib/mock/fedora-rawhide-x86_64/root/ /sbin/init systemd.log_level=debug</pre><p>This installs a minimal Fedora distribution into
67
a subdirectory of <code class="filename">/var/lib/mock/</code>
68
and then boots an OS in a namespace container in it,
69
with systemd as init system, configured for debug
70
logging.</p></div><div class="refsect1" title="Exit status"><a name="id389170"></a><h2>Exit status</h2><p>The exit code of the program executed in the
71
container is returned.</p></div><div class="refsect1" title="See Also"><a name="id389181"></a><h2>See Also</h2><p>
72
<span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span>,
73
<span class="citerefentry"><span class="refentrytitle">chroot</span>(1)</span>,
74
<span class="citerefentry"><span class="refentrytitle">debootstrap</span>(8)</span>,
75
<span class="citerefentry"><span class="refentrytitle">mock</span>(1)</span>
213
<code class="filename">~/debian-tree/</code> and then spawns a
214
shell in a namespace container in it.</p></div><div class="refsect1"><a name="idm259777415520"></a><h2 id="Example 3">Example 3<a class="headerlink" title="Permalink to this headline" href="#Example%203">¶</a></h2><pre class="programlisting"># pacstrap -c -d ~/arch-tree/ base
215
# systemd-nspawn -bD ~/arch-tree/</pre><p>This installs a mimimal Arch Linux distribution into
216
the directory <code class="filename">~/arch-tree/</code> and then
217
boots an OS in a namespace container in it.</p></div><div class="refsect1"><a name="example-nsenter"></a><h2 id="Example 4">Example 4<a class="headerlink" title="Permalink to this headline" href="#Example%204">¶</a></h2><p>To enter the container, PID of one of the
218
processes sharing the new namespaces must be used.
219
<span class="command"><strong>systemd-nspawn</strong></span> prints the PID
220
(as viewed from the outside) of the launched process,
221
and it can be used to enter the container.</p><pre class="programlisting"># nsenter -m -u -i -n -p -t $PID</pre><p><a href="nsenter.html"><span class="citerefentry"><span class="refentrytitle">nsenter</span>(1)</span></a>
223
<a class="ulink" href="https://github.com/karelzak/util-linux" target="_top">util-linux</a>.
224
Kernel support for entering namespaces was added in
225
Linux 3.8.</p></div><div class="refsect1"><a name="idm259777408320"></a><h2 id="Exit status">Exit status<a class="headerlink" title="Permalink to this headline" href="#Exit%20status">¶</a></h2><p>The exit code of the program executed in the
226
container is returned.</p></div><div class="refsect1"><a name="idm259777407072"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
227
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
228
<a href="chroot.html"><span class="citerefentry"><span class="refentrytitle">chroot</span>(1)</span></a>,
229
<a href="unshare.html"><span class="citerefentry"><span class="refentrytitle">unshare</span>(1)</span></a>,
230
<a href="yum.html"><span class="citerefentry"><span class="refentrytitle">yum</span>(8)</span></a>,
231
<a href="debootstrap.html"><span class="citerefentry"><span class="refentrytitle">debootstrap</span>(8)</span></a>,
232
<a href="pacman.html"><span class="citerefentry"><span class="refentrytitle">pacman</span>(8)</span></a>
76
233
</p></div></div></body></html>
added
removed
man/systemd-nspawn.html
