X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd-nspawn.xml;h=b991b5dd15accfb21abb20053b8b6adb9631b06d;hp=1688687948ec3770ddd5727ab709a65b7fb4f301;hb=c6c8f6e218995852350e5e35c080dec788c42c3f;hpb=b2e6df73aa508cc09b1b536a2fb9f90f152b89fa diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 168868794..b991b5dd1 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1,6 +1,6 @@ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - - - - systemd-nspawn - systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - - - - - systemd-nspawn - 1 - - - - systemd-nspawn - Spawn a namespace container for debugging, testing and building - - - - - systemd-nspawn OPTIONS COMMAND ARGS - - - - - Description - - systemd-nspawn may be used to - run a command or OS in a light-weight namespace - container. In many ways it is similar to - chroot1, - but more powerful since it fully virtualizes the file - system hierarchy, as well as the process tree, the - various IPC subsystems and the host and domain - name. - - systemd-nspawn limits access - to various kernel interfaces in the container to - read-only, such as /sys, - /proc/sys or - /sys/fs/selinux. 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. - - Note that even though these security precautions - are taken systemd-nspawn 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. - - In contrast to - chroot1 - systemd-nspawn may be used to boot - full Linux-based operating systems in a - container. - - Use a tool like - yum8 - or - debootstrap8 - to set up an OS directory tree suitable as file system - hierarchy for systemd-nspawn - containers. - - Note that systemd-nspawn will - mount file systems private to the container to - /dev, - /run and similar. These will - not be visible outside of the container, and their - contents will be lost when the container exits. - - Note that running two - systemd-nspawn containers from the - same directory tree will not make processes in them - see each other. The PID namespace separation of the - two containers is complete and the containers will - share very few runtime objects except for the - underlying file system. - - systemd-nspawn implements the - Container - Interface specification. - - - - Options - - 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: - - - - - - - Prints a short help - text and exits. - - - - - - - Directory to use as - file system root for the namespace - container. If omitted the current - directory will be - used. - - - - - - - Automatically search - for an init binary and invoke it - instead of a shell or a user supplied - program. - - - - - - - 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. - - - - - - - Set the specified uuid - for the container. The init system - will initialize - /etc/machine-id - from this if this file is not set yet. - - - - - - - - Makes the container appear in - other hierarchies than the name=systemd:/ one. - Takes a comma-separated list of controllers. - - - - - - - Turn off networking in - the container. This makes all network - interfaces unavailable in the - container, with the exception of the - loopback device. - - - - - - Mount the root file - system read only for the - container. - - - - - - List one or more - additional capabilities to grant the - container. Takes a comma separated - list of capability names, see - capabilities7 - for more information. Note that the - the following capabilities will be - granted in any way: CAP_CHOWN, - CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, - CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, - CAP_KILL, CAP_LEASE, - CAP_LINUX_IMMUTABLE, - CAP_NET_BIND_SERVICE, - CAP_NET_BROADCAST, CAP_NET_RAW, - CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, - CAP_SETUID, CAP_SYS_ADMIN, - CAP_SYS_CHROOT, CAP_SYS_NICE, - CAP_SYS_PTRACE, CAP_SYS_TTY_CONFIG, - CAP_SYS_RESOURCE, CAP_SYS_BOOT. - - - - - - Control whether the - container's journal shall be made - visible to the host system. If enabled - allows viewing the container's journal - files from the host (but not vice - versa). Takes one of - no, - host, - guest, - auto. If - no the journal is - not linked. If host - the journal files are stored on the - host file system (beneath the host's - /var/log/journal) - and a per-machine subdirectory of this - directory is created and bind mounted - into the container at the same - location. If guest - the journal files are stored on the - guest file system (beneath the guest's - /var/log/journal) - and a per-machine subdirectory of this - directory is symlinked into the host - at the same location. If - auto (the default) - and the subdirectory of - /var/log/journal - exists as directory it is bind mounted - into the container, but nothing is - done otherwise. Effectively, booting a - container once with - guest or - host will link the - journal persistently if further one - the default of auto - is used. - - - - - - Equivalent to - . - - - - - - - Example 1 - - # yum --releasever=17 --nogpgcheck --installroot ~/fedora-tree/ install yum passwd vim-minimal rootfiles systemd -# systemd-nspawn -D ~/fedora-tree /usr/lib/systemd/systemd - - This installs a minimal Fedora distribution into - the directory ~/fedora-tree/ - and then boots an OS in a namespace container in it, - with systemd as init system. - - - - Example 2 - - # debootstrap --arch=amd64 unstable ~/debian-tree/ + + + + systemd-nspawn + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd-nspawn + 1 + + + + systemd-nspawn + Spawn a namespace container for debugging, testing and building + + + + + systemd-nspawn + OPTIONS + COMMAND + ARGS + + + + systemd-nspawn + -b + OPTIONS + ARGS + + + + + Description + + systemd-nspawn may be used to run a + command or OS in a light-weight namespace container. In many ways + it is similar to + chroot1, + but more powerful since it fully virtualizes the file system + hierarchy, as well as the process tree, the various IPC subsystems + and the host and domain name. + + systemd-nspawn limits access to various + kernel interfaces in the container to read-only, such as + /sys, /proc/sys or + /sys/fs/selinux. 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. + + Note that even though these security precautions are taken + systemd-nspawn 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. + + In contrast to + chroot1 systemd-nspawn + may be used to boot full Linux-based operating systems in a + container. + + Use a tool like + dnf8, + yum8, + debootstrap8, + or + pacman8 + to set up an OS directory tree suitable as file system hierarchy + for systemd-nspawn containers. + + Note that systemd-nspawn will mount file + systems private to the container to /dev, + /run and similar. These will not be visible + outside of the container, and their contents will be lost when the + container exits. + + Note that running two systemd-nspawn + containers from the same directory tree will not make processes in + them see each other. The PID namespace separation of the two + containers is complete and the containers will share very few + runtime objects except for the underlying file system. Use + machinectl1's + login command to request an additional login + prompt in a running container. + + systemd-nspawn implements the + Container + Interface specification. + + As a safety check systemd-nspawn will + verify the existence of /usr/lib/os-release + or /etc/os-release in the container tree + before starting the container (see + os-release5). + It might be necessary to add this file to the container tree + manually if the OS of the container is too old to contain this + file out-of-the-box. + + + + Options + + If option is specified, the arguments + are used as arguments for the init binary. Otherwise, + COMMAND specifies the program to launch + in the container, and the remaining arguments are used as + arguments for this program. If is not used and + no arguments are specifed, a shell is launched in the + container. + + The following options are understood: + + + + + + + Directory to use as file system root for the + container. + + If neither , nor + is specified the directory is + determined as /var/lib/machines/ suffixed + by the machine name as specified with + . If neither + , , nor + are specified, the current + directory will be used. May not be specified together with + . + + + + + + Directory or btrfs + subvolume to use as template for the container's root + directory. If this is specified and the container's root + directory (as configured by ) + does not yet exist it is created as btrfs + subvolume and populated from this template tree. Ideally, the + specified template path refers to the root of a + btrfs subvolume, in which case a simple + copy-on-write snapshot is taken, and populating the root + directory is instant. If the specified template path does not + refer to the root of a btrfs subvolume (or + not even to a btrfs file system at all), + the tree is copied, which can be substantially more + time-consuming. Note that if this option is used the + container's root directory (in contrast to the template + directory!) must be located on a btrfs file + system, so that the btrfs subvolume may be + created. May not be specified together with + or + . + + + + + + + If specified, the container is run with a + temporary btrfs snapshot of its root + directory (as configured with ), + that is removed immediately when the container terminates. + This option is only supported if the root file system is + btrfs. May not be specified together with + or + . + + + + + + + Disk image to mount the root directory for the + container from. Takes a path to a regular file or to a block + device node. The file or block device must contain + either: + + + An MBR partition table with a single + partition of type 0x83 that is marked + bootable. + + A GUID partition table (GPT) with a single + partition of type + 0fc63daf-8483-4772-8e79-3d69d8477de4. + + A GUID partition table (GPT) with a marked + root partition which is mounted as the root directory of the + container. Optionally, GPT images may contain a home and/or + a server data partition which are mounted to the appropriate + places in the container. All these partitions must be + identified by the partition types defined by the Discoverable + Partitions Specification. + + + Any other partitions, such as foreign partitions, swap + partitions or EFI system partitions are not mounted. May not + be specified together with , + or + . + + + + + + + Automatically search for an init binary and + invoke it instead of a shell or a user supplied program. If + this option is used, arguments specified on the command line + are used as arguments for the init binary. This option may not + be combined with . + + + + + + + + After transitioning into the container, change + to the specified user-defined in the container's user + database. Like all other systemd-nspawn features, this is not + a security feature and provides protection against accidental + destructive operations only. + + + + + + + Sets the machine name for this container. This + name may be used to identify this container during its runtime + (for example in tools like + machinectl1 + and similar), and is used to initialize the container's + hostname (which the container can choose to override, + however). If not specified, the last component of the root + directory path of the container is used, possibly suffixed + with a random identifier in case + mode is selected. If the root directory selected is the host's + root directory the host's hostname is used as default + instead. + + + + + + Set the specified UUID for the container. The + init system will initialize + /etc/machine-id from this if this file is + not set yet. + + + + + + Make the container part of the specified + slice, instead of the default + machine.slice. This is only applies if + the machine is run in its own scope unit, i.e. if + is not used. + + + + + + + Set a unit property on the scope unit to + register for the machine. This only applies if the machine is + run in its own scope unit, i.e. if + is not used. Takes unit property + assignments in the same format as systemctl + set-property. This is useful to set memory limits + and similar for machines. + + + + + + + Disconnect networking of the container from + the host. This makes all network interfaces unavailable in the + container, with the exception of the loopback device and those + specified with and + configured with . If this + option is specified, the CAP_NET_ADMIN capability will be + added to the set of capabilities the container retains. The + latter may be disabled by using + . + + + + + + Assign the specified network interface to the + container. This will remove the specified interface from the + calling namespace and place it in the container. When the + container terminates, it is moved back to the host namespace. + Note that implies + . This option may be used + more than once to add multiple network interfaces to the + container. + + + + + + Create a macvlan interface + of the specified Ethernet network interface and add it to the + container. A macvlan interface is a virtual + interface that adds a second MAC address to an existing + physical Ethernet link. The interface in the container will be + named after the interface on the host, prefixed with + mv-. Note that + implies + . This option may be used + more than once to add multiple network interfaces to the + container. + + + + + + Create an ipvlan interface + of the specified Ethernet network interface and add it to the + container. An ipvlan interface is a virtual + interface, similar to a macvlan interface, + which uses the same MAC address as the underlying interface. + The interface in the container will be named after the + interface on the host, prefixed with iv-. + Note that implies + . This option may be used + more than once to add multiple network interfaces to the + container. + + + + + + + Create a virtual Ethernet link + (veth) between host and container. The host + side of the Ethernet link will be available as a network + interface named after the container's name (as specified with + ), prefixed with + ve-. The container side of the Ethernet + link will be named host0. Note that + implies + . + + + + + + Adds the host side of the Ethernet link + created with to the specified + bridge. Note that implies + . If this option is used, the + host side of the Ethernet link will use the + vb- prefix instead of + ve-. + + + + + + + If private networking is enabled, maps an IP + port on the host onto an IP port on the container. Takes a + protocol specifier (either tcp or + udp), separated by a colon from a host port + number in the range 1 to 65535, separated by a colon from a + container port number in the range from 1 to 65535. The + protocol specifier and its separating colon may be omitted, in + which case tcp is assumed. The container + port number and its colon may be ommitted, in which case the + same port as the host port is implied. This option is only + supported if private networking is used, such as + or + . + + + + + + + Sets the SELinux security context to be used + to label processes in the container. + + + + + + + + Sets the SELinux security context to be used + to label files in the virtual API file systems in the + container. + + + + + + + List one or more additional capabilities to + grant the container. Takes a comma-separated list of + capability names, see + capabilities7 + for more information. Note that the following capabilities + will be granted in any way: CAP_CHOWN, CAP_DAC_OVERRIDE, + CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_FSETID, CAP_IPC_OWNER, + CAP_KILL, CAP_LEASE, CAP_LINUX_IMMUTABLE, + CAP_NET_BIND_SERVICE, CAP_NET_BROADCAST, CAP_NET_RAW, + CAP_SETGID, CAP_SETFCAP, CAP_SETPCAP, CAP_SETUID, + CAP_SYS_ADMIN, CAP_SYS_CHROOT, CAP_SYS_NICE, CAP_SYS_PTRACE, + CAP_SYS_TTY_CONFIG, CAP_SYS_RESOURCE, CAP_SYS_BOOT, + CAP_AUDIT_WRITE, CAP_AUDIT_CONTROL. Also CAP_NET_ADMIN is + retained if is specified. + If the special value all is passed, all + capabilities are retained. + + + + + + Specify one or more additional capabilities to + drop for the container. This allows running the container with + fewer capabilities than the default (see + above). + + + + + + Specify the process signal to send to the + container's PID 1 when nspawn itself receives SIGTERM, in + order to trigger an orderly shutdown of the + container. Defaults to SIGRTMIN+3 if + is used (on systemd-compatible init systems SIGRTMIN+3 + triggers an orderly shutdown). Takes a signal name like + SIGHUP, SIGTERM or + similar as argument. + + + + + + Control whether the container's journal shall + be made visible to the host system. If enabled, allows viewing + the container's journal files from the host (but not vice + versa). Takes one of no, + host, try-host, + guest, try-guest, + auto. If no, the journal + is not linked. If host, the journal files + are stored on the host file system (beneath + /var/log/journal/machine-id) + and the subdirectory is bind-mounted into the container at the + same location. If guest, the journal files + are stored on the guest file system (beneath + /var/log/journal/machine-id) + and the subdirectory is symlinked into the host at the same + location. try-host and + try-guest do the same but do not fail if + the host does not have persistent journalling enabled. If + auto (the default), and the right + subdirectory of /var/log/journal exists, + it will be bind mounted into the container. If the + subdirectory does not exist, no linking is performed. + Effectively, booting a container once with + guest or host will link + the journal persistently if further on the default of + auto is used. + + + + + + Equivalent to + . + + + + + + Mount the root file system read-only for the + container. + + + + + + + Bind mount a file or directory from the host + into the container. Either takes a path argument -- in which + case the specified path will be mounted from the host to the + same path in the container --, or a colon-separated pair of + paths -- in which case the first specified path is the source + in the host, and the second path is the destination in the + container. The option creates + read-only bind mounts. + + + + + + Mount a tmpfs file system into the container. + Takes a single absolute path argument that specifies where to + mount the tmpfs instance to (in which case the directory + access mode will be chosen as 0755, owned by root/root), or + optionally a colon-separated pair of path and mount option + string, that is used for mounting (in which case the kernel + default for access mode and owner will be chosen, unless + otherwise specified). This option is particularly useful for + mounting directories such as /var as + tmpfs, to allow state-less systems, in particular when + combined with . + + + + + + Specifies an environment variable assignment + to pass to the init process in the container, in the format + NAME=VALUE. This may be used to override + the default variables or to set additional variables. This + parameter may be used more than once. + + + + + + Allows the container to share certain system + facilities with the host. More specifically, this turns off + PID namespacing, UTS namespacing and IPC namespacing, and thus + allows the guest to see and interact more easily with + processes outside of the container. Note that using this + option makes it impossible to start up a full Operating System + in the container, as an init system cannot operate in this + mode. It is only useful to run specific programs or + applications this way, without involving an init system in the + container. This option implies . + This option may not be combined with + . + + + + + + Controls whether the container is registered + with + systemd-machined8. + Takes a boolean argument, defaults to yes. + This option should be enabled when the container runs a full + Operating System (more specifically: an init system), and is + useful to ensure that the container is accessible via + machinectl1 + and shown by tools such as + ps1. + If the container does not run an init system, it is + recommended to set this option to no. Note + that implies + . + + + + + + Instead of creating a transient scope unit to + run the container in, simply register the service or scope + unit systemd-nspawn has been invoked in + with + systemd-machined8. + This has no effect if is used. + This switch should be used if + systemd-nspawn is invoked from within a + service unit, and the service unit's sole purpose is to run a + single systemd-nspawn container. This + option is not available if run from a user + session. + + + + + + Control the architecture ("personality") + reported by + uname2 + in the container. Currently, only x86 and + x86-64 are supported. This is useful when + running a 32-bit container on a 64-bit host. If this setting + is not used, the personality reported in the container is the + same as the one reported on the host. + + + + + + + Turns off any status output by the tool + itself. When this switch is used, the only output from nspawn + will be the console output of the container OS + itself. + + + + =MODE + + Boots the container in volatile mode. When no + mode parameter is passed or when mode is specified as + yes full volatile mode is enabled. This + means the root directory is mounted as mostly unpopulated + tmpfs instance, and + /usr from the OS tree is mounted into it, + read-only (the system thus starts up with read-only OS + resources, but pristine state and configuration, any changes + to the either are lost on shutdown). When the mode parameter + is specified as state the OS tree is + mounted read-only, but /var is mounted as + tmpfs instance into it (the system thus + starts up with read-only OS resources and configuration, but + pristine state, any changes to the latter are lost on + shutdown). When the mode parameter is specified as + no (the default) the whole OS tree is made + available writable. + + Note that setting this to yes or + state will only work correctly with + operating systems in the container that can boot up with only + /usr mounted, and are able to populate + /var automatically, as + needed. + + + + + + + + + + Examples + + + Download a Fedora image and start a shell in it + + # machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz +# systemd-nspawn -M Fedora-Cloud-Base-20141203-21 + + This downloads an image using + machinectl1 + and opens a shell in it. + + + + Build and boot a minimal Fedora distribution in a container + + # dnf -y --releasever=21 --nogpg --installroot=/srv/mycontainer --disablerepo='*' --enablerepo=fedora install systemd passwd dnf fedora-release vim-minimal +# systemd-nspawn -bD /srv/mycontainer + + This installs a minimal Fedora distribution into the + directory /srv/mycontainer/ + and then boots an OS in a namespace container in it. + + + + Spawn a shell in a container of a minimal Debian unstable distribution + + # debootstrap --arch=amd64 unstable ~/debian-tree/ # systemd-nspawn -D ~/debian-tree/ - This installs a minimal Debian unstable - distribution into the directory - ~/debian-tree/ and then spawns a - shell in a namespace container in it. - - - - - Exit status - - The exit code of the program executed in the - container is returned. - - - - See Also - - systemd1, - chroot1, - yum8, - debootstrap8 - - + This installs a minimal Debian unstable distribution into + the directory ~/debian-tree/ and then + spawns a shell in a namespace container in it. + + + + Boot a minimal Arch Linux distribution in a container + + # pacstrap -c -d ~/arch-tree/ base +# systemd-nspawn -bD ~/arch-tree/ + + This installs a mimimal Arch Linux distribution into the + directory ~/arch-tree/ and then boots an OS + in a namespace container in it. + + + + Boot into an ephemeral <literal>btrfs</literal> snapshot of the host system + + # systemd-nspawn -D / -xb + + This runs a copy of the host system in a + btrfs snapshot which is removed immediately + when the container exits. All file system changes made during + runtime will be lost on shutdown, hence. + + + + Run a container with SELinux sandbox security contexts + + # chcon system_u:object_r:svirt_sandbox_file_t:s0:c0,c1 -R /srv/container +# 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 + + + + + Exit status + + The exit code of the program executed in the container is + returned. + + + + See Also + + systemd1, + chroot1, + dnf8, + yum8, + debootstrap8, + pacman8, + systemd.slice5, + machinectl1, + btrfs8 + +