diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index f0a5231acf..5ed49e6587 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -167,9 +167,9 @@ 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 (though possibly in a copy-on-write scheme — if the file system supports that), which - can be substantially more time-consuming. May not be specified together with or - . + all), the tree is copied (though possibly in a 'reflink' copy-on-write scheme — if the file system supports + that), which can be substantially more time-consuming. May not be specified together with + or . Note that this switch leaves host name, machine ID and all other settings that could identify the instance @@ -183,9 +183,16 @@ If specified, the container is run with a temporary snapshot of its file system that is removed immediately when the container terminates. May not be specified together with . - Note that this switch leaves host name, machine ID and - all other settings that could identify the instance - unmodified. + Note that this switch leaves host name, machine ID and all other settings that could identify the + instance unmodified. Please note that — as with — taking the temporary snapshot is + more efficient on file systems that support subvolume snapshots or 'reflinks' naively (btrfs + or new xfs) than on more traditional file systems that do not + (ext4). + + With this option no modifications of the container image are retained. Use + (described below) for other mechanisms to restrict persistency of + container images during runtime. + @@ -899,8 +906,12 @@ - Mount the root file system read-only for the - container. + Mount the container's root file system (and any other file systems container in the container + image) read-only. This has no effect on additional mounts made with , + and similar options. This mode is implied if the container image file or directory is + marked read-only itself. It is also implied if is used. In this case the container + image on disk is strictly read-only, while changes are permitted but kept non-persistently in memory only. For + further details, see below. @@ -931,20 +942,16 @@ - 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 . - Backslash escapes are interpreted in the path, so - \: may be used to embed colons in the path. - + 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). Backslash escapes are interpreted in the path, so \: may be used to embed colons + in the path. + + Note that this option cannot be used to replace the root file system of the container with a temporary + file system. However, the option described below provides similar + functionality, with a focus on implementing stateless operating system images. @@ -1002,7 +1009,11 @@ be on the same file system as the top-most directory tree). Also note that the lowerdir= mount option receives the paths to stack in the opposite order of - this switch. + this switch. + + Note that this option cannot be used to replace the root file system of the container with an overlay + file system. However, the option described below provides similar functionality, + with a focus on implementing stateless operating system images. @@ -1074,33 +1085,49 @@ MODE - Boots the container in volatile mode. When no - mode parameter is passed or when mode is specified as - , full volatile mode is enabled. This - means the root directory is mounted as a mostly unpopulated - tmpfs instance, and - /usr from the OS tree is mounted into it - in read-only mode (the system thus starts up with read-only OS - image, but pristine state and configuration, any changes - are lost on shutdown). When the mode parameter - is specified as , the OS tree is - mounted read-only, but /var is mounted as - a tmpfs instance into it (the system thus - starts up with read-only OS resources and configuration, but - pristine state, and any changes to the latter are lost on - shutdown). When the mode parameter is specified as - (the default), the whole OS tree is made - available writable. + Boots the container in volatile mode. When no mode parameter is passed or when mode is + specified as , full volatile mode is enabled. This means the root directory is mounted as a + mostly unpopulated tmpfs instance, and /usr/ from the OS tree is + mounted into it in read-only mode (the system thus starts up with read-only OS image, but pristine state and + configuration, any changes are lost on shutdown). When the mode parameter is specified as + , the OS tree is mounted read-only, but /var/ is mounted as a + writable tmpfs instance into it (the system thus starts up with read-only OS resources and + configuration, but pristine state, and any changes to the latter are lost on shutdown). When the mode parameter + is specified as the read-only root file system is combined with a writable + tmpfs instance through overlayfs, so that it appears at it normally + would, but any changes are applied to the temporary file system only and lost when the container is + terminated. When the mode parameter is specified as (the default), the whole OS tree is + made available writable (unless is specified, see above). + + Note that if one of the volatile modes is chosen, its effect is limited to the root file system (or + /var/ in case of ), and any other mounts placed in the hierarchy are + unaffected — regardless if they are established automatically (e.g. the EFI system partition that might be + mounted to /efi/ or /boot/) or explicitly (e.g. through an additional + command line option such as , see above). This means, even if + is used changes to /efi/ or + /boot/ are prohibited in case such a partition exists in the container image operated on, + and even if is used the hypothetical file /etc/foobar is + potentially writable if if used to mount it from outside the read-only + container /etc directory. + + The option is closely related to this setting, and provides similar + behaviour by making a temporary, ephemeral copy of the whole OS image and executing that. For further details, + see above. + + The and options provide similar functionality, but + for specific sub-directories of the OS image only. For details, see above. This option provides similar functionality for containers as the systemd.volatile= kernel command line switch provides for host systems. See kernel-command-line7 for details. - Note that enabling this setting will only work correctly with operating systems in the container that can - boot up with only /usr mounted, and are able to automatically populate - /var, and also /etc in case of - --volatile=yes. + Note that setting this option to or will only work correctly + with operating systems in the container that can boot up with only /usr mounted, and are + able to automatically populate /var, and also /etc in case of + --volatile=yes. The option does not require any particular + preparations in the OS, but do note that overlayfs behaviour differs from regular file + systems in a number of ways, and hence compatibility is limited.