From 2d55baca25d4769e2afa4bf8eaccbc6ea8d0fbfb Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 14 Nov 2023 14:47:15 +0100
Subject: [PATCH] engine: add recursive bind mounts

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/storage/bind-mounts.md | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/content/storage/bind-mounts.md b/content/storage/bind-mounts.md
index 6e5bbc05c2..f1a703d4e5 100644
--- a/content/storage/bind-mounts.md
+++ b/content/storage/bind-mounts.md
@@ -266,6 +266,30 @@ $ docker container stop devtest
 $ docker container rm devtest
 ```
 
+## Recursive mounts
+
+When you bind mount a path that itself contains mounts, those submounts are
+also included in the bind mount by default. This behavior is configurable,
+using the `bind-recursive` option for `--mount`. This option is only supported
+with the `--mount` flag, not with `-v` or `--volume`.
+
+If the bind mount is read-only, the Docker Engine makes a best-effort attempt
+at making the submounts read-only as well. This is referred to as recursive
+read-only mounts. Recursive read-only mounts require Linux kernel version 5.12
+or later. If you're running an older kernel version, submounts are
+automatically mounted as read-write by default. Attempting to set submounts to
+be read-only on a kernel version earlier than 5.12, using the
+`bind-recursive=readonly` option, results in an error.
+
+Supported values for the `bind-recursive` option are:
+
+| Value               | Description                                                                                                       |
+|:--------------------|:------------------------------------------------------------------------------------------------------------------|
+| `enabled` (default) | Read-only mounts are made recursively read-only if kernel is v5.12 or later. Otherwise, submounts are read-write. |
+| `disabled`          | Submounts are ignored (not included in the bind mount).                                                           |
+| `writable`          | Submounts are read-write.                                                                                         |
+| `readonly`          | Submounts are read-only. Requires kernel v5.12 or later.                                                          |
+
 ## Configure bind propagation
 
 Bind propagation defaults to `rprivate` for both bind mounts and volumes. It is
@@ -396,4 +420,4 @@ and
 
 - Learn about [volumes](volumes.md).
 - Learn about [tmpfs mounts](tmpfs.md).
-- Learn about [storage drivers](/storage/storagedriver/).
\ No newline at end of file
+- Learn about [storage drivers](/storage/storagedriver/).