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.