From b09c0bbad831a11e2200a6ebb48908a10ce29305 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 22 Jun 2016 23:30:36 +0200 Subject: nspawn: improve man page (#3577) This change documents the existance of the systemd-nspawn@.service template unit file, which was previously not mentioned at all. Since the unit file uses slightly different default than nspawn invoked from the command line, these defaults are now explicitly documented too. A couple of further additions and changes are made, too. Replaces: #3497 --- man/systemd-nspawn.xml | 155 ++++++++++++++++++++++++++++--------------------- man/systemd.nspawn.xml | 18 +++--- 2 files changed, 99 insertions(+), 74 deletions(-) (limited to 'man') diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 08122795f4..c436f42948 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -67,69 +67,82 @@ 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 fully 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. - - In contrast to - chroot1 systemd-nspawn - may be used to boot full Linux-based operating systems in a + 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. + + Like chroot1 the + systemd-nspawn command may be invoked on any directory tree containing an operating system tree, + using the command line option. By using the option an OS + tree is automatically searched in a couple of locations, most importantly in + /var/lib/machines, the suggested directory to place container images installed on the + system. + + In contrast to chroot1 systemd-nspawn + may be used to boot full Linux-based operating systems in a container. + + systemd-nspawn limits access to various kernel interfaces in the container to read-only, + such as /sys, /proc/sys or /sys/fs/selinux. The + host's 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. - Use a tool like - dnf8, - 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 + Use a tool like dnf8, debootstrap8, or + pacman8 to + set up an OS directory tree suitable as file system hierarchy for systemd-nspawn containers. See + the Examples section below for details on suitable invocation of these commands. + + 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. + + systemd-nspawn may be invoked directly from the interactive command line or run as system + service in the background. In this mode each container instance runs as its own service instance; a default + template unit file systemd-nspawn@.service is provided to make this easy, taking the container + name as instance identifier. Note that different default options apply when systemd-nspawn is + invoked by the template unit file than interactively on the commnd line. Most importanly the template unit file + makes use of the which is not the default in case systemd-nspawn is + invoked from the interactive command line. Further differences with the defaults are documented dalong with the + various supported options below. + + The machinectl1 tool may + be used to execute a number of operations on containers. In particular it provides easy-to-use commands to run + containers as system services using the systemd-nspawn@.service template unit + file. + + Along with each container a settings file with the .nspawn suffix may exist, containing + additional settings to apply when running the container. See + systemd.nspawn5 for + details. Settings files override the default options used by the systemd-nspawn@.service + template unit file, making it usually unnecessary to alter this template file directly. + + 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 or shell commands to request an additional login session in a running + container. + + systemd-nspawn implements the Container Interface + specification. + + While running, containers invoked with systemd-nspawn are registered with the + systemd-machined8 service that + keeps track of running containers, and provides programming interfaces to interact with them. @@ -139,7 +152,7 @@ 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 + arguments for this program. If is not used and no arguments are specified, a shell is launched in the container. @@ -310,6 +323,9 @@ + + Note that is the default mode of operation if the + systemd-nspawn@.service template unit file is used. @@ -446,7 +462,10 @@ If the kernel supports the user namespaces feature, equivalent to , otherwise equivalent to - . + . + + Note that is the default if the systemd-nspawn@.service template unit + file is used. @@ -540,6 +559,9 @@ assignment via DHCP. In case systemd-networkd is running on both the host and inside the container, automatic IP communication from the container to the host is thus available, with further connectivity to the external network. + + Note that is the default if the + systemd-nspawn@.service template unit file is used. @@ -705,7 +727,10 @@ Effectively, booting a container once with guest or host will link the journal persistently if further on the default of - auto is used. + auto is used. + + Note that is the default if the + systemd-nspawn@.service template unit file is used. @@ -981,10 +1006,10 @@ - --notify-ready= + Configures support for notifications from the container's init process. - --notify-ready= takes a boolean ( and ). + takes a boolean ( and ). With option systemd-nspawn notifies systemd with a READY=1 message when the init process is created. With option systemd-nspawn waits for the diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml index 6df4aeb2a9..b1344d6c10 100644 --- a/man/systemd.nspawn.xml +++ b/man/systemd.nspawn.xml @@ -146,7 +146,8 @@ specified parameters using Parameters= are passed as additional arguments to the init process. This setting corresponds to the switch on the systemd-nspawn command line. This option may not be combined with - ProcessTwo=yes. + ProcessTwo=yes. This option is the default if the + systemd-nspawn@.service template unit file is used. @@ -257,7 +258,8 @@ Configures support for usernamespacing. This is equivalent to the command line switch, and takes the same options. This option is privileged - (see above). + (see above). This option is the default if the systemd-nspawn@.service template unit file + is used. @@ -367,13 +369,11 @@ VirtualEthernet= - Takes a boolean argument. Configures whether - to create a virtual Ethernet connection - (veth) between host and the container. This - setting implies Private=yes. This setting - corresponds to the command - line switch. This option is privileged (see - above). + Takes a boolean argument. Configures whether to create a virtual Ethernet connection + (veth) between host and the container. This setting implies + Private=yes. This setting corresponds to the command line + switch. This option is privileged (see above). This option is the default if the + systemd-nspawn@.service template unit file is used. -- cgit v1.2.3-54-g00ecf