From 1ef5938191e7a2265bb176ea7731f9a3bf3ad4af Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 12 Aug 2016 22:56:40 -0700 Subject: [PATCH] config: Document 'recursive' 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. 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 --- config.md | 18 +++++++++++++----- schema/defs.json | 3 +-- specs-go/config.go | 4 ++-- 3 files changed, 16 insertions(+), 9 deletions(-) diff --git a/config.md b/config.md index 1a551435c..4ed416bc3 100644 --- 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` or `rbind`; 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 index 329031848..b25a12347 100644 --- 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 index 4a1612264..014f81083 100644 --- 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"`