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

wking · wking · commit 05b32777bfe6 · 2016-08-31T09:12:45.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 to that example with an unset type and: "options": ["rbind", ...] and that would have been closer to mount(8)'s --rbind API, but I've gone with 'recursive' here to stay closer to mount(2). This will scale better if/when we eventually add options for MS_SLAVE, etc. 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(2) now will make life less confusing in the future. Signed-off-by: W. Trevor King <wking@tremily.us>
diff --git a/config.md b/config.md
@@ -41,17 +41,24 @@ Each container has exactly one *root filesystem*, specified in the *root* object
 
 You MAY add array of mount points inside container as `mounts`.
 The runtime MUST mount entries in the listed order.
-The parameters are similar to the ones in [the Linux mount system call](http://man7.org/linux/man-pages/man2/mount.2.html).
+The parameters are similar to the ones in [the Linux mount system call][mount.2].
 
 * **`destination`** (string, required) Destination of mount point: path inside container.
   For the Windows operating system, one mount destination MUST NOT be nested within another mount (e.g., c:\\foo and c:\\foo\\bar).
-* **`type`** (string, required) The filesystem type of the filesystem to be mounted.
-  Linux: *filesystemtype* argument supported by the kernel are listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660").
+* **`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.
+  For example, `type` is ignored when `options` contains `bind`; see the `MS_BIND` description in [mount(2)][mount.2].
+  Linux: [*filesystemtype*][mount.2] values supported by the kernel are listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660").
   Windows: ntfs.
 * **`source`** (string, required) 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).
 * **`options`** (list of strings, optional) Mount options of the filesystem to be used.
   Linux: [supported][mount.8-filesystem-independent] [options][mount.8-filesystem-specific] are listed in [mount(8)][mount.8].
+  Linux runtimes MUST also support the following options:
+
+    * `recursive`, with the semantics of [`MS_REC`][mount.2].
+    * `bind`, with the semantics of [`MS_BIND`][mount.2].
 
 ### Example (Linux)
 
@@ -65,9 +72,8 @@ The parameters are similar to the ones in [the Linux mount system call](http://m
     },
     {
         "destination": "/data",
-        "type": "bind",
         "source": "/volumes/testing",
-        "options": ["rbind","rw"]
+        "options": ["recursive", "bind", "rw"]
     }
 ]
 ```
@@ -688,6 +694,8 @@ Here is a full example `config.json` for reference.
 [go-environment]: https://golang.org/doc/install/source#environment
 [runtime-namespace]: glossary.md#runtime-namespace
 [uts-namespace]: http://man7.org/linux/man-pages/man7/namespaces.7.html
+[mount.2]: http://man7.org/linux/man-pages/man2/mount.2.html
 [mount.8-filesystem-independent]: http://man7.org/linux/man-pages/man8/mount.8.html#FILESYSTEM-INDEPENDENT_MOUNT OPTIONS
 [mount.8-filesystem-specific]: http://man7.org/linux/man-pages/man8/mount.8.html#FILESYSTEM-SPECIFIC_MOUNT OPTIONS
+[mount.8-options]: http://man7.org/linux/man-pages/man8/mount.8.html#COMMAND-LINE_OPTIONS
 [mount.8]: http://man7.org/linux/man-pages/man8/mount.8.html
diff --git a/schema/defs.json b/schema/defs.json
@@ -152,8 +152,7 @@
             },
             "required": [
                 "destination",
-                "source",
-                "type"
+                "source"
             ]
         },
         "ociVersion": {
diff --git a/specs-go/config.go b/specs-go/config.go
@@ -85,8 +85,8 @@ 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 string `json:"type"`
+	// 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.
 	Source string `json:"source"`
