From 5ca74df7e95bde488acf2b7f730656d1b565c06e Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 4 Jun 2016 23:09:32 -0700 Subject: [PATCH 1/2] config: Make 'process.args' optional Since be59415 (Split create and start, 2016-04-01, #384), it's possible for a container process to never execute user-specified code (e.g. you can call 'create', 'kill', 'delete' without calling 'start'). For folks who expect to do that, there's no reason to define process.args. The only other process property required for all platforms is 'cwd', but the runtime's idler code isn't specified in sufficient detail for the configuration author to have an opinion about what its working directory should be. On Linux and Solaris, 'user' is also required for 'uid' and 'gid'. My preferred approach here is to make those optional and define defaults [1,2]: If unset, the runtime will not attempt to manipulate the user ID (e.g. not calling setuid(2) or similar). But the maintainer consensus is that they want those to be explicitly required properties [3,4,5]. With the current spec, one option could be to make process optional (with the idler's working directory unspecified) for OSes besides Linux and Solaris, but the main reason that Windows doesn't have a user property is that we don't know how to specify it [6]. I expect all platforms will have some sort of required user field, which means they'll all have to define 'process'. While I'm indenting the sub-properties, also wrap them to one line per sentence (style.md). [1]: https://github.com/opencontainers/runtime-spec/pull/417#issuecomment-216076069 [2]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/DWdystx5X3A Subject: Exposing platform defaults Date: Thu, 14 Jan 2016 15:36:26 -0800 Message-ID: <20160114233625.GN6362@odin.tremily.us> [3]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-04-17.00.log.html#l-44 [4]: https://github.com/opencontainers/runtime-spec/pull/417#issuecomment-216937010 [5]: https://github.com/opencontainers/runtime-spec/pull/417#issuecomment-216937090 [6]: https://github.com/opencontainers/runtime-spec/pull/96#issuecomment-128410585 Signed-off-by: W. Trevor King --- config.md | 49 +++++++++++++++++++++++++++------------------- runtime.md | 1 + schema/schema.json | 3 +-- specs-go/config.go | 2 +- 4 files changed, 32 insertions(+), 23 deletions(-) diff --git a/config.md b/config.md index 78a501a12..670f20aa8 100644 --- a/config.md +++ b/config.md @@ -84,26 +84,35 @@ For the Windows operating system, one mount destination MUST NOT be nested withi See links for details about [mountvol](http://ss64.com/nt/mountvol.html) and [SetVolumeMountPoint](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365561(v=vs.85).aspx) in Windows. -## Process configuration - -* **`terminal`** (bool, optional) specifies whether you want a terminal attached to that process. Defaults to false. -* **`cwd`** (string, required) is the working directory that will be set for the executable. This value MUST be an absolute path. -* **`env`** (array of strings, optional) contains a list of variables that will be set in the process's environment prior to execution. Elements in the array are specified as Strings in the form "KEY=value". The left hand side MUST consist solely of letters, digits, and underscores `_` as outlined in [IEEE Std 1003.1-2001](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html). -* **`args`** (array of strings, required) executable to launch and any flags as an array. The executable is the first element and MUST be available at the given path inside of the rootfs. If the executable path is not an absolute path then the search $PATH is interpreted to find the executable. - -For Linux-based systems the process structure supports the following process specific fields: - -* **`capabilities`** (array of strings, optional) capabilities is an array that specifies Linux capabilities that can be provided to the process inside the container. -Valid values are the strings for capabilities defined in [the man page](http://man7.org/linux/man-pages/man7/capabilities.7.html) -* **`rlimits`** (array of rlimits, optional) rlimits is an array of rlimits that allows setting resource limits for a process inside the container. -The kernel enforces the `soft` limit for a resource while the `hard` limit acts as a ceiling for that value that could be set by an unprivileged process. -Valid values for the 'type' field are the resources defined in [the man page](http://man7.org/linux/man-pages/man2/setrlimit.2.html). -* **`apparmorProfile`** (string, optional) apparmor profile specifies the name of the apparmor profile that will be used for the container. -For more information about Apparmor, see [Apparmor documentation](https://wiki.ubuntu.com/AppArmor) -* **`selinuxLabel`** (string, optional) SELinux process label specifies the label with which the processes in a container are run. -For more information about SELinux, see [Selinux documentation](http://selinuxproject.org/page/Main_Page) -* **`noNewPrivileges`** (bool, optional) setting `noNewPrivileges` to true prevents the processes in the container from gaining additional privileges. -[The kernel doc](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt) has more information on how this is achieved using a prctl system call. +## Process + +* **`process`** (object, required) configures the container process. + It supports the following properties: + + * **`terminal`** (bool, optional) specifies whether you want a terminal attached to that process. + Defaults to false. + * **`cwd`** (string, required) is the working directory that will be set for the executable. + This value MUST be an absolute path. + * **`env`** (array of strings, optional) contains a list of variables that will be set in the process's environment prior to execution. + Elements in the array are specified as Strings in the form "KEY=value". + The left hand side MUST consist solely of letters, digits, and underscores `_` as outlined in [IEEE Std 1003.1-2001](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html). + * **`args`** (array of strings, optional) executable to launch and any flags as an array. + The executable is the first element and MUST be available at the given path inside of the rootfs. + If the executable path is not an absolute path then the search $PATH is interpreted to find the executable. + + For Linux-based systems the process structure supports the following process specific fields: + + * **`capabilities`** (array of strings, optional) capabilities is an array that specifies Linux capabilities that can be provided to the process inside the container. + Valid values are the strings for capabilities defined in [the man page](http://man7.org/linux/man-pages/man7/capabilities.7.html) + * **`rlimits`** (array of rlimits, optional) rlimits is an array of rlimits that allows setting resource limits for a process inside the container. + The kernel enforces the `soft` limit for a resource while the `hard` limit acts as a ceiling for that value that could be set by an unprivileged process. + Valid values for the 'type' field are the resources defined in [the man page](http://man7.org/linux/man-pages/man2/setrlimit.2.html). + * **`apparmorProfile`** (string, optional) apparmor profile specifies the name of the apparmor profile that will be used for the container. + For more information about Apparmor, see [Apparmor documentation](https://wiki.ubuntu.com/AppArmor) + * **`selinuxLabel`** (string, optional) SELinux process label specifies the label with which the processes in a container are run. + For more information about SELinux, see [Selinux documentation](http://selinuxproject.org/page/Main_Page) + * **`noNewPrivileges`** (bool, optional) setting `noNewPrivileges` to true prevents the processes in the container from gaining additional privileges. + [The kernel doc](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt) has more information on how this is achieved using a prctl system call. ### User diff --git a/runtime.md b/runtime.md index 2c99f501d..e2b68cccd 100644 --- a/runtime.md +++ b/runtime.md @@ -102,6 +102,7 @@ This operation MUST generate an error if it is not provided the container ID. Attempting to start a container that does not exist MUST generate an error. Attempting to start an already started container MUST have no effect on the container and MUST generate an error. This operation MUST run the user-specified code as specified by [`process`](config.md#process-configuration). +If `process.args` was not configured, the runtime MUST generate an error. Upon successful completion of this operation the `status` property of this container MUST be `running`. diff --git a/schema/schema.json b/schema/schema.json index ca0b880de..32bdc67bb 100644 --- a/schema/schema.json +++ b/schema/schema.json @@ -83,8 +83,7 @@ "id": "https://opencontainers.org/schema/bundle/process", "type": "object", "required": [ - "cwd", - "args" + "cwd" ], "properties": { "args": { diff --git a/specs-go/config.go b/specs-go/config.go index ec99035bb..b5e4b4261 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -34,7 +34,7 @@ type Process struct { // User specifies user information for the process. User User `json:"user"` // Args specifies the binary and arguments for the application to execute. - Args []string `json:"args"` + Args []string `json:"args,omitempty"` // Env populates the process environment for the process. Env []string `json:"env,omitempty"` // Cwd is the current working directory for the process and must be From f025239e732654256ddaa1927d49b820ca1fdddf Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sun, 5 Jun 2016 00:01:10 -0700 Subject: [PATCH 2/2] config: Explicitly list process.user as required Linux and Solaris both use the same POSIX-based structure (which I've moved to defs-linux.json). Windows likely needs a string-based structure, but we're punting on that until we have more feedback from the Windows folks [1]. Regardless of whether we have a Windows user structure yet, the maintainer consensus is that the property is required [2,3,4]. [1]: https://github.com/opencontainers/runtime-spec/pull/96#issuecomment-128410585 [2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-04-17.00.log.html#l-44 [3]: https://github.com/opencontainers/runtime-spec/pull/417#issuecomment-216937010 [4]: https://github.com/opencontainers/runtime-spec/pull/417#issuecomment-216937090 Signed-off-by: W. Trevor King --- config.md | 2 ++ schema/defs-linux.json | 18 ++++++++++++++++++ schema/schema.json | 21 ++++++--------------- 3 files changed, 26 insertions(+), 15 deletions(-) diff --git a/config.md b/config.md index 670f20aa8..35c4b3f1b 100644 --- a/config.md +++ b/config.md @@ -99,6 +99,8 @@ See links for details about [mountvol](http://ss64.com/nt/mountvol.html) and [Se * **`args`** (array of strings, optional) executable to launch and any flags as an array. The executable is the first element and MUST be available at the given path inside of the rootfs. If the executable path is not an absolute path then the search $PATH is interpreted to find the executable. + * **`user`** (object, required) the process user. + The properties for this object are [platform dependent](#user). For Linux-based systems the process structure supports the following process specific fields: diff --git a/schema/defs-linux.json b/schema/defs-linux.json index ea02361c0..d12749c56 100644 --- a/schema/defs-linux.json +++ b/schema/defs-linux.json @@ -1,5 +1,23 @@ { "definitions": { + "user": { + "type": "object", + "properties": { + "uid": { + "$ref": "defs.json#/definitions/UID" + }, + "gid": { + "$ref": "defs.json#/definitions/GID" + }, + "additionalGids": { + "$ref": "defs.json#/definitions/ArrayOfGIDs" + } + }, + "required": [ + "uid", + "gid" + ] + }, "SeccompArch": { "type": "string", "enum": [ diff --git a/schema/schema.json b/schema/schema.json index 32bdc67bb..ad22475dd 100644 --- a/schema/schema.json +++ b/schema/schema.json @@ -83,7 +83,8 @@ "id": "https://opencontainers.org/schema/bundle/process", "type": "object", "required": [ - "cwd" + "cwd", + "user" ], "properties": { "args": { @@ -104,21 +105,11 @@ }, "user": { "id": "https://opencontainers.org/schema/bundle/process/user", - "type": "object", - "properties": { - "uid": { - "id": "https://opencontainers.org/schema/bundle/process/user/uid", - "$ref": "defs.json#/definitions/UID" - }, - "gid": { - "id": "https://opencontainers.org/schema/bundle/process/user/gid", - "$ref": "defs.json#/definitions/GID" - }, - "additionalGids": { - "id": "https://opencontainers.org/schema/bundle/process/user/additionalGids", - "$ref": "defs.json#/definitions/ArrayOfGIDs" + "oneOf": [ + { + "$ref": "defs-linux.json#/definitions/user" } - } + ] }, "capabilities": { "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities",