opencontainers · kershawmehta · Aug 30, 2024 · AkihiroSuda · Jan 8, 2025 · kershawmehta
@@ -1,20 +1,56 @@
-_This document is a work in progress._
-
 # <a name="ZOSContainerConfiguration" />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][] |
+
+## <a name="configZOSNamespaces" />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:
 
-## <a name="configZOSDevices" />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"
+    }
+]
+```
@@ -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.
 
+### <a name="configZOSProcess" />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.
+
 ### <a name="configUser" />User
 
 The user for the process is a platform-specific structure that allows specific control over which user the process runs as.

@@ -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"
+                        }
+                    ]
                 }
             }
         }

@@ -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"
+            ]
         }
     }
 }
@@ -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"
+    }
+}
@@ -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