projects / thirdparty / systemd.git / blame
| Commit | Line | Data |
|---|---|---|
| 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 | |
| 5430f7f2 LP |
11 | under the terms of the GNU Lesser General Public License as published by |
| 12 | the Free Software Foundation; either version 2.1 of the License, or | |
| 8f7a3c14 LP |
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 | |
| 5430f7f2 | 18 | Lesser General Public License for more details. |
| 8f7a3c14 | 19 | |
| 5430f7f2 | 20 | You should have received a copy of the GNU Lesser General Public License |
| 8f7a3c14 LP |
21 | along with systemd; If not, see <http://www.gnu.org/licenses/>. |
| 22 | --> | |
| 23 | ||
| dfdebb1b ZJS |
24 | <refentry id="systemd-nspawn" |
| 25 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
| 8f7a3c14 LP |
26 | |
| 27 | <refentryinfo> | |
| 28 | <title>systemd-nspawn</title> | |
| 29 | <productname>systemd</productname> | |
| 30 | ||
| 31 | <authorgroup> | |
| 32 | <author> | |
| 33 | <contrib>Developer</contrib> | |
| 34 | <firstname>Lennart</firstname> | |
| 35 | <surname>Poettering</surname> | |
| 36 | <email>lennart@poettering.net</email> | |
| 37 | </author> | |
| 38 | </authorgroup> | |
| 39 | </refentryinfo> | |
| 40 | ||
| 41 | <refmeta> | |
| 42 | <refentrytitle>systemd-nspawn</refentrytitle> | |
| 43 | <manvolnum>1</manvolnum> | |
| 44 | </refmeta> | |
| 45 | ||
| 46 | <refnamediv> | |
| 47 | <refname>systemd-nspawn</refname> | |
| 48 | <refpurpose>Spawn a namespace container for debugging, testing and building</refpurpose> | |
| 49 | </refnamediv> | |
| 50 | ||
| 51 | <refsynopsisdiv> | |
| 52 | <cmdsynopsis> | |
| 1fd96121 ZJS |
53 | <command>systemd-nspawn</command> |
| 54 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
| 870c4365 ZJS |
55 | <arg choice="opt"><replaceable>COMMAND</replaceable> |
| 56 | <arg choice="opt" rep="repeat">ARGS</arg> | |
| 57 | </arg> | |
| 58 | </cmdsynopsis> | |
| 59 | <cmdsynopsis> | |
| 60 | <command>systemd-nspawn</command> | |
| 61 | <arg choice="plain">-b</arg> | |
| 62 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
| 1fd96121 | 63 | <arg choice="opt" rep="repeat">ARGS</arg> |
| 8f7a3c14 LP |
64 | </cmdsynopsis> |
| 65 | </refsynopsisdiv> | |
| 66 | ||
| 67 | <refsect1> | |
| 68 | <title>Description</title> | |
| 69 | ||
| 70 | <para><command>systemd-nspawn</command> may be used to | |
| 71 | run a command or OS in a light-weight namespace | |
| 72 | container. In many ways it is similar to | |
| 5aded369 | 73 | <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| 8f7a3c14 | 74 | but more powerful since it fully virtualizes the file |
| 9f7dad77 | 75 | system hierarchy, as well as the process tree, the |
| 8f7a3c14 LP |
76 | various IPC subsystems and the host and domain |
| 77 | name.</para> | |
| 78 | ||
| 79 | <para><command>systemd-nspawn</command> limits access | |
| 80 | to various kernel interfaces in the container to | |
| 81 | read-only, such as <filename>/sys</filename>, | |
| 82 | <filename>/proc/sys</filename> or | |
| 4f755fc6 LP |
83 | <filename>/sys/fs/selinux</filename>. Network |
| 84 | interfaces and the system clock may not be changed | |
| 85 | from within the container. Device nodes may not be | |
| 86 | created. The host system cannot be rebooted and kernel | |
| 87 | modules may not be loaded from within the | |
| 88 | container.</para> | |
| 8f7a3c14 LP |
89 | |
| 90 | <para>Note that even though these security precautions | |
| 91 | are taken <command>systemd-nspawn</command> is not | |
| 92 | suitable for secure container setups. Many of the | |
| 93 | security features may be circumvented and are hence | |
| 94 | primarily useful to avoid accidental changes to the | |
| 95 | host system from the container. The intended use of | |
| 96 | this program is debugging and testing as well as | |
| 97 | building of packages, distributions and software | |
| 98 | involved with boot and systems management.</para> | |
| 99 | ||
| 100 | <para>In contrast to | |
| 5aded369 | 101 | <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry> <command>systemd-nspawn</command> |
| 04ac7992 ZJS |
102 | may be used to boot full Linux-based operating systems |
| 103 | in a container.</para> | |
| 8f7a3c14 LP |
104 | |
| 105 | <para>Use a tool like | |
| 5aded369 ZJS |
106 | <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| 107 | <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
| 4d62fb42 | 108 | or |
| 5aded369 | 109 | <citerefentry project='arch'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
| 8f7a3c14 | 110 | to set up an OS directory tree suitable as file system |
| 25f5971b LP |
111 | hierarchy for <command>systemd-nspawn</command> |
| 112 | containers.</para> | |
| 8f7a3c14 LP |
113 | |
| 114 | <para>Note that <command>systemd-nspawn</command> will | |
| 115 | mount file systems private to the container to | |
| 116 | <filename>/dev</filename>, | |
| 2b583ce6 | 117 | <filename>/run</filename> and similar. These will |
| 8f7a3c14 LP |
118 | not be visible outside of the container, and their |
| 119 | contents will be lost when the container exits.</para> | |
| 120 | ||
| 121 | <para>Note that running two | |
| 122 | <command>systemd-nspawn</command> containers from the | |
| 123 | same directory tree will not make processes in them | |
| 9f7dad77 | 124 | see each other. The PID namespace separation of the |
| 8f7a3c14 LP |
125 | two containers is complete and the containers will |
| 126 | share very few runtime objects except for the | |
| 04d39279 LP |
127 | underlying file system. Use |
| 128 | <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s | |
| 129 | <command>login</command> command to request an | |
| 130 | additional login prompt in a running container.</para> | |
| 99800333 LP |
131 | |
| 132 | <para><command>systemd-nspawn</command> implements the | |
| 133 | <ulink | |
| 134 | url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container | |
| 135 | Interface</ulink> specification.</para> | |
| f8964235 LP |
136 | |
| 137 | <para>As a safety check | |
| 138 | <command>systemd-nspawn</command> will verify the | |
| 5ae4d543 LP |
139 | existence of <filename>/usr/lib/os-release</filename> |
| 140 | or <filename>/etc/os-release</filename> in the | |
| 141 | container tree before starting the container (see | |
| f8964235 LP |
142 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>). It |
| 143 | might be necessary to add this file to the container | |
| 144 | tree manually if the OS of the container is too old to | |
| 145 | contain this file out-of-the-box.</para> | |
| 77b6e194 LP |
146 | </refsect1> |
| 147 | ||
| 8f7a3c14 LP |
148 | <refsect1> |
| 149 | <title>Options</title> | |
| 150 | ||
| 870c4365 ZJS |
151 | <para>If option <option>-b</option> is specified, the |
| 152 | arguments are used as arguments for the init | |
| 153 | binary. Otherwise, <replaceable>COMMAND</replaceable> | |
| 154 | specifies the program to launch in the container, and | |
| 155 | the remaining arguments are used as arguments for this | |
| 156 | program. If <option>-b</option> is not used and no | |
| 157 | arguments are specifed, a shell is launched in the | |
| 158 | container.</para> | |
| 159 | ||
| 160 | <para>The following options are understood:</para> | |
| 8f7a3c14 LP |
161 | |
| 162 | <variablelist> | |
| 8f7a3c14 | 163 | <varlistentry> |
| ab1f0633 | 164 | <term><option>-D</option></term> |
| a7f5bb1e | 165 | <term><option>--directory=</option></term> |
| 8f7a3c14 LP |
166 | |
| 167 | <listitem><para>Directory to use as | |
| 1b9e5b12 LP |
168 | file system root for the container. If |
| 169 | neither <option>--directory=</option> | |
| 170 | nor <option>--image=</option> are | |
| 171 | specified, the current directory will | |
| 172 | be used. May not be specified together with | |
| 173 | <option>--image=</option>.</para></listitem> | |
| 174 | </varlistentry> | |
| 175 | ||
| 176 | <varlistentry> | |
| 177 | <term><option>-i</option></term> | |
| 178 | <term><option>--image=</option></term> | |
| 179 | ||
| 180 | <listitem><para>Disk image to mount | |
| 181 | the root directory for the container | |
| 182 | from. Takes a path to a regular file | |
| 183 | or to a block device node. The file or | |
| 184 | block device must contain a GUID | |
| 185 | Partition Table with a root partition | |
| 186 | which is mounted as the root directory | |
| 187 | of the container. Optionally, it may | |
| 188 | contain a home and/or a server data | |
| 189 | partition which are mounted to the | |
| 190 | appropriate places in the | |
| 191 | container. All these partitions must | |
| 192 | be identified by the partition types | |
| 193 | defined by the <ulink | |
| 194 | url="http://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable | |
| 195 | Partitions Specification</ulink>. Any | |
| 196 | other partitions, such as foreign | |
| 197 | partitions, swap partitions or EFI | |
| 198 | system partitions are not mounted. May | |
| 199 | not be specified together with | |
| 200 | <option>--directory=</option>.</para></listitem> | |
| 8f7a3c14 LP |
201 | </varlistentry> |
| 202 | ||
| 0f0dbc46 | 203 | <varlistentry> |
| 0f0dbc46 | 204 | <term><option>-b</option></term> |
| a7f5bb1e | 205 | <term><option>--boot</option></term> |
| 0f0dbc46 LP |
206 | |
| 207 | <listitem><para>Automatically search | |
| 208 | for an init binary and invoke it | |
| 209 | instead of a shell or a user supplied | |
| eb91eb18 LP |
210 | program. If this option is used, |
| 211 | arguments specified on the command | |
| 212 | line are used as arguments for the | |
| 213 | init binary. This option may not be | |
| 214 | combined with | |
| 215 | <option>--share-system</option>. | |
| 870c4365 | 216 | </para></listitem> |
| 0f0dbc46 LP |
217 | </varlistentry> |
| 218 | ||
| 687d0825 | 219 | <varlistentry> |
| 4f755fc6 | 220 | <term><option>-u</option></term> |
| a7f5bb1e | 221 | <term><option>--user=</option></term> |
| 687d0825 | 222 | |
| 1810e3dc LP |
223 | <listitem><para>After transitioning |
| 224 | into the container, change to the | |
| 70a44afe | 225 | specified user-defined in the |
| 1810e3dc LP |
226 | container's user database. Like all |
| 227 | other systemd-nspawn features, this is | |
| 228 | not a security feature and provides | |
| 229 | protection against accidental | |
| 230 | destructive operations | |
| 231 | only.</para></listitem> | |
| 687d0825 MV |
232 | </varlistentry> |
| 233 | ||
| 7027ff61 LP |
234 | <varlistentry> |
| 235 | <term><option>-M</option></term> | |
| 236 | <term><option>--machine=</option></term> | |
| 237 | ||
| 238 | <listitem><para>Sets the machine name | |
| 239 | for this container. This name may be | |
| 240 | used to identify this container on the | |
| 241 | host, and is used to initialize the | |
| 242 | container's hostname (which the | |
| 243 | container can choose to override, | |
| 79640424 | 244 | however). If not specified, the last |
| 7027ff61 LP |
245 | component of the root directory of the |
| 246 | container is used.</para></listitem> | |
| 247 | </varlistentry> | |
| 248 | ||
| 144f0fc0 LP |
249 | <varlistentry> |
| 250 | <term><option>--uuid=</option></term> | |
| 251 | ||
| e9dd9f95 | 252 | <listitem><para>Set the specified UUID |
| 144f0fc0 LP |
253 | for the container. The init system |
| 254 | will initialize | |
| 255 | <filename>/etc/machine-id</filename> | |
| 256 | from this if this file is not set yet. | |
| 257 | </para></listitem> | |
| 258 | </varlistentry> | |
| 259 | ||
| 69c79d3c LP |
260 | <varlistentry> |
| 261 | <term><option>--slice=</option></term> | |
| 262 | ||
| 263 | <listitem><para>Make the container | |
| 264 | part of the specified slice, instead | |
| 265 | of the default | |
| 266 | <filename>machine.slice</filename>.</para> | |
| 267 | </listitem> | |
| 268 | </varlistentry> | |
| 269 | ||
| a41fe3a2 | 270 | <varlistentry> |
| ff01d048 | 271 | <term><option>--private-network</option></term> |
| a41fe3a2 | 272 | |
| 69c79d3c LP |
273 | <listitem><para>Disconnect networking |
| 274 | of the container from the host. This | |
| 275 | makes all network interfaces | |
| 276 | unavailable in the container, with the | |
| 277 | exception of the loopback device and | |
| 278 | those specified with | |
| 279 | <option>--network-interface=</option> | |
| ab046dde | 280 | and configured with |
| 69c79d3c | 281 | <option>--network-veth</option>. If |
| 73e231ab | 282 | this option is specified, the |
| a42c8b54 LP |
283 | CAP_NET_ADMIN capability will be added |
| 284 | to the set of capabilities the | |
| 285 | container retains. The latter may be | |
| 286 | disabled by using | |
| 287 | <option>--drop-capability=</option>.</para></listitem> | |
| a41fe3a2 LP |
288 | </varlistentry> |
| 289 | ||
| aa28aefe LP |
290 | <varlistentry> |
| 291 | <term><option>--network-interface=</option></term> | |
| 292 | ||
| 293 | <listitem><para>Assign the specified | |
| 294 | network interface to the | |
| c74e630d | 295 | container. This will remove the |
| aa28aefe LP |
296 | specified interface from the calling |
| 297 | namespace and place it in the | |
| 298 | container. When the container | |
| 73e231ab | 299 | terminates, it is moved back to the |
| a42c8b54 LP |
300 | host namespace. Note that |
| 301 | <option>--network-interface=</option> | |
| 302 | implies | |
| 303 | <option>--private-network</option>. This | |
| 304 | option may be used more than once to | |
| 305 | add multiple network interfaces to the | |
| 306 | container.</para></listitem> | |
| aa28aefe LP |
307 | </varlistentry> |
| 308 | ||
| c74e630d LP |
309 | <varlistentry> |
| 310 | <term><option>--network-macvlan=</option></term> | |
| 311 | ||
| 312 | <listitem><para>Create a | |
| 313 | <literal>macvlan</literal> interface | |
| 314 | of the specified Ethernet network | |
| 315 | interface and add it to the | |
| 316 | container. A | |
| 317 | <literal>macvlan</literal> interface | |
| 318 | is a virtual interface that adds a | |
| 319 | second MAC address to an existing | |
| 320 | physical Ethernet link. The interface | |
| 321 | in the container will be named after | |
| 322 | the interface on the host, prefixed | |
| 323 | with <literal>mv-</literal>. Note that | |
| 324 | <option>--network-macvlan=</option> | |
| 325 | implies | |
| 326 | <option>--private-network</option>. This | |
| 327 | option may be used more than once to | |
| 328 | add multiple network interfaces to the | |
| 329 | container.</para></listitem> | |
| 330 | </varlistentry> | |
| 331 | ||
| bc2f673e | 332 | <varlistentry> |
| 69c79d3c LP |
333 | <term><option>--network-veth</option></term> |
| 334 | ||
| 335 | <listitem><para>Create a virtual | |
| c74e630d LP |
336 | Ethernet link |
| 337 | (<literal>veth</literal>) between host | |
| 338 | and container. The host side of the | |
| 66f756d4 | 339 | Ethernet link will be available as a |
| 69c79d3c LP |
340 | network interface named after the |
| 341 | container's name (as specified with | |
| 342 | <option>--machine=</option>), prefixed | |
| 343 | with <literal>ve-</literal>. The | |
| dca348bc | 344 | container side of the Ethernet |
| 69c79d3c LP |
345 | link will be named |
| 346 | <literal>host0</literal>. Note that | |
| 347 | <option>--network-veth</option> | |
| 348 | implies | |
| 349 | <option>--private-network</option>.</para></listitem> | |
| 350 | </varlistentry> | |
| bc2f673e | 351 | |
| ab046dde TG |
352 | <varlistentry> |
| 353 | <term><option>--network-bridge=</option></term> | |
| 354 | ||
| 08af0da2 LP |
355 | <listitem><para>Adds the host side of |
| 356 | the Ethernet link created with | |
| 357 | <option>--network-veth</option> to the | |
| 358 | specified bridge. Note that | |
| 359 | <option>--network-bridge=</option> | |
| ab046dde | 360 | implies |
| 08af0da2 | 361 | <option>--network-veth</option>. If |
| b8bde116 | 362 | this option is used, the host side of |
| 08af0da2 LP |
363 | the Ethernet link will use the |
| 364 | <literal>vb-</literal> prefix instead | |
| 365 | of <literal>ve-</literal>.</para></listitem> | |
| ab046dde TG |
366 | </varlistentry> |
| 367 | ||
| 69c79d3c LP |
368 | <varlistentry> |
| 369 | <term><option>-Z</option></term> | |
| 370 | <term><option>--selinux-context=</option></term> | |
| 371 | ||
| 372 | <listitem><para>Sets the SELinux | |
| 373 | security context to be used to label | |
| 374 | processes in the container.</para> | |
| 375 | </listitem> | |
| 376 | </varlistentry> | |
| 377 | ||
| 378 | <varlistentry> | |
| 379 | <term><option>-L</option></term> | |
| 380 | <term><option>--selinux-apifs-context=</option></term> | |
| 381 | ||
| 382 | <listitem><para>Sets the SELinux security | |
| 383 | context to be used to label files in | |
| 384 | the virtual API file systems in the | |
| 385 | container.</para> | |
| 386 | </listitem> | |
| bc2f673e LP |
387 | </varlistentry> |
| 388 | ||
| 5076f0cc LP |
389 | <varlistentry> |
| 390 | <term><option>--capability=</option></term> | |
| 391 | ||
| 392 | <listitem><para>List one or more | |
| 393 | additional capabilities to grant the | |
| e9dd9f95 | 394 | container. Takes a comma-separated |
| 5076f0cc | 395 | list of capability names, see |
| 5aded369 | 396 | <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> |
| 5076f0cc | 397 | for more information. Note that the |
| 88d04e31 LP |
398 | following capabilities will be granted |
| 399 | in any way: CAP_CHOWN, | |
| 5076f0cc LP |
400 | CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, |
| 401 | CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, | |
| 402 | CAP_KILL, CAP_LEASE, | |
| 403 | CAP_LINUX_IMMUTABLE, | |
| 404 | CAP_NET_BIND_SERVICE, | |
| 405 | CAP_NET_BROADCAST, CAP_NET_RAW, | |
| 406 | CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, | |
| 407 | CAP_SETUID, CAP_SYS_ADMIN, | |
| 408 | CAP_SYS_CHROOT, CAP_SYS_NICE, | |
| 409 | CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG, | |
| 88d04e31 | 410 | CAP_SYS_RESOURCE, CAP_SYS_BOOT, |
| a42c8b54 LP |
411 | CAP_AUDIT_WRITE, |
| 412 | CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN | |
| 413 | is retained if | |
| 414 | <option>--private-network</option> is | |
| 415 | specified. If the special value | |
| 73e231ab | 416 | <literal>all</literal> is passed, all |
| 39ed67d1 LP |
417 | capabilities are |
| 418 | retained.</para></listitem> | |
| 5076f0cc LP |
419 | </varlistentry> |
| 420 | ||
| 420c7379 LP |
421 | <varlistentry> |
| 422 | <term><option>--drop-capability=</option></term> | |
| 423 | ||
| 424 | <listitem><para>Specify one or more | |
| 425 | additional capabilities to drop for | |
| 426 | the container. This allows running the | |
| 427 | container with fewer capabilities than | |
| 428 | the default (see above).</para></listitem> | |
| 429 | </varlistentry> | |
| 430 | ||
| 57fb9fb5 LP |
431 | <varlistentry> |
| 432 | <term><option>--link-journal=</option></term> | |
| 433 | ||
| 434 | <listitem><para>Control whether the | |
| 435 | container's journal shall be made | |
| 79640424 | 436 | visible to the host system. If enabled, |
| 57fb9fb5 LP |
437 | allows viewing the container's journal |
| 438 | files from the host (but not vice | |
| 439 | versa). Takes one of | |
| 440 | <literal>no</literal>, | |
| 441 | <literal>host</literal>, | |
| 442 | <literal>guest</literal>, | |
| 443 | <literal>auto</literal>. If | |
| 27407a01 ZJS |
444 | <literal>no</literal>, the journal is |
| 445 | not linked. If <literal>host</literal>, | |
| 57fb9fb5 | 446 | the journal files are stored on the |
| 27407a01 | 447 | host file system (beneath |
| e670b166 | 448 | <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>) |
| 27407a01 | 449 | and the subdirectory is bind-mounted |
| 57fb9fb5 | 450 | into the container at the same |
| 27407a01 | 451 | location. If <literal>guest</literal>, |
| 57fb9fb5 | 452 | the journal files are stored on the |
| 27407a01 | 453 | guest file system (beneath |
| e670b166 | 454 | <filename>/var/log/journal/<replaceable>machine-id</replaceable></filename>) |
| 27407a01 | 455 | and the subdirectory is symlinked into the host |
| 57fb9fb5 | 456 | at the same location. If |
| 27407a01 ZJS |
457 | <literal>auto</literal> (the default), |
| 458 | and the right subdirectory of | |
| 57fb9fb5 | 459 | <filename>/var/log/journal</filename> |
| 27407a01 ZJS |
460 | exists, it will be bind mounted |
| 461 | into the container. If the | |
| 6b4991cf | 462 | subdirectory does not exist, no |
| 27407a01 ZJS |
463 | linking is performed. Effectively, |
| 464 | booting a container once with | |
| 57fb9fb5 LP |
465 | <literal>guest</literal> or |
| 466 | <literal>host</literal> will link the | |
| 27407a01 | 467 | journal persistently if further on |
| 57fb9fb5 LP |
468 | the default of <literal>auto</literal> |
| 469 | is used.</para></listitem> | |
| 470 | </varlistentry> | |
| 471 | ||
| 472 | <varlistentry> | |
| 473 | <term><option>-j</option></term> | |
| 474 | ||
| 475 | <listitem><para>Equivalent to | |
| 476 | <option>--link-journal=guest</option>.</para></listitem> | |
| 477 | </varlistentry> | |
| 17fe0523 | 478 | |
| 69c79d3c LP |
479 | <varlistentry> |
| 480 | <term><option>--read-only</option></term> | |
| 481 | ||
| 482 | <listitem><para>Mount the root file | |
| 483 | system read-only for the | |
| 484 | container.</para></listitem> | |
| 485 | </varlistentry> | |
| 486 | ||
| 17fe0523 LP |
487 | <varlistentry> |
| 488 | <term><option>--bind=</option></term> | |
| 489 | <term><option>--bind-ro=</option></term> | |
| 490 | ||
| 491 | <listitem><para>Bind mount a file or | |
| 492 | directory from the host into the | |
| 493 | container. Either takes a path | |
| 494 | argument -- in which case the | |
| 495 | specified path will be mounted from | |
| 496 | the host to the same path in the | |
| 497 | container --, or a colon-separated | |
| 498 | pair of paths -- in which case the | |
| 499 | first specified path is the source in | |
| 500 | the host, and the second path is the | |
| 501 | destination in the container. The | |
| 502 | <option>--bind-ro=</option> option | |
| 503 | creates read-only bind | |
| 08af0da2 | 504 | mounts.</para></listitem> |
| 17fe0523 | 505 | </varlistentry> |
| f4889f65 | 506 | |
| 06c17c39 LP |
507 | <varlistentry> |
| 508 | <term><option>--tmpfs=</option></term> | |
| 509 | ||
| 510 | <listitem><para>Mount a tmpfs file | |
| 511 | system into the container. Takes a | |
| 512 | single absolute path argument that | |
| 513 | specifies where to mount the tmpfs | |
| 514 | instance to (in which case the | |
| 515 | directory access mode will be chosen | |
| 516 | as 0755, owned by root/root), or | |
| 517 | optionally a colon-separated pair of | |
| 518 | path and mount option string, that is | |
| 519 | used for mounting (in which case the | |
| 520 | kernel default for access mode and | |
| 521 | owner will be chosen, unless otherwise | |
| 522 | specified). This option is | |
| 523 | particularly useful for mounting | |
| 524 | directories such as | |
| 525 | <filename>/var</filename> as tmpfs, to | |
| 526 | allow state-less systems, in | |
| 527 | particular when combined with | |
| 528 | <option>--read-only</option>.</para></listitem> | |
| 529 | </varlistentry> | |
| 530 | ||
| f4889f65 LP |
531 | <varlistentry> |
| 532 | <term><option>--setenv=</option></term> | |
| 533 | ||
| 534 | <listitem><para>Specifies an | |
| 535 | environment variable assignment to | |
| 536 | pass to the init process in the | |
| 537 | container, in the format | |
| 538 | <literal>NAME=VALUE</literal>. This | |
| 539 | may be used to override the default | |
| 540 | variables or to set additional | |
| 541 | variables. This parameter may be used | |
| 542 | more than once.</para></listitem> | |
| 543 | </varlistentry> | |
| 544 | ||
| 8a96d94e LP |
545 | <varlistentry> |
| 546 | <term><option>--share-system</option></term> | |
| 547 | ||
| 548 | <listitem><para>Allows the container | |
| 549 | to share certain system facilities | |
| 550 | with the host. More specifically, this | |
| 551 | turns off PID namespacing, UTS | |
| 552 | namespacing and IPC namespacing, and | |
| 553 | thus allows the guest to see and | |
| 554 | interact more easily with processes | |
| 555 | outside of the container. Note that | |
| 556 | using this option makes it impossible | |
| eb91eb18 LP |
557 | to start up a full Operating System in |
| 558 | the container, as an init system | |
| 559 | cannot operate in this mode. It is | |
| 560 | only useful to run specific programs | |
| 561 | or applications this way, without | |
| 562 | involving an init system in the | |
| 563 | container. This option implies | |
| 564 | <option>--register=no</option>. This | |
| 565 | option may not be combined with | |
| 566 | <option>--boot</option>.</para></listitem> | |
| 8a96d94e LP |
567 | </varlistentry> |
| 568 | ||
| eb91eb18 LP |
569 | <varlistentry> |
| 570 | <term><option>--register=</option></term> | |
| 571 | ||
| 572 | <listitem><para>Controls whether the | |
| 573 | container is registered with | |
| 574 | <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Takes | |
| 575 | a boolean argument, defaults to | |
| 576 | <literal>yes</literal>. This option | |
| 577 | should be enabled when the container | |
| 578 | runs a full Operating System (more | |
| 579 | specifically: an init system), and is | |
| 89f7c846 LP |
580 | useful to ensure that the container is |
| 581 | accessible via | |
| eb91eb18 LP |
582 | <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| 583 | and shown by tools such as | |
| 5aded369 | 584 | <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If |
| eb91eb18 | 585 | the container does not run an init |
| 73e231ab | 586 | system, it is recommended to set this |
| eb91eb18 LP |
587 | option to <literal>no</literal>. Note |
| 588 | that <option>--share-system</option> | |
| 589 | implies | |
| 590 | <option>--register=no</option>. | |
| 591 | </para></listitem> | |
| 592 | </varlistentry> | |
| 89f7c846 LP |
593 | |
| 594 | <varlistentry> | |
| 595 | <term><option>--keep-unit</option></term> | |
| 596 | ||
| 597 | <listitem><para>Instead of creating a | |
| 598 | transient scope unit to run the | |
| 599 | container in, simply register the | |
| 600 | service or scope unit | |
| 601 | <command>systemd-nspawn</command> has | |
| 66f756d4 | 602 | been invoked in with |
| 89f7c846 LP |
603 | <citerefentry><refentrytitle>systemd-machined</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This |
| 604 | has no effect if | |
| 605 | <option>--register=no</option> is | |
| 606 | used. This switch should be used if | |
| 607 | <command>systemd-nspawn</command> is | |
| 66f756d4 | 608 | invoked from within a service unit, |
| 89f7c846 LP |
609 | and the service unit's sole purpose |
| 610 | is to run a single | |
| 611 | <command>systemd-nspawn</command> | |
| 612 | container. This option is not | |
| 613 | available if run from a user | |
| 614 | session.</para></listitem> | |
| 615 | </varlistentry> | |
| 616 | ||
| 6afc95b7 LP |
617 | <varlistentry> |
| 618 | <term><option>--personality=</option></term> | |
| 619 | ||
| 620 | <listitem><para>Control the | |
| 621 | architecture ("personality") reported | |
| 622 | by | |
| 623 | <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 624 | in the container. Currently, only | |
| 625 | <literal>x86</literal> and | |
| 626 | <literal>x86-64</literal> are | |
| 627 | supported. This is useful when running | |
| 70a44afe | 628 | a 32-bit container on a 64-bit |
| b8bde116 | 629 | host. If this setting is not used, |
| 6afc95b7 LP |
630 | the personality reported in the |
| 631 | container is the same as the one | |
| 632 | reported on the | |
| 633 | host.</para></listitem> | |
| 634 | </varlistentry> | |
| dfdebb1b ZJS |
635 | |
| 636 | <varlistentry> | |
| 637 | <term><option>-q</option></term> | |
| 638 | <term><option>--quiet</option></term> | |
| 639 | ||
| 640 | <listitem><para>Turns off any status | |
| 641 | output by the tool itself. When this | |
| 642 | switch is used, the only output | |
| 643 | from nspawn will be the console output | |
| 644 | of the container OS itself.</para></listitem> | |
| 645 | </varlistentry> | |
| 646 | ||
| 108e8cd1 LP |
647 | <varlistentry> |
| 648 | <term><option>--volatile</option><replaceable>=MODE</replaceable></term> | |
| 649 | ||
| 650 | <listitem><para>Boots the container in | |
| 651 | volatile (ephemeral) mode. When no | |
| 652 | mode parameter is passed or when mode | |
| 653 | is specified as <literal>yes</literal> | |
| 654 | full volatile mode is enabled. This | |
| 655 | means the root directory is mounted as | |
| 656 | mostly unpopulated | |
| 657 | <literal>tmpfs</literal> instance, and | |
| 658 | <filename>/usr</filename> from the OS | |
| 659 | tree is mounted into it, read-only | |
| 660 | (the system thus starts up with | |
| 661 | read-only OS resources, but pristine | |
| 662 | state and configuration, any changes | |
| 663 | to the either are lost on | |
| 664 | shutdown). When the mode parameter is | |
| 665 | specified as <literal>state</literal> | |
| 666 | the OS tree is mounted read-only, but | |
| 667 | <filename>/var</filename> is mounted | |
| 668 | as <literal>tmpfs</literal> instance | |
| 669 | into it (the system thus starts up | |
| 670 | with read-only OS resources and | |
| 06b643e7 | 671 | configuration, but pristine state, any |
| 108e8cd1 LP |
672 | changes to the latter are lost on |
| 673 | shutdown). When the mode parameter is | |
| 674 | specified as <literal>no</literal> | |
| 675 | (the default) the whole OS tree is made | |
| 676 | available writable.</para> | |
| 677 | ||
| 678 | <para>Note that setting this to | |
| 679 | <literal>yes</literal> or | |
| 680 | <literal>state</literal> will only | |
| 681 | work correctly with operating systems | |
| 682 | in the container that can boot up with | |
| 683 | only <filename>/usr</filename> | |
| 684 | mounted, and are able to populate | |
| 685 | <filename>/var</filename> | |
| 686 | automatically, as | |
| 687 | needed.</para></listitem> | |
| 688 | </varlistentry> | |
| 689 | ||
| dfdebb1b ZJS |
690 | <xi:include href="standard-options.xml" xpointer="help" /> |
| 691 | <xi:include href="standard-options.xml" xpointer="version" /> | |
| 8f7a3c14 LP |
692 | </variablelist> |
| 693 | ||
| 694 | </refsect1> | |
| 695 | ||
| 696 | <refsect1> | |
| 697 | <title>Example 1</title> | |
| 698 | ||
| 2b3987a8 LP |
699 | <programlisting># yum -y --releasever=19 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal |
| 700 | # systemd-nspawn -bD /srv/mycontainer</programlisting> | |
| 8f7a3c14 | 701 | |
| 25f5971b | 702 | <para>This installs a minimal Fedora distribution into |
| 845c5324 | 703 | the directory <filename noindex='true'>/srv/mycontainer/</filename> and |
| 2b3987a8 LP |
704 | then boots an OS in a namespace container in |
| 705 | it.</para> | |
| 8f7a3c14 LP |
706 | </refsect1> |
| 707 | ||
| 708 | <refsect1> | |
| 709 | <title>Example 2</title> | |
| 710 | ||
| 25f5971b LP |
711 | <programlisting># debootstrap --arch=amd64 unstable ~/debian-tree/ |
| 712 | # systemd-nspawn -D ~/debian-tree/</programlisting> | |
| 8f7a3c14 | 713 | |
| 25f5971b LP |
714 | <para>This installs a minimal Debian unstable |
| 715 | distribution into the directory | |
| 716 | <filename>~/debian-tree/</filename> and then spawns a | |
| 717 | shell in a namespace container in it.</para> | |
| 8f7a3c14 LP |
718 | </refsect1> |
| 719 | ||
| 68562936 WG |
720 | <refsect1> |
| 721 | <title>Example 3</title> | |
| 722 | ||
| 723 | <programlisting># pacstrap -c -d ~/arch-tree/ base | |
| 724 | # systemd-nspawn -bD ~/arch-tree/</programlisting> | |
| 725 | ||
| 726 | <para>This installs a mimimal Arch Linux distribution into | |
| 727 | the directory <filename>~/arch-tree/</filename> and then | |
| 728 | boots an OS in a namespace container in it.</para> | |
| 729 | </refsect1> | |
| 730 | ||
| 9cb74bcb ZJS |
731 | <refsect1> |
| 732 | <title>Example 4</title> | |
| 733 | ||
| 734 | <programlisting># mv ~/arch-tree /var/lib/container/arch | |
| 735 | # systemctl enable systemd-nspawn@arch.service | |
| 736 | # systemctl start systemd-nspawn@arch.service</programlisting> | |
| 737 | ||
| 738 | <para>This makes the Arch Linux container part of the | |
| 739 | <filename>multi-user.target</filename> on the host. | |
| 740 | </para> | |
| 741 | </refsect1> | |
| 742 | ||
| f9f4dd51 ZJS |
743 | <refsect1> |
| 744 | <title>Example 5</title> | |
| 745 | ||
| 746 | <programlisting># btrfs subvolume snapshot / /.tmp | |
| 747 | # systemd-nspawn --private-network -D /.tmp -b</programlisting> | |
| 748 | ||
| 749 | <para>This runs a copy of the host system in a | |
| 750 | btrfs snapshot.</para> | |
| 751 | </refsect1> | |
| 752 | ||
| a8828ed9 DW |
753 | <refsect1> |
| 754 | <title>Example 6</title> | |
| 755 | ||
| 756 | <programlisting># chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container | |
| 757 | # 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</programlisting> | |
| 758 | ||
| 82adf6af | 759 | <para>This runs a container with SELinux sandbox security contexts.</para> |
| a8828ed9 | 760 | </refsect1> |
| f9f4dd51 | 761 | |
| 8f7a3c14 LP |
762 | <refsect1> |
| 763 | <title>Exit status</title> | |
| 764 | ||
| 765 | <para>The exit code of the program executed in the | |
| 766 | container is returned.</para> | |
| 767 | </refsect1> | |
| 768 | ||
| 769 | <refsect1> | |
| 770 | <title>See Also</title> | |
| 771 | <para> | |
| 772 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
| 5aded369 ZJS |
773 | <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| 774 | <citerefentry project='die-net'><refentrytitle>yum</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
| 775 | <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
| 776 | <citerefentry project='arch'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
| 04d39279 LP |
777 | <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| 778 | <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
| 8f7a3c14 LP |
779 | </para> |
| 780 | </refsect1> | |
| 781 | ||
| 782 | </refentry> |