Skip to content

Commit 4b1b93f

Browse files
wkingwking
committed
config: Document 'rbind' and 'bind' mount options extensions
They are not filesystem types, so they don't belong in 'type'. The specs claim mount(2) as inspiration for this modeling (which makes sense, since that's the syscall Linux runtimes will make to implement it), and there (recursive) bind is represented by mountflags (MS_REC | MS_BIND). Currently the 'options' property handles both mount(2)'s mountflags and data, so 'options' is a good spot for these two settings. Before this commit, we were punting this sort of table to mount(8)'s filesystem-independent mount options. With this commit we drop the mount(8) reference and replace it with explicit requirements based on mount(2), as approved by Michael [1]. Personally, I prefer the old mount(8) punt, but have been unable to get (recursive) bind documented without removing it. The option strings still come from mount(8)'s filesytem-independent mount options with the following exceptions: * move, rbind, rprivate, rshared, rslave, and runbindable are exposed in mount(8) through long options (e.g. --move). * (no)acl is listed under filesystem-specific mount options (e.g. for ext2). This commit covers the MS_* entries from [2] with the following exceptions: * MS_VERBOSE, which has been deprecated in favor of MS_SILENT. * MS_KERNMOUNT, since the mount(2) calls won't be kern_mount calls and they are not covered in mount(8). * MS_SUBMOUNT and other flags documented as "internal to the kernel". * MS_RMT_MASK, since it's a mask and not a flag. * MS_MGC_*, since the magic mount flag is ignored since Linux 2.4 according to mount(2). The example I'm touching used: "type": "bind", ... "options": ["rbind", ...] but I don't see a point to putting 'bind' in 'type' when it's not a filesystem type and you already have 'rbind' in 'options'. We could have stuck closer mount(2) by using: "options": ["recursive", "bind", ...] but while that approach extends more conveniently to the other recursive mounts (recursive shared, slave, private, and unbindable mounts), there has been resistance to a direct MS_REC analog [3,4]. I think that resistance is ungrounded (obviously the kernel and mount(2) feels like a composable MS_REC makes sense), but I'm not a mainainer. Since there are existing consumers using the old example format and similar things like runtime-tools: $ git log --oneline -1 | cat 03e8b89 Merge pull request #176 from hmeng-19/set_oom_score_adj $ ./ocitools generate --template <(echo '{}') --bind ab:cd:ro | jq '.mounts[0]' { "destination": "cd", "type": "bind", "source": "ab", "options": [ "bind", "ro" ] } this may be a breaking change for some spec consumers (although that ocitools example will still work, because 'options' contains 'bind', which means the 'type' will be ignored). But even if there are broken consumers, we're still pre-1.0, the spec never explained what bind/rbind meant before this commit, and consolidating the Linux mount spec around mount(2) now will make life less confusing in the future. [1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-05-09-20.07.log.html#l-24 [2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/fs.h?id=refs/tags/v4.11#n105 [3]: #530 (comment) [4]: #771 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
1 parent 138ad89 commit 4b1b93f

2 files changed

Lines changed: 65 additions & 14 deletions

File tree

‎config.md‎

Lines changed: 64 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -55,18 +55,73 @@ For Windows, see [mountvol][mountvol] and [SetVolumeMountPoint][set-volume-mount
5555

5656
* **`destination`** (string, REQUIRED) Destination of mount point: path inside container.
5757
This value MUST be an absolute path.
58+
* Linux: runtimes MUST pass this value to [`mount(2)`][mount.2] as the `target` argument.
5859
* Windows: one mount destination MUST NOT be nested within another mount (e.g., c:\\foo and c:\\foo\\bar).
5960
* Solaris: corresponds to "dir" of the fs resource in [zonecfg(1M)][zonecfg.1m].
60-
* **`type`** (string, OPTIONAL) The filesystem type of the filesystem to be mounted.
61-
* Linux: valid *filesystemtype* supported by the kernel as listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660").
62-
* Windows: the type of file system on the volume, e.g. "ntfs".
63-
* Solaris: corresponds to "type" of the fs resource in [zonecfg(1M)][zonecfg.1m].
61+
* **`type`** (string, OPTIONAL) The type of filesystem to mount.
62+
If `type` is unset, the runtime MAY ask the kernel to guess the desired type.
63+
Depending on the mount `options`, the `type` field MAY be ignored.
64+
* Linux: when `type` is set, runtimes MUST pass the value to [`mount(2)`][mount.2] as the `filesystemtype` argument.
65+
`type` is ignored when `options` contains `bind` or `rbind`; see the `MS_BIND` description in [mount(2)][mount.2].
66+
* Windows: the type of file system on the volume, e.g. "ntfs".
67+
* Solaris: corresponds to "type" of the fs resource in [zonecfg(1M)][zonecfg.1m].
6468
* **`source`** (string, OPTIONAL) A device name, but can also be a directory name or a dummy.
65-
* Windows: the volume name that is the target of the mount point, \\?\Volume\{GUID}\ (on Windows source is called target).
66-
* Solaris: corresponds to "special" of the fs resource in [zonecfg(1M)][zonecfg.1m].
69+
* Linux: when `type` is set, runtimes MUST pass the value to [`mount(2)`][mount.2] as the `source` argument.
70+
When `type` is not set, the value used for the `source` argument is unspecified.
71+
* Windows: the volume name that is the target of the mount point, \\?\Volume\{GUID}\ (on Windows source is called target).
72+
* Solaris: corresponds to "special" of the fs resource in [zonecfg(1M)][zonecfg.1m].
6773
* **`options`** (list of strings, OPTIONAL) Mount options of the filesystem to be used.
68-
* Linux: supported options are listed in the [mount(8)][mount.8] man page. Note both [filesystem-independent][mount.8-filesystem-independent] and [filesystem-specific][mount.8-filesystem-specific] options are listed.
69-
* Solaris: corresponds to "options" of the fs resource in [zonecfg(1M)][zonecfg.1m].
74+
* Linux: runtimes MUST call [`mount(2)`][mount.2] with an initially-zero `mountflags` argument altered by applying the following `options` in the listed order:
75+
76+
| Option | Set bits | Clear bits |
77+
| --------------- | ------------------------ | ------------------------------------------------------------------------------------- |
78+
| `acl` | `MS_POSIXACL` | |
79+
| `async` | | `MS_SYNCHRONOUS` |
80+
| `atime` | | `MS_NOATIME` |
81+
| `bind` | `MS_BIND` | |
82+
| `defaults` | | `MS_RDONLY | MS_NOSUID | MS_NODEV | MS_NOEXEC | MS_NOAUTO | MS_USER | MS_SYNCHRONOUS` |
83+
| `dev` | | `MS_NODEV` |
84+
| `diratime` | | `MS_NODIRATIME` |
85+
| `dirsync` | `MS_DIRSYNC` | |
86+
| `exec` | | `MS_NOEXEC` |
87+
| `iversion` | `MS_I_VERSION` | |
88+
| `lazytime` | `MS_LAZYTIME` | |
89+
| `loud` | | `MS_SILENT` |
90+
| `mand` | `MS_MANDLOCK` | |
91+
| `move` | `MS_MOVE` | |
92+
| `noacl` | | `MS_POSIXACL` |
93+
| `noatime` | `MS_NOATIME` | |
94+
| `nodev` | `MS_NODEV` | |
95+
| `nodiratime` | `MS_NODIRATIME` | |
96+
| `noexec` | `MS_NOEXEC` | |
97+
| `noiversion` | | `MS_I_VERSION` |
98+
| `nolazytime` | | `MS_LAZYTIME` |
99+
| `nomand` | | `MS_MANDLOCK` |
100+
| `norelatime` | | `MS_RELATIME` |
101+
| `nostrictatime` | | `MS_STRICTATIME` |
102+
| `nosuid` | `MS_NOSUID` | |
103+
| `private` | `MS_PRIVATE` | |
104+
| `rbind` | `MS_REC | MS_BIND` | |
105+
| `relatime` | `MS_RELATIME` | |
106+
| `remount` | `MS_REMOUNT` | |
107+
| `ro` | `MS_RDONLY` | |
108+
| `rprivate` | `MS_REC | MS_PRIVATE` | |
109+
| `rshared` | `MS_REC | MS_SHARED` | |
110+
| `rslave` | `MS_REC | MS_SLAVE` | |
111+
| `runbindable` | `MS_REC | MS_UNBINDABLE` | |
112+
| `rw` | | `MS_RDONLY` |
113+
| `shared` | `MS_SHARED` | |
114+
| `silent` | `MS_SILENT` | |
115+
| `slave` | `MS_SLAVE` | |
116+
| `strictatime` | `MS_STRICTATIME` | |
117+
| `suid` | | `MS_NOSUID` |
118+
| `sync` | `MS_SYNCHRONOUS` | |
119+
| `unbindable` | `MS_UNBINDABLE` | |
120+
121+
Runtimes MUST call [`mount(2)`][mount.2] with the `data` pointing at a string containing, in the listed order, all options not listed in the above table joined with comma delimiters.
122+
If `options` contains no options from the above table, `data` may be either a pointer to an empty string or `NULL`.
123+
124+
* Solaris: corresponds to "options" of the fs resource in [zonecfg(1M)][zonecfg.1m].
70125

71126
### Example (Linux)
72127

@@ -80,9 +135,8 @@ For Windows, see [mountvol][mountvol] and [SetVolumeMountPoint][set-volume-mount
80135
},
81136
{
82137
"destination": "/data",
83-
"type": "bind",
84138
"source": "/volumes/testing",
85-
"options": ["rbind","rw"]
139+
"options": ["rbind", "rw"]
86140
}
87141
]
88142
```
@@ -829,9 +883,6 @@ Here is a full example `config.json` for reference.
829883

830884
[capabilities.7]: http://man7.org/linux/man-pages/man7/capabilities.7.html
831885
[mount.2]: http://man7.org/linux/man-pages/man2/mount.2.html
832-
[mount.8]: http://man7.org/linux/man-pages/man8/mount.8.html
833-
[mount.8-filesystem-independent]: http://man7.org/linux/man-pages/man8/mount.8.html#FILESYSTEM-INDEPENDENT_MOUNT%20OPTIONS
834-
[mount.8-filesystem-specific]: http://man7.org/linux/man-pages/man8/mount.8.html#FILESYSTEM-SPECIFIC_MOUNT%20OPTIONS
835886
[setrlimit.2]: http://man7.org/linux/man-pages/man2/setrlimit.2.html
836887
[stdin.3]: http://man7.org/linux/man-pages/man3/stdin.3.html
837888
[uts-namespace.7]: http://man7.org/linux/man-pages/man7/namespaces.7.html

‎specs-go/config.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ type Platform struct {
112112
type Mount struct {
113113
// Destination is the path where the mount will be placed relative to the container's root. The path and child directories MUST exist, a runtime MUST NOT create directories automatically to a mount point.
114114
Destination string `json:"destination"`
115-
// Type specifies the mount kind.
115+
// Type specifies the type of filesystem to mount.
116116
Type string `json:"type,omitempty"`
117117
// Source specifies the source path of the mount. In the case of bind mounts on
118118
// Linux based systems this would be the file on the host.

0 commit comments

Comments
 (0)