diff --git a/config-zos.md b/config-zos.md index b0fdc252c..a00e5a578 100644 --- a/config-zos.md +++ b/config-zos.md @@ -1,20 +1,56 @@ -_This document is a work in progress._ - # z/OS Container Configuration This document describes the schema for the [z/OS-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md). +The z/OS container specification uses z/OS UNIX kernel features like namespaces and filesystem jails to fulfill the spec. + +Applications expecting a z/OS environment will very likely expect these file paths to be set up correctly. + +The following filesystems SHOULD be made available in each container's filesystem: + +| Path | Type | +| -------- | ------ | +| /proc | [proc][] | + +## Namespaces + +A namespace wraps a global system resource in an abstraction that makes it appear to the processes within the namespace that they have their own isolated instance of the global resource. +Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes. +For more information, see https://www.ibm.com/docs/zos/latest?topic=planning-namespaces-zos-unix. + +Namespaces are specified as an array of entries inside the `namespaces` root field. +The following parameters can be specified to set up namespaces: -## Devices +* **`type`** *(string, REQUIRED)* - namespace type. The following namespace types SHOULD be supported: + * **`pid`** processes inside the container will only be able to see other processes inside the same container or inside the same pid namespace. + * **`mount`** the container will have an isolated mount table. + * **`ipc`** processes inside the container will only be able to communicate to other processes inside the same container via system level IPC. + * **`uts`** the container will be able to have its own hostname and domain name. +* **`path`** *(string, OPTIONAL)* - namespace file. + This value MUST be an absolute path in the [runtime mount namespace](glossary.md#runtime-namespace). + The runtime MUST place the container process in the namespace associated with that `path`. + The runtime MUST [generate an error](runtime.md#errors) if `path` is not associated with a namespace of type `type`. -**`devices`** (array of objects, OPTIONAL) lists devices that MUST be available in the container. -The runtime MAY supply them however it likes. + If `path` is not specified, the runtime MUST create a new [container namespace](glossary.md#container-namespace) of type `type`. -Each entry has the following structure: +If a namespace type is not specified in the `namespaces` array, the container MUST inherit the [runtime namespace](glossary.md#runtime-namespace) of that type. +If a `namespaces` field contains duplicated namespaces with same `type`, the runtime MUST [generate an error](runtime.md#errors). -* **`type`** *(string, REQUIRED)* - type of device: `c`, `b`, `u` or `p`. -* **`path`** *(string, REQUIRED)* - full path to device inside container. - If a file already exists at `path` that does not match the requested device, the runtime MUST generate an error. -* **`major, minor`** *(int64, REQUIRED unless `type` is `p`)* - major, minor numbers for the device. -* **`fileMode`** *(uint32, OPTIONAL)* - file mode for the device. +### Example -The same `type`, `major` and `minor` SHOULD NOT be used for multiple devices. +```json +"namespaces": [ + { + "type": "pid", + "path": "/proc/1234/ns/pid" + }, + { + "type": "mount" + }, + { + "type": "ipc" + }, + { + "type": "uts" + } +] +``` diff --git a/config.md b/config.md index 704bbaa2f..33878b2b6 100644 --- a/config.md +++ b/config.md @@ -353,6 +353,12 @@ For Linux-based systems, the `process` object supports the following process-spe CPU affinity after the process is moved to container's cgroup, and the final affinity is determined by the Linux kernel. +### z/OS Process + +For z/OS-based systems, the `process` object supports the following process-specific properties. + +* **`noNewPrivileges`** (bool, OPTIONAL) setting `noNewPrivileges` to true prevents the process from gaining additional privileges. + ### User The user for the process is a platform-specific structure that allows specific control over which user the process runs as. diff --git a/schema/config-zos.json b/schema/config-zos.json index 971056923..13cabfca3 100644 --- a/schema/config-zos.json +++ b/schema/config-zos.json @@ -3,10 +3,14 @@ "description": "z/OS platform-specific configurations", "type": "object", "properties": { - "devices": { + "namespaces": { "type": "array", "items": { - "$ref": "defs-zos.json#/definitions/Device" + "anyOf": [ + { + "$ref": "defs-zos.json#/definitions/NamespaceReference" + } + ] } } } diff --git a/schema/defs-zos.json b/schema/defs-zos.json index cf3051dac..e15e281af 100644 --- a/schema/defs-zos.json +++ b/schema/defs-zos.json @@ -1,55 +1,27 @@ { "definitions": { - "Major": { - "description": "major device number", - "$ref": "defs.json#/definitions/int64" - }, - "Minor": { - "description": "minor device number", - "$ref": "defs.json#/definitions/int64" - }, - "FileMode": { - "description": "File permissions mode (typically an octal value)", - "type": "integer", - "minimum": 0, - "maximum": 512 - }, - "FileType": { - "description": "Type of a block or special character device", + "NamespaceType": { "type": "string", - "pattern": "^[cbup]$" + "enum": [ + "mount", + "pid", + "uts", + "ipc" + ] }, - "Device": { + "NamespaceReference": { "type": "object", - "required": [ - "type", - "path", - "major", - "minor" - ], "properties": { - "path": { - "$ref": "defs.json#/definitions/FilePath" - }, "type": { - "$ref": "#/definitions/FileType" + "$ref": "#/definitions/NamespaceType" }, - "major": { - "$ref": "#/definitions/Major" - }, - "minor": { - "$ref": "#/definitions/Minor" - }, - "fileMode": { - "$ref": "#/definitions/FileMode" - }, - "uid": { - "$ref": "defs.json#/definitions/UID" - }, - "gid": { - "$ref": "defs.json#/definitions/GID" + "path": { + "$ref": "defs.json#/definitions/FilePath" } - } + }, + "required": [ + "type" + ] } } } diff --git a/schema/test/config/good/zos-example.json b/schema/test/config/good/zos-example.json new file mode 100644 index 000000000..cb9cfca61 --- /dev/null +++ b/schema/test/config/good/zos-example.json @@ -0,0 +1,138 @@ +{ + "ociVersion": "0.5.0-dev", + "process": { + "terminal": true, + "user": { + "uid": 1, + "gid": 1, + "additionalGids": [ + 5, + 6 + ] + }, + "args": [ + "sh" + ], + "env": [ + "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/bin", + "TERM=xterm" + ], + "cwd": "/", + "rlimits": [ + { + "type": "RLIMIT_NOFILE", + "hard": 1024, + "soft": 1024 + } + ], + "noNewPrivileges": true + }, + "root": { + "path": "rootfs" + }, + "hostname": "slartibartfast", + "mounts": [ + { + "destination": "/proc", + "type": "proc", + "source": "proc" + }, + { + "destination": "/dev", + "type": "tfs", + "source": "tmpfs", + "options": [ + "nosuid", + "-p 1755", + "-s 64" + ] + } + ], + "hooks": { + "prestart": [ + { + "path": "/usr/bin/fix-mounts", + "args": [ + "fix-mounts", + "arg1", + "arg2" + ], + "env": [ + "key1=value1" + ] + }, + { + "path": "/usr/bin/setup-network" + } + ], + "createRuntime": [ + { + "path": "/usr/bin/fix-mounts", + "args": [ + "fix-mounts", + "arg1", + "arg2" + ], + "env": [ + "key1=value1" + ] + }, + { + "path": "/usr/bin/setup-network" + } + ], + "createContainer": [ + { + "path": "/usr/bin/mount-hook", + "args": [ + "-mount", + "arg1", + "arg2" + ], + "env": [ + "key1=value1" + ] + } + ], + "startContainer": [ + { + "path": "/usr/bin/refresh-ldcache" + } + ], + "poststart": [ + { + "path": "/usr/bin/notify-start", + "timeout": 5 + } + ], + "poststop": [ + { + "path": "/usr/sbin/cleanup.sh", + "args": [ + "cleanup.sh", + "-f" + ] + } + ] + }, + "zos": { + "namespaces": [ + { + "type": "pid" + }, + { + "type": "ipc" + }, + { + "type": "uts" + }, + { + "type": "mount" + } + ] + }, + "annotations": { + "com.example.key1": "value1", + "com.example.key2": "value2" + } +} diff --git a/specs-go/config.go b/specs-go/config.go index f7a78d51b..9e90f59dc 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -83,7 +83,7 @@ type Process struct { // Rlimits specifies rlimit options to apply to the process. Rlimits []POSIXRlimit `json:"rlimits,omitempty" platform:"linux,solaris,zos"` // NoNewPrivileges controls whether additional privileges could be gained by processes in the container. - NoNewPrivileges bool `json:"noNewPrivileges,omitempty" platform:"linux"` + NoNewPrivileges bool `json:"noNewPrivileges,omitempty" platform:"linux,zos"` // ApparmorProfile specifies the apparmor profile for the container. ApparmorProfile string `json:"apparmorProfile,omitempty" platform:"linux"` // Specify an oom_score_adj for the container. @@ -846,28 +846,33 @@ type LinuxIntelRdt struct { // ZOS contains platform-specific configuration for z/OS based containers. type ZOS struct { - // Devices are a list of device nodes that are created for the container - Devices []ZOSDevice `json:"devices,omitempty"` + // Namespaces contains the namespaces that are created and/or joined by the container + Namespaces []ZOSNamespace `json:"namespaces,omitempty"` } -// ZOSDevice represents the mknod information for a z/OS special device file -type ZOSDevice struct { - // Path to the device. - Path string `json:"path"` - // Device type, block, char, etc. - Type string `json:"type"` - // Major is the device's major number. - Major int64 `json:"major"` - // Minor is the device's minor number. - Minor int64 `json:"minor"` - // FileMode permission bits for the device. - FileMode *os.FileMode `json:"fileMode,omitempty"` - // UID of the device. - UID *uint32 `json:"uid,omitempty"` - // Gid of the device. - GID *uint32 `json:"gid,omitempty"` +// ZOSNamespace is the configuration for a z/OS namespace +type ZOSNamespace struct { + // Type is the type of namespace + Type ZOSNamespaceType `json:"type"` + // Path is a path to an existing namespace persisted on disk that can be joined + // and is of the same type + Path string `json:"path,omitempty"` } +// ZOSNamespaceType is one of the z/OS namespaces +type ZOSNamespaceType string + +const ( + // PIDNamespace for isolating process IDs + ZOSPIDNamespace ZOSNamespaceType = "pid" + // MountNamespace for isolating mount points + ZOSMountNamespace ZOSNamespaceType = "mount" + // IPCNamespace for isolating System V IPC, POSIX message queues + ZOSIPCNamespace ZOSNamespaceType = "ipc" + // UTSNamespace for isolating hostname and NIS domain name + ZOSUTSNamespace ZOSNamespaceType = "uts" +) + // LinuxSchedulerPolicy represents different scheduling policies used with the Linux Scheduler type LinuxSchedulerPolicy string