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 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. + 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. - 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 container. - In contrast to - chroot1 systemd-nspawn - may be used to boot full Linux-based operating systems in a + 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. + 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. - 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 + 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.