@@ -783,6 +783,56 @@ controlled by the "uuid" mount option, which supports these values:
783783 mounted with "uuid=on".
784784
785785
786+ Durability and copy up
787+ ----------------------
788+
789+ The fsync(2) system call ensures that the data and metadata of a file
790+ are safely written to the backing storage, which is expected to
791+ guarantee the existence of the information post system crash.
792+
793+ Without an fsync(2) call, there is no guarantee that the observed
794+ data after a system crash will be either the old or the new data, but
795+ in practice, the observed data after crash is often the old or new data
796+ or a mix of both.
797+
798+ When an overlayfs file is modified for the first time, copy up will
799+ create a copy of the lower file and its parent directories in the upper
800+ layer. Since the Linux filesystem API does not enforce any particular
801+ ordering on storing changes without explicit fsync(2) calls, in case
802+ of a system crash, the upper file could end up with no data at all
803+ (i.e. zeros), which would be an unusual outcome. To avoid this
804+ experience, overlayfs calls fsync(2) on the upper file before completing
805+ data copy up with rename(2) or link(2) to make the copy up "atomic".
806+
807+ By default, overlayfs does not explicitly call fsync(2) on copied up
808+ directories or on metadata-only copy up, so it provides no guarantee to
809+ persist the user's modification unless the user calls fsync(2).
810+ The fsync during copy up only guarantees that if a copy up is observed
811+ after a crash, the observed data is not zeroes or intermediate values
812+ from the copy up staging area.
813+
814+ On traditional local filesystems with a single journal (e.g. ext4, xfs),
815+ fsync on a file also persists the parent directory changes, because they
816+ are usually modified in the same transaction, so metadata durability during
817+ data copy up effectively comes for free. Overlayfs further limits risk by
818+ disallowing network filesystems as upper layer.
819+
820+ Overlayfs can be tuned to prefer performance or durability when storing
821+ to the underlying upper layer. This is controlled by the "fsync" mount
822+ option, which supports these values:
823+
824+ - "auto": (default)
825+ Call fsync(2) on upper file before completion of data copy up.
826+ No explicit fsync(2) on directory or metadata-only copy up.
827+ - "strict":
828+ Call fsync(2) on upper file and directories before completion of any
829+ copy up.
830+ - "volatile": [*]
831+ Prefer performance over durability (see `Volatile mount `_)
832+
833+ [*] The mount option "volatile" is an alias to "fsync=volatile".
834+
835+
786836Volatile mount
787837--------------
788838
0 commit comments