Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add bind-recursive mount option #4606

Merged
merged 1 commit into from
Nov 14, 2023
Merged

docs: add bind-recursive mount option #4606

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 29 additions & 6 deletions docs/reference/commandline/service_create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -394,7 +394,7 @@ volumes in a service:
<td>
<p>The Engine mounts binds and volumes <tt>read-write</tt> unless <tt>readonly</tt> option
is given when mounting the bind or volume. Note that setting <tt>readonly</tt> for a
bind-mount does not make its submounts <tt>readonly</tt> on the current Linux implementation. See also <tt>bind-nonrecursive</tt>.</p>
bind-mount may not make its submounts <tt>readonly</tt> depending on the kernel version. See also <tt>bind-recursive</tt>.</p>
<ul>
<li><tt>true</tt> or <tt>1</tt> or no value: Mounts the bind or volume read-only.</li>
<li><tt>false</tt> or <tt>0</tt>: Mounts the bind or volume read-write.</li>
Expand Down Expand Up @@ -432,17 +432,40 @@ The following options can only be used for bind mounts (`type=bind`):
</td>
</tr>
<tr>
<td><b>bind-nonrecursive</b></td>
<td><b>bind-recursive</b></td>
<td>
By default, submounts are recursively bind-mounted as well. However, this behavior can be confusing when a
bind mount is configured with <tt>readonly</tt> option, because submounts are not mounted as read-only.
Set <tt>bind-nonrecursive</tt> to disable recursive bind-mount.<br />
bind mount is configured with <tt>readonly</tt> option, because submounts may not be mounted as read-only,
depending on the kernel version.
Set <tt>bind-recursive</tt> to control the behavior of the recursive bind-mount.<br />
<br />
A value is one of:<br />
<br />
<ul>
<li><<tt>enabled</tt>, <tt>true</tt> or <tt>1</tt>: Enables recursive bind-mount.
Read-only mounts are made recursively read-only if kernel is v5.12 or later.
Otherwise they are not made recursively read-only.</li>
<li><<tt>disabled</tt>, <tt>false</tt> or <tt>0</tt>: Disables recursive bind-mount.</li>
Comment on lines +445 to +448
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Opened a PR for discussion to remove the boolean variants (motivation outlined in that PR);

<li><<tt>writable</tt>: Enables recursive bind-mount.
Read-only mounts are not made recursively read-only.</li>
<li><<tt>readonly</tt>: Enables recursive bind-mount.
Read-only mounts are made recursively read-only if kernel is v5.12 or later.
Otherwise the Engine raises an error.</li>
</ul>
When the option is not specified, the default behavior correponds to setting <tt>enabled</tt>.
</td>
</tr>
<tr>
<td><b>bind-nonrecursive</b></td>
<td>
<tt>bind-nonrecursive</tt> is deprecated since Docker Engine v25.0.
Use <tt>bind-recursive</tt>instead.<br />
<br />
A value is optional:<br />
<br />
<ul>
<li><tt>true</tt> or <tt>1</tt>: Disables recursive bind-mount.</li>
<li><tt>false</tt> or <tt>0</tt>: Default if you do not provide a value. Enables recursive bind-mount.</li>
<li><tt>true</tt> or <tt>1</tt>: Equivalent to <tt>bind-recursive=disabled</tt>.</li>
<li><tt>false</tt> or <tt>0</tt>: Equivalent to <tt>bind-recursive=enabled</tt>.</li>
</ul>
</td>
</tr>
Expand Down
14 changes: 9 additions & 5 deletions man/docker-run.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -467,16 +467,20 @@ according to RFC4862.
* `dst`, `destination`, `target`: mount destination spec.
* `ro`, `readonly`: `true` or `false` (default).

**Note**: setting `readonly` for a bind mount does not make its submounts
read-only on the current Linux implementation. See also `bind-nonrecursive`.
**Note**: setting `readonly` for a bind mount may not make its submounts
read-only depending on the kernel version. See also `bind-recursive`.

Options specific to `bind`:

* `bind-propagation`: `shared`, `slave`, `private`, `rshared`, `rslave`, or `rprivate`(default). See also `mount(2)`.
* `consistency`: `consistent`(default), `cached`, or `delegated`. Currently, only effective for Docker for Mac.
* `bind-nonrecursive`: `true` or `false` (default). If set to `true`,
submounts are not recursively bind-mounted. This option is useful for
`readonly` bind mount.
* `bind-recursive`: `enabled` (default), `disabled`, `writable`, or `readonly`:
If set to `enabled`, submounts are recursively bind-mounted and attempted to be made recursively read-only.
If set to `disabled`, submounts are not recursively bind-mounted.
If set to `writable`, submounts are recursively bind-mounted but not made recursively read-only.
If set to `readonly`, submounts are recursively bind-mounted and forcibly made recursively read-only.
* `bind-nonrecursive` (Deprecated): `true` or `false` (default). Setting `true` equates to `bind-recursive=disabled`.
Setting `false` equates to `bind-recursive=enabled`.

Options specific to `volume`:

Expand Down
Loading