config: Document 'rbind' and 'bind' mount options extensions

wking · wking · commit bd28d9bde07e · 2017-04-13T22:04:01.000-07:00
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. We may eventually add entries for other mount(8) command-line options (e.g. --move, --make-shared, ...), but I've left those off until someone pitches a motivational use case for them. 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 [1]. 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: $ 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(8) now will make life less confusing in the future. [1]: #530 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
diff --git a/config.md b/config.md
@@ -57,16 +57,23 @@ For Windows, see [mountvol][mountvol] and [SetVolumeMountPoint][set-volume-mount
   This value MUST be an absolute path.
   * Windows: one mount destination MUST NOT be nested within another mount (e.g., c:\\foo and c:\\foo\\bar).
   * Solaris: corresponds to "dir" of the fs resource in [zonecfg(1M)][zonecfg.1m].
-* **`type`** (string, OPTIONAL) The filesystem type of the filesystem to be mounted.
-  * Linux: valid *filesystemtype* supported by the kernel as listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660").
-  * Windows: the type of file system on the volume, e.g. "ntfs".
-  * Solaris: corresponds to "type" of the fs resource in [zonecfg(1M)][zonecfg.1m].
+* **`type`** (string, OPTIONAL) The type of filesystem to mount.
+    If `type` is unset, the runtime MAY ask the kernel to guess the desired type.
+    Depending on the mount `options`, the `type` field MAY be ignored.
+    * Linux: valid *filesystemtype* supported by the kernel as listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660").
+        `type` is ignored when `options` contains `bind` or `rbind`; see the `MS_BIND` description in [mount(2)][mount.2].
+    * Windows: the type of file system on the volume, e.g. "ntfs".
+    * Solaris: corresponds to "type" of the fs resource in [zonecfg(1M)][zonecfg.1m].
 * **`source`** (string, OPTIONAL) A device name, but can also be a directory name or a dummy.
   * Windows: the volume name that is the target of the mount point, \\?\Volume\{GUID}\ (on Windows source is called target).
   * Solaris: corresponds to "special" of the fs resource in [zonecfg(1M)][zonecfg.1m].
 * **`options`** (list of strings, OPTIONAL) Mount options of the filesystem to be used.
-  * 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.
-  * Solaris: corresponds to "options" of the fs resource in [zonecfg(1M)][zonecfg.1m].
+    * 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.
+        Linux runtimes MUST also support the following options:
+
+        * `rbind`, with the semantics of [`MS_REC | MS_BIND`][mount.2].
+        * `bind`, with the semantics of [`MS_BIND`][mount.2].
+    * Solaris: corresponds to "options" of the fs resource in [zonecfg(1M)][zonecfg.1m].
 
 ### Example (Linux)
 
@@ -80,9 +87,8 @@ For Windows, see [mountvol][mountvol] and [SetVolumeMountPoint][set-volume-mount
     },
     {
         "destination": "/data",
-        "type": "bind",
         "source": "/volumes/testing",
-        "options": ["rbind","rw"]
+        "options": ["rbind", "rw"]
     }
 ]
 ```
diff --git a/specs-go/config.go b/specs-go/config.go
@@ -112,7 +112,7 @@ type Platform struct {
 type Mount struct {
 	// 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.
 	Destination string `json:"destination"`
-	// Type specifies the mount kind.
+	// Type specifies the type of filesystem to mount.
 	Type string `json:"type,omitempty"`
 	// Source specifies the source path of the mount.  In the case of bind mounts on
 	// Linux based systems this would be the file on the host.
