]>
Commit | Line | Data |
---|---|---|
663996b3 MS |
1 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>systemd-nspawn</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style> |
2 | a.headerlink { | |
3 | color: #c60f0f; | |
4 | font-size: 0.8em; | |
5 | padding: 0 4px 0 4px; | |
6 | text-decoration: none; | |
7 | visibility: hidden; | |
8 | } | |
9 | ||
10 | a.headerlink:hover { | |
11 | background-color: #c60f0f; | |
12 | color: white; | |
13 | } | |
14 | ||
15 | h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink { | |
16 | visibility: visible; | |
17 | } | |
18 | </style><a href="index.html">Index </a>· | |
19 | <a href="systemd.directives.html">Directives </a>· | |
20 | <a href="../python-systemd/index.html">Python </a>· | |
21 | <a href="../libudev/index.html">libudev </a>· | |
5eef597e | 22 | <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 217</span><hr><div class="refentry"><a name="systemd-nspawn"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>systemd-nspawn — Spawn a namespace container for debugging, testing and building</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">systemd-nspawn</code> [OPTIONS...] [<em class="replaceable"><code>COMMAND</code></em> |
663996b3 | 23 | [ARGS...] |
5eef597e | 24 | ]</p></div><div class="cmdsynopsis"><p><code class="command">systemd-nspawn</code> -b [OPTIONS...] [ARGS...]</p></div></div><div class="refsect1"><a name="idm214181337840"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><span class="command"><strong>systemd-nspawn</strong></span> may be used to |
663996b3 MS |
25 | run a command or OS in a light-weight namespace |
26 | container. In many ways it is similar to | |
5eef597e | 27 | <a href="http://man7.org/linux/man-pages/man1/chroot.1.html"><span class="citerefentry"><span class="refentrytitle">chroot</span>(1)</span></a>, |
663996b3 MS |
28 | but more powerful since it fully virtualizes the file |
29 | system hierarchy, as well as the process tree, the | |
30 | various IPC subsystems and the host and domain | |
31 | name.</p><p><span class="command"><strong>systemd-nspawn</strong></span> limits access | |
32 | to various kernel interfaces in the container to | |
33 | read-only, such as <code class="filename">/sys</code>, | |
34 | <code class="filename">/proc/sys</code> or | |
35 | <code class="filename">/sys/fs/selinux</code>. Network | |
36 | interfaces and the system clock may not be changed | |
37 | from within the container. Device nodes may not be | |
38 | created. The host system cannot be rebooted and kernel | |
39 | modules may not be loaded from within the | |
40 | container.</p><p>Note that even though these security precautions | |
41 | are taken <span class="command"><strong>systemd-nspawn</strong></span> is not | |
42 | suitable for secure container setups. Many of the | |
43 | security features may be circumvented and are hence | |
44 | primarily useful to avoid accidental changes to the | |
45 | host system from the container. The intended use of | |
46 | this program is debugging and testing as well as | |
47 | building of packages, distributions and software | |
48 | involved with boot and systems management.</p><p>In contrast to | |
5eef597e | 49 | <a href="http://man7.org/linux/man-pages/man1/chroot.1.html"><span class="citerefentry"><span class="refentrytitle">chroot</span>(1)</span></a> <span class="command"><strong>systemd-nspawn</strong></span> |
14228c0d MB |
50 | may be used to boot full Linux-based operating systems |
51 | in a container.</p><p>Use a tool like | |
5eef597e MP |
52 | <a href="http://linux.die.net/man/8/yum"><span class="citerefentry"><span class="refentrytitle">yum</span>(8)</span></a>, |
53 | <a href="http://linux.die.net/man/8/debootstrap"><span class="citerefentry"><span class="refentrytitle">debootstrap</span>(8)</span></a>, | |
663996b3 | 54 | or |
5eef597e | 55 | <a href="https://www.archlinux.org/pacman/pacman.8.html"><span class="citerefentry"><span class="refentrytitle">pacman</span>(8)</span></a> |
663996b3 MS |
56 | to set up an OS directory tree suitable as file system |
57 | hierarchy for <span class="command"><strong>systemd-nspawn</strong></span> | |
58 | containers.</p><p>Note that <span class="command"><strong>systemd-nspawn</strong></span> will | |
59 | mount file systems private to the container to | |
60 | <code class="filename">/dev</code>, | |
61 | <code class="filename">/run</code> and similar. These will | |
62 | not be visible outside of the container, and their | |
63 | contents will be lost when the container exits.</p><p>Note that running two | |
64 | <span class="command"><strong>systemd-nspawn</strong></span> containers from the | |
65 | same directory tree will not make processes in them | |
66 | see each other. The PID namespace separation of the | |
67 | two containers is complete and the containers will | |
68 | share very few runtime objects except for the | |
60f067b4 JS |
69 | underlying file system. Use |
70 | <a href="machinectl.html"><span class="citerefentry"><span class="refentrytitle">machinectl</span>(1)</span></a>'s | |
71 | <span class="command"><strong>login</strong></span> command to request an | |
72 | additional login prompt in a running container.</p><p><span class="command"><strong>systemd-nspawn</strong></span> implements the | |
663996b3 MS |
73 | <a class="ulink" href="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface" target="_top">Container |
74 | Interface</a> specification.</p><p>As a safety check | |
75 | <span class="command"><strong>systemd-nspawn</strong></span> will verify the | |
e842803a MB |
76 | existence of <code class="filename">/usr/lib/os-release</code> |
77 | or <code class="filename">/etc/os-release</code> in the | |
78 | container tree before starting the container (see | |
663996b3 MS |
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 | |
5eef597e | 82 | contain this file out-of-the-box.</p></div><div class="refsect1"><a name="idm214185204208"></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 |
663996b3 MS |
83 | arguments are used as arguments for the init |
84 | binary. Otherwise, <em class="replaceable"><code>COMMAND</code></em> | |
85 | specifies the program to launch in the container, and | |
86 | the remaining arguments are used as arguments for this | |
87 | program. If <code class="option">-b</code> is not used and no | |
88 | arguments are specifed, a shell is launched in the | |
60f067b4 JS |
89 | container.</p><p>The following options are understood:</p><div class="variablelist"><dl class="variablelist"><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 |
90 | file system root for the container. If | |
91 | neither <code class="option">--directory=</code> | |
92 | nor <code class="option">--image=</code> are | |
93 | specified, the current directory will | |
94 | be used. May not be specified together with | |
95 | <code class="option">--image=</code>.</p></dd><dt id="-i"><span class="term"><code class="option">-i</code>, </span><span class="term"><code class="option">--image=</code></span><a class="headerlink" title="Permalink to this term" href="#-i">¶</a></dt><dd><p>Disk image to mount | |
96 | the root directory for the container | |
97 | from. Takes a path to a regular file | |
98 | or to a block device node. The file or | |
99 | block device must contain a GUID | |
100 | Partition Table with a root partition | |
101 | which is mounted as the root directory | |
102 | of the container. Optionally, it may | |
103 | contain a home and/or a server data | |
104 | partition which are mounted to the | |
105 | appropriate places in the | |
106 | container. All these partitions must | |
107 | be identified by the partition types | |
108 | defined by the <a class="ulink" href="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/" target="_top">Discoverable | |
109 | Partitions Specification</a>. Any | |
110 | other partitions, such as foreign | |
111 | partitions, swap partitions or EFI | |
112 | system partitions are not mounted. May | |
113 | not be specified together with | |
114 | <code class="option">--directory=</code>.</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 | |
663996b3 MS |
115 | for an init binary and invoke it |
116 | instead of a shell or a user supplied | |
60f067b4 JS |
117 | program. If this option is used, |
118 | arguments specified on the command | |
119 | line are used as arguments for the | |
120 | init binary. This option may not be | |
121 | combined with | |
122 | <code class="option">--share-system</code>. | |
123 | </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>After transitioning | |
124 | into the container, change to the | |
125 | specified user-defined in the | |
126 | container's user database. Like all | |
127 | other systemd-nspawn features, this is | |
128 | not a security feature and provides | |
129 | protection against accidental | |
130 | destructive operations | |
131 | only.</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 | |
663996b3 MS |
132 | for this container. This name may be |
133 | used to identify this container on the | |
134 | host, and is used to initialize the | |
135 | container's hostname (which the | |
136 | container can choose to override, | |
14228c0d | 137 | however). If not specified, the last |
663996b3 | 138 | component of the root directory of the |
60f067b4 | 139 | 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 |
663996b3 MS |
140 | for the container. The init system |
141 | will initialize | |
142 | <code class="filename">/etc/machine-id</code> | |
143 | from this if this file is not set yet. | |
60f067b4 JS |
144 | </p></dd><dt id="--slice="><span class="term"><code class="option">--slice=</code></span><a class="headerlink" title="Permalink to this term" href="#--slice=">¶</a></dt><dd><p>Make the container |
145 | part of the specified slice, instead | |
146 | of the default | |
147 | <code class="filename">machine.slice</code>.</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>Disconnect networking | |
148 | of the container from the host. This | |
149 | makes all network interfaces | |
150 | unavailable in the container, with the | |
151 | exception of the loopback device and | |
152 | those specified with | |
153 | <code class="option">--network-interface=</code> | |
154 | and configured with | |
155 | <code class="option">--network-veth</code>. If | |
156 | this option is specified, the | |
157 | CAP_NET_ADMIN capability will be added | |
158 | to the set of capabilities the | |
159 | container retains. The latter may be | |
160 | disabled by using | |
161 | <code class="option">--drop-capability=</code>.</p></dd><dt id="--network-interface="><span class="term"><code class="option">--network-interface=</code></span><a class="headerlink" title="Permalink to this term" href="#--network-interface=">¶</a></dt><dd><p>Assign the specified | |
162 | network interface to the | |
163 | container. This will remove the | |
164 | specified interface from the calling | |
165 | namespace and place it in the | |
166 | container. When the container | |
167 | terminates, it is moved back to the | |
168 | host namespace. Note that | |
169 | <code class="option">--network-interface=</code> | |
170 | implies | |
171 | <code class="option">--private-network</code>. This | |
172 | option may be used more than once to | |
173 | add multiple network interfaces to the | |
174 | container.</p></dd><dt id="--network-macvlan="><span class="term"><code class="option">--network-macvlan=</code></span><a class="headerlink" title="Permalink to this term" href="#--network-macvlan=">¶</a></dt><dd><p>Create a | |
175 | "<code class="literal">macvlan</code>" interface | |
176 | of the specified Ethernet network | |
177 | interface and add it to the | |
178 | container. A | |
179 | "<code class="literal">macvlan</code>" interface | |
180 | is a virtual interface that adds a | |
181 | second MAC address to an existing | |
182 | physical Ethernet link. The interface | |
183 | in the container will be named after | |
184 | the interface on the host, prefixed | |
185 | with "<code class="literal">mv-</code>". Note that | |
186 | <code class="option">--network-macvlan=</code> | |
187 | implies | |
188 | <code class="option">--private-network</code>. This | |
189 | option may be used more than once to | |
190 | add multiple network interfaces to the | |
191 | container.</p></dd><dt id="--network-veth"><span class="term"><code class="option">--network-veth</code></span><a class="headerlink" title="Permalink to this term" href="#--network-veth">¶</a></dt><dd><p>Create a virtual | |
192 | Ethernet link | |
193 | ("<code class="literal">veth</code>") between host | |
194 | and container. The host side of the | |
195 | Ethernet link will be available as a | |
196 | network interface named after the | |
197 | container's name (as specified with | |
198 | <code class="option">--machine=</code>), prefixed | |
199 | with "<code class="literal">ve-</code>". The | |
200 | container side of the Ethernet | |
201 | link will be named | |
202 | "<code class="literal">host0</code>". Note that | |
203 | <code class="option">--network-veth</code> | |
204 | implies | |
205 | <code class="option">--private-network</code>.</p></dd><dt id="--network-bridge="><span class="term"><code class="option">--network-bridge=</code></span><a class="headerlink" title="Permalink to this term" href="#--network-bridge=">¶</a></dt><dd><p>Adds the host side of | |
206 | the Ethernet link created with | |
207 | <code class="option">--network-veth</code> to the | |
208 | specified bridge. Note that | |
209 | <code class="option">--network-bridge=</code> | |
210 | implies | |
211 | <code class="option">--network-veth</code>. If | |
212 | this option is used, the host side of | |
213 | the Ethernet link will use the | |
214 | "<code class="literal">vb-</code>" prefix instead | |
215 | of "<code class="literal">ve-</code>".</p></dd><dt id="-Z"><span class="term"><code class="option">-Z</code>, </span><span class="term"><code class="option">--selinux-context=</code></span><a class="headerlink" title="Permalink to this term" href="#-Z">¶</a></dt><dd><p>Sets the SELinux | |
216 | security context to be used to label | |
217 | processes in the container.</p></dd><dt id="-L"><span class="term"><code class="option">-L</code>, </span><span class="term"><code class="option">--selinux-apifs-context=</code></span><a class="headerlink" title="Permalink to this term" href="#-L">¶</a></dt><dd><p>Sets the SELinux security | |
218 | context to be used to label files in | |
219 | the virtual API file systems in the | |
663996b3 MS |
220 | 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 |
221 | additional capabilities to grant the | |
14228c0d | 222 | container. Takes a comma-separated |
663996b3 | 223 | list of capability names, see |
5eef597e | 224 | <a href="http://man7.org/linux/man-pages/man7/capabilities.7.html"><span class="citerefentry"><span class="refentrytitle">capabilities</span>(7)</span></a> |
663996b3 MS |
225 | for more information. Note that the |
226 | following capabilities will be granted | |
227 | in any way: CAP_CHOWN, | |
228 | CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, | |
229 | CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, | |
230 | CAP_KILL, CAP_LEASE, | |
231 | CAP_LINUX_IMMUTABLE, | |
232 | CAP_NET_BIND_SERVICE, | |
233 | CAP_NET_BROADCAST, CAP_NET_RAW, | |
234 | CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, | |
235 | CAP_SETUID, CAP_SYS_ADMIN, | |
236 | CAP_SYS_CHROOT, CAP_SYS_NICE, | |
237 | CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG, | |
238 | CAP_SYS_RESOURCE, CAP_SYS_BOOT, | |
239 | CAP_AUDIT_WRITE, | |
60f067b4 JS |
240 | CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN |
241 | is retained if | |
242 | <code class="option">--private-network</code> is | |
243 | specified. If the special value | |
244 | "<code class="literal">all</code>" is passed, all | |
245 | capabilities are | |
246 | retained.</p></dd><dt id="--drop-capability="><span class="term"><code class="option">--drop-capability=</code></span><a class="headerlink" title="Permalink to this term" href="#--drop-capability=">¶</a></dt><dd><p>Specify one or more | |
247 | additional capabilities to drop for | |
248 | the container. This allows running the | |
249 | container with fewer capabilities than | |
250 | the default (see above).</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 | |
663996b3 | 251 | container's journal shall be made |
14228c0d | 252 | visible to the host system. If enabled, |
663996b3 MS |
253 | allows viewing the container's journal |
254 | files from the host (but not vice | |
255 | versa). Takes one of | |
14228c0d MB |
256 | "<code class="literal">no</code>", |
257 | "<code class="literal">host</code>", | |
258 | "<code class="literal">guest</code>", | |
259 | "<code class="literal">auto</code>". If | |
260 | "<code class="literal">no</code>", the journal is | |
261 | not linked. If "<code class="literal">host</code>", | |
663996b3 MS |
262 | the journal files are stored on the |
263 | host file system (beneath | |
264 | <code class="filename">/var/log/journal/<em class="replaceable"><code>machine-id</code></em></code>) | |
265 | and the subdirectory is bind-mounted | |
266 | into the container at the same | |
14228c0d | 267 | location. If "<code class="literal">guest</code>", |
663996b3 MS |
268 | the journal files are stored on the |
269 | guest file system (beneath | |
270 | <code class="filename">/var/log/journal/<em class="replaceable"><code>machine-id</code></em></code>) | |
271 | and the subdirectory is symlinked into the host | |
272 | at the same location. If | |
14228c0d | 273 | "<code class="literal">auto</code>" (the default), |
663996b3 MS |
274 | and the right subdirectory of |
275 | <code class="filename">/var/log/journal</code> | |
276 | exists, it will be bind mounted | |
277 | into the container. If the | |
14228c0d | 278 | subdirectory does not exist, no |
663996b3 MS |
279 | linking is performed. Effectively, |
280 | booting a container once with | |
14228c0d MB |
281 | "<code class="literal">guest</code>" or |
282 | "<code class="literal">host</code>" will link the | |
663996b3 | 283 | journal persistently if further on |
14228c0d | 284 | the default of "<code class="literal">auto</code>" |
663996b3 | 285 | 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 |
60f067b4 JS |
286 | <code class="option">--link-journal=guest</code>.</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 |
287 | system read-only for the | |
288 | container.</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 | |
663996b3 MS |
289 | directory from the host into the |
290 | container. Either takes a path | |
291 | argument -- in which case the | |
292 | specified path will be mounted from | |
293 | the host to the same path in the | |
294 | container --, or a colon-separated | |
295 | pair of paths -- in which case the | |
296 | first specified path is the source in | |
297 | the host, and the second path is the | |
298 | destination in the container. The | |
299 | <code class="option">--bind-ro=</code> option | |
300 | creates read-only bind | |
60f067b4 JS |
301 | mounts.</p></dd><dt id="--tmpfs="><span class="term"><code class="option">--tmpfs=</code></span><a class="headerlink" title="Permalink to this term" href="#--tmpfs=">¶</a></dt><dd><p>Mount a tmpfs file |
302 | system into the container. Takes a | |
303 | single absolute path argument that | |
304 | specifies where to mount the tmpfs | |
305 | instance to (in which case the | |
306 | directory access mode will be chosen | |
307 | as 0755, owned by root/root), or | |
308 | optionally a colon-separated pair of | |
309 | path and mount option string, that is | |
310 | used for mounting (in which case the | |
311 | kernel default for access mode and | |
312 | owner will be chosen, unless otherwise | |
313 | specified). This option is | |
314 | particularly useful for mounting | |
315 | directories such as | |
316 | <code class="filename">/var</code> as tmpfs, to | |
317 | allow state-less systems, in | |
318 | particular when combined with | |
319 | <code class="option">--read-only</code>.</p></dd><dt id="--setenv="><span class="term"><code class="option">--setenv=</code></span><a class="headerlink" title="Permalink to this term" href="#--setenv=">¶</a></dt><dd><p>Specifies an | |
320 | environment variable assignment to | |
321 | pass to the init process in the | |
322 | container, in the format | |
323 | "<code class="literal">NAME=VALUE</code>". This | |
324 | may be used to override the default | |
325 | variables or to set additional | |
326 | variables. This parameter may be used | |
327 | more than once.</p></dd><dt id="--share-system"><span class="term"><code class="option">--share-system</code></span><a class="headerlink" title="Permalink to this term" href="#--share-system">¶</a></dt><dd><p>Allows the container | |
328 | to share certain system facilities | |
329 | with the host. More specifically, this | |
330 | turns off PID namespacing, UTS | |
331 | namespacing and IPC namespacing, and | |
332 | thus allows the guest to see and | |
333 | interact more easily with processes | |
334 | outside of the container. Note that | |
335 | using this option makes it impossible | |
336 | to start up a full Operating System in | |
337 | the container, as an init system | |
338 | cannot operate in this mode. It is | |
339 | only useful to run specific programs | |
340 | or applications this way, without | |
341 | involving an init system in the | |
342 | container. This option implies | |
343 | <code class="option">--register=no</code>. This | |
344 | option may not be combined with | |
345 | <code class="option">--boot</code>.</p></dd><dt id="--register="><span class="term"><code class="option">--register=</code></span><a class="headerlink" title="Permalink to this term" href="#--register=">¶</a></dt><dd><p>Controls whether the | |
346 | container is registered with | |
347 | <a href="systemd-machined.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined</span>(8)</span></a>. Takes | |
348 | a boolean argument, defaults to | |
349 | "<code class="literal">yes</code>". This option | |
350 | should be enabled when the container | |
351 | runs a full Operating System (more | |
352 | specifically: an init system), and is | |
353 | useful to ensure that the container is | |
354 | accessible via | |
355 | <a href="machinectl.html"><span class="citerefentry"><span class="refentrytitle">machinectl</span>(1)</span></a> | |
356 | and shown by tools such as | |
5eef597e | 357 | <a href="http://man7.org/linux/man-pages/man1/ps.1.html"><span class="citerefentry"><span class="refentrytitle">ps</span>(1)</span></a>. If |
60f067b4 JS |
358 | the container does not run an init |
359 | system, it is recommended to set this | |
360 | option to "<code class="literal">no</code>". Note | |
361 | that <code class="option">--share-system</code> | |
362 | implies | |
363 | <code class="option">--register=no</code>. | |
364 | </p></dd><dt id="--keep-unit"><span class="term"><code class="option">--keep-unit</code></span><a class="headerlink" title="Permalink to this term" href="#--keep-unit">¶</a></dt><dd><p>Instead of creating a | |
365 | transient scope unit to run the | |
366 | container in, simply register the | |
367 | service or scope unit | |
368 | <span class="command"><strong>systemd-nspawn</strong></span> has | |
369 | been invoked in with | |
370 | <a href="systemd-machined.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined</span>(8)</span></a>. This | |
371 | has no effect if | |
372 | <code class="option">--register=no</code> is | |
373 | used. This switch should be used if | |
374 | <span class="command"><strong>systemd-nspawn</strong></span> is | |
375 | invoked from within a service unit, | |
376 | and the service unit's sole purpose | |
377 | is to run a single | |
378 | <span class="command"><strong>systemd-nspawn</strong></span> | |
379 | container. This option is not | |
380 | available if run from a user | |
381 | session.</p></dd><dt id="--personality="><span class="term"><code class="option">--personality=</code></span><a class="headerlink" title="Permalink to this term" href="#--personality=">¶</a></dt><dd><p>Control the | |
382 | architecture ("personality") reported | |
383 | by | |
5eef597e | 384 | <a href="http://man7.org/linux/man-pages/man2/uname.2.html"><span class="citerefentry"><span class="refentrytitle">uname</span>(2)</span></a> |
60f067b4 JS |
385 | in the container. Currently, only |
386 | "<code class="literal">x86</code>" and | |
387 | "<code class="literal">x86-64</code>" are | |
388 | supported. This is useful when running | |
389 | a 32-bit container on a 64-bit | |
390 | host. If this setting is not used, | |
391 | the personality reported in the | |
392 | container is the same as the one | |
393 | reported on the | |
394 | host.</p></dd><dt id="-q"><span class="term"><code class="option">-q</code>, </span><span class="term"><code class="option">--quiet</code></span><a class="headerlink" title="Permalink to this term" href="#-q">¶</a></dt><dd><p>Turns off any status | |
395 | output by the tool itself. When this | |
396 | switch is used, the only output | |
397 | from nspawn will be the console output | |
5eef597e MP |
398 | of the container OS itself.</p></dd><dt id="--volatile=MODE"><span class="term"><code class="option">--volatile</code><em class="replaceable"><code>=MODE</code></em></span><a class="headerlink" title="Permalink to this term" href="#--volatile=MODE">¶</a></dt><dd><p>Boots the container in |
399 | volatile (ephemeral) mode. When no | |
400 | mode parameter is passed or when mode | |
401 | is specified as "<code class="literal">yes</code>" | |
402 | full volatile mode is enabled. This | |
403 | means the root directory is mounted as | |
404 | mostly unpopulated | |
405 | "<code class="literal">tmpfs</code>" instance, and | |
406 | <code class="filename">/usr</code> from the OS | |
407 | tree is mounted into it, read-only | |
408 | (the system thus starts up with | |
409 | read-only OS resources, but pristine | |
410 | state and configuration, any changes | |
411 | to the either are lost on | |
412 | shutdown). When the mode parameter is | |
413 | specified as "<code class="literal">state</code>" | |
414 | the OS tree is mounted read-only, but | |
415 | <code class="filename">/var</code> is mounted | |
416 | as "<code class="literal">tmpfs</code>" instance | |
417 | into it (the system thus starts up | |
418 | with read-only OS resources and | |
419 | configuration, but pristine state, any | |
420 | changes to the latter are lost on | |
421 | shutdown). When the mode parameter is | |
422 | specified as "<code class="literal">no</code>" | |
423 | (the default) the whole OS tree is made | |
424 | available writable.</p><p>Note that setting this to | |
425 | "<code class="literal">yes</code>" or | |
426 | "<code class="literal">state</code>" will only | |
427 | work correctly with operating systems | |
428 | in the container that can boot up with | |
429 | only <code class="filename">/usr</code> | |
430 | mounted, and are able to populate | |
431 | <code class="filename">/var</code> | |
432 | automatically, as | |
433 | needed.</p></dd><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><a name="help-text"></a>Print a short help text and exit. | |
434 | </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><a name="version-text"></a>Print a short version string and exit.</p></dd></dl></div></div><div class="refsect1"><a name="idm214180168448"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><div class="example"><a name="idm214180167808"></a><p class="title"><b>Example 1. Boot a minimal Fedora distribution in a container</b></p><div class="example-contents"><pre class="programlisting"># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal | |
663996b3 | 435 | # systemd-nspawn -bD /srv/mycontainer</pre><p>This installs a minimal Fedora distribution into |
5eef597e MP |
436 | the directory <code class="filename">/srv/mycontainer/</code> and |
437 | then boots an OS in a namespace container in | |
438 | it.</p></div></div><br class="example-break"><div class="example"><a name="idm214180164752"></a><p class="title"><b>Example 2. Spawn a shell in a container of a minimal Debian unstable distribution</b></p><div class="example-contents"><pre class="programlisting"># debootstrap --arch=amd64 unstable ~/debian-tree/ | |
663996b3 | 439 | # systemd-nspawn -D ~/debian-tree/</pre><p>This installs a minimal Debian unstable |
5eef597e MP |
440 | distribution into the directory |
441 | <code class="filename">~/debian-tree/</code> and then spawns a | |
442 | shell in a namespace container in it.</p></div></div><br class="example-break"><div class="example"><a name="idm214180162016"></a><p class="title"><b>Example 3. Boot a minimal Arch Linux distribution in a container</b></p><div class="example-contents"><pre class="programlisting"># pacstrap -c -d ~/arch-tree/ base | |
663996b3 | 443 | # systemd-nspawn -bD ~/arch-tree/</pre><p>This installs a mimimal Arch Linux distribution into |
5eef597e MP |
444 | the directory <code class="filename">~/arch-tree/</code> and then |
445 | boots an OS in a namespace container in it.</p></div></div><br class="example-break"><div class="example"><a name="idm214180159408"></a><p class="title"><b>Example 4. Enable Arch Linux container on boot</b></p><div class="example-contents"><pre class="programlisting"># mv ~/arch-tree /var/lib/container/arch | |
60f067b4 JS |
446 | # systemctl enable systemd-nspawn@arch.service |
447 | # systemctl start systemd-nspawn@arch.service</pre><p>This makes the Arch Linux container part of the | |
5eef597e MP |
448 | <code class="filename">multi-user.target</code> on the host. |
449 | </p></div></div><br class="example-break"><div class="example"><a name="idm214180156768"></a><p class="title"><b>Example 5. Boot into a btrfs snapshot of the host system</b></p><div class="example-contents"><pre class="programlisting"># btrfs subvolume snapshot / /.tmp | |
60f067b4 | 450 | # systemd-nspawn --private-network -D /.tmp -b</pre><p>This runs a copy of the host system in a |
5eef597e MP |
451 | btrfs snapshot.</p></div></div><br class="example-break"><div class="example"><a name="idm214180154800"></a><p class="title"><b>Example 6. Run a container with SELinux sandbox security contexts</b></p><div class="example-contents"><pre class="programlisting"># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container |
452 | # systemd-nspawn -L system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -Z system_u:system_r:svirt_lxc_net_t:s0:c0,c1 -D /srv/container /bin/sh</pre></div></div><br class="example-break"></div><div class="refsect1"><a name="idm214180153056"></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 | |
453 | container is returned.</p></div><div class="refsect1"><a name="idm214180151808"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p> | |
663996b3 | 454 | <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>, |
5eef597e MP |
455 | <a href="http://man7.org/linux/man-pages/man1/chroot.1.html"><span class="citerefentry"><span class="refentrytitle">chroot</span>(1)</span></a>, |
456 | <a href="http://linux.die.net/man/8/yum"><span class="citerefentry"><span class="refentrytitle">yum</span>(8)</span></a>, | |
457 | <a href="http://linux.die.net/man/8/debootstrap"><span class="citerefentry"><span class="refentrytitle">debootstrap</span>(8)</span></a>, | |
458 | <a href="https://www.archlinux.org/pacman/pacman.8.html"><span class="citerefentry"><span class="refentrytitle">pacman</span>(8)</span></a>, | |
60f067b4 JS |
459 | <a href="systemd.slice.html"><span class="citerefentry"><span class="refentrytitle">systemd.slice</span>(5)</span></a>, |
460 | <a href="machinectl.html"><span class="citerefentry"><span class="refentrytitle">machinectl</span>(1)</span></a> | |
663996b3 | 461 | </p></div></div></body></html> |