diff --git a/config-linux.md b/config-linux.md index d457184e4..8ceb30404 100644 --- a/config-linux.md +++ b/config-linux.md @@ -39,7 +39,7 @@ The following parameters can be specified to set up namespaces: 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`. - If `path` is not specified, the runtime MUST create a new [container namespace](glossary.md#container-namespace) of type `type`. + If `path` is [unset](glossary.md#set), the runtime MUST create a new [container namespace](glossary.md#container-namespace) of type `type`. 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). @@ -176,9 +176,9 @@ The path to the cgroups can be specified in the Spec via `cgroupsPath`. If `cgroupsPath` is: * ... an absolute path (starting with `/`), the runtime MUST take the path to be relative to the cgroup mount point. * ... a relative path (not starting with `/`), the runtime MAY interpret the path relative to a runtime-determined location in the cgroup hierarchy. -* ... not specified, the runtime MAY define the default cgroup path. +* ... [unset](glossary.md#set), the runtime MAY define the default cgroup path. Runtimes MAY consider certain `cgroupsPath` values to be invalid, and MUST generate an error if this is the case. -If a `cgroupsPath` value is specified, the runtime MUST consistently attach to the same place in the cgroup hierarchy given the same value of `cgroupsPath`. +If a `cgroupsPath` value is [set](glossary.md#set), the runtime MUST consistently attach to the same place in the cgroup hierarchy given the same value of `cgroupsPath`. Implementations of the Spec can choose to name cgroups in any manner. The Spec does not include naming schema for cgroups. @@ -186,8 +186,8 @@ The Spec does not support per-controller paths for the reasons discussed in the The cgroups will be created if they don't exist. You can configure a container's cgroups via the `resources` field of the Linux configuration. -Do not specify `resources` unless limits have to be updated. -For example, to run a new process in an existing container without updating limits, `resources` need not be specified. +Do not [set](glossary.md#set) `resources` unless limits have to be updated. +To run a new process in an existing container without updating limits, `resources` SHOULD be [unset](glossary.md#set). Runtimes MAY attach the container process to additional cgroup controllers beyond those necessary to fulfill the `resources` settings. @@ -218,9 +218,9 @@ Each entry has the following structure: * **`allow`** *(boolean, REQUIRED)* - whether the entry is allowed or denied. * **`type`** *(string, OPTIONAL)* - type of device: `a` (all), `c` (char), or `b` (block). - Unset values mean "all", mapping to `a`. + Defaults to `a`. * **`major, minor`** *(int64, OPTIONAL)* - [major, minor numbers][devices] for the device. - Unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices]. + Defaults to `*`, the semantics of which are documented [in the filesystem API][cgroup-v1-devices]. * **`access`** *(string, OPTIONAL)* - cgroup permissions for device. A composition of `r` (read), `w` (write), and `m` (mknod). @@ -335,7 +335,7 @@ The following parameters can be specified to set up the controller: * **`weight`** *(uint16, OPTIONAL)* - bandwidth rate for the device. * **`leafWeight`** *(uint16, OPTIONAL)* - bandwidth rate for the device while competing with the cgroup's child cgroups, CFQ scheduler only - You MUST specify at least one of `weight` or `leafWeight` in a given entry, and MAY specify both. + You MUST [set](glossary.md#set) at least one of `weight` or `leafWeight` in a given entry, and MAY [set](glossary.md#set) both. * **`blkioThrottleReadBpsDevice`**, **`blkioThrottleWriteBpsDevice`**, **`blkioThrottleReadIOPSDevice`**, **`blkioThrottleWriteIOPSDevice`** *(array of objects, OPTIONAL)* - specify the list of devices which will be IO rate limited. The following parameters can be specified per-device: @@ -451,17 +451,17 @@ The following parameters can be specified to set up the controller: ## IntelRdt **`intelRdt`** (object, OPTIONAL) represents the [Intel Resource Director Technology][intel-rdt-cat-kernel-interface]. - If `intelRdt` is set, the runtime MUST write the container process ID to the `/tasks` file in a mounted `resctrl` pseudo-filesystem, using the container ID from [`start`](runtime.md#start) and creating the `` directory if necessary. + If `intelRdt` is [set](glossary.md#set), the runtime MUST write the container process ID to the `/tasks` file in a mounted `resctrl` pseudo-filesystem, using the container ID from [`start`](runtime.md#start) and creating the `` directory if necessary. If no mounted `resctrl` pseudo-filesystem is available in the [runtime mount namespace](glossary.md#runtime-namespace), the runtime MUST [generate an error](runtime.md#errors). - If `intelRdt` is not set, the runtime MUST NOT manipulate any `resctrl` psuedo-filesystems. + If `intelRdt` is [unset](glossary.md#set), the runtime MUST NOT manipulate any `resctrl` psuedo-filesystems. The following parameters can be specified for the container: * **`l3CacheSchema`** *(string, OPTIONAL)* - specifies the schema for L3 cache id and capacity bitmask (CBM). - If `l3CacheSchema` is set, runtimes MUST write the value to the `schemata` file in the `` directory discussed in `intelRdt`. + If `l3CacheSchema` is [set](glossary.md#set), runtimes MUST write the value to the `schemata` file in the `` directory discussed in `intelRdt`. - If `l3CacheSchema` is not set, runtimes MUST NOT write to `schemata` files in any `resctrl` psuedo-filesystems. + If `l3CacheSchema` is [unset](glossary.md#set), runtimes MUST NOT write to `schemata` files in any `resctrl` psuedo-filesystems. ### Example @@ -528,7 +528,7 @@ The following parameters can be specified to set up seccomp: * **`syscalls`** *(array of objects, OPTIONAL)* - match a syscall in seccomp. While this property is OPTIONAL, some values of `defaultAction` are not useful without `syscalls` entries. - For example, if `defaultAction` is `SCMP_ACT_KILL` and `syscalls` is empty or unset, the kernel will kill the container process on its first syscall. + For example, if `defaultAction` is `SCMP_ACT_KILL` and `syscalls` is empty or [unset](glossary.md#set), the kernel will kill the container process on its first syscall. Each entry has the following structure: diff --git a/config-solaris.md b/config-solaris.md index 4446a166a..4decb26ed 100644 --- a/config-solaris.md +++ b/config-solaris.md @@ -84,11 +84,11 @@ For additional information on properties, check the [zonecfg(1M)][zonecfg.1m_2] * **`lowerLink`** *(string, OPTIONAL)* Specify the link over which the VNIC will be created. Mapped to `lower-link` in the [zonecfg(1M)][zonecfg.1m_2] man page. * **`allowedAddress`** *(string, OPTIONAL)* The set of IP addresses that the container can use might be constrained by specifying the `allowedAddress` property. - If `allowedAddress` has not been specified, then they can use any IP address on the associated physical interface for the network resource. - Otherwise, when `allowedAddress` is specified, the container cannot use IP addresses that are not in the `allowedAddress` list for the physical address. + If `allowedAddress` is [unset](glossary.md#set), then they can use any IP address on the associated physical interface for the network resource. + Otherwise, when `allowedAddress` is [set](glossary.md#set), the container cannot use IP addresses that are not in the `allowedAddress` list for the physical address. Mapped to `allowed-address` in the [zonecfg(1M)][zonecfg.1m_2] man page. -* **`configureAllowedAddress`** *(string, OPTIONAL)* If `configureAllowedAddress` is set to true, the addresses specified by `allowedAddress` are automatically configured on the interface each time the container starts. - When it is set to false, the `allowedAddress` will not be configured on container start. +* **`configureAllowedAddress`** *(string, OPTIONAL)* If `configureAllowedAddress` is `true`, the addresses specified by `allowedAddress` are automatically configured on the interface each time the container starts. + When it is `false`, the `allowedAddress` will not be configured on container start. Mapped to `configure-allowed-address` in the [zonecfg(1M)][zonecfg.1m_2] man page. * **`defrouter`** *(string, OPTIONAL)* The value for the OPTIONAL default router. * **`macAddress`** *(string, OPTIONAL)* Set the VNIC's MAC addresses based on the specified value or keyword. diff --git a/config-windows.md b/config-windows.md index 2c5dda921..bb702722e 100644 --- a/config-windows.md +++ b/config-windows.md @@ -155,14 +155,14 @@ You can indicate that a container should be started in an a mode where disk flus ## HyperV `hyperv` is an OPTIONAL field of the Windows configuration. -If present, the container MUST be run with Hyper-V isolation. -If omitted, the container MUST be run as a Windows Server container. +If [set](glossary.md#set), the container MUST be run with Hyper-V isolation. +If [unset](glossary.md#set), the container MUST be run as a Windows Server container. The following parameters can be specified: * **`utilityVMPath`** *(string, OPTIONAL)* - specifies the path to the image used for the utility VM. This would be specified if using a base image which does not contain a utility VM image. - If not supplied, the runtime will search the container filesystem layers from the bottom-most layer upwards, until it locates "UtilityVM", and default to that path. + If [unset](glossary.md#set), the runtime MUST search the container filesystem layers from the bottom-most layer upwards, until it locates "UtilityVM", and default to that path. ### Example diff --git a/config.md b/config.md index 78de158cf..4a06ecb7b 100644 --- a/config.md +++ b/config.md @@ -32,14 +32,15 @@ For all platform-specific configuration values, the scope defined below in the [ The path is either an absolute path or a relative path to the bundle. Users SHOULD consider using a conventional name, such as `rootfs`. - * On Windows, for Windows Server Containers, this field is REQUIRED and MUST be specified as a [volume GUID path][naming-a-volume]. - For Hyper-V Containers, this field MUST be omitted. + * On Windows, for Windows Server Containers, this field is REQUIRED and MUST be a [volume GUID path][naming-a-volume]. + For Hyper-V Containers, this field MUST be [unset](glossary.md#set). * On all other platforms, this field is REQUIRED. * On Linux, for example, with a bundle at `/to/bundle` and a root filesystem at `/to/bundle/rootfs`, the `path` value can be either `/to/bundle/rootfs` or `rootfs`. If defined, a directory MUST exist at the path declared by the field. -* **`readonly`** (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container, defaults to false. - * On Windows, this field MUST be omitted or false. +* **`readonly`** (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container. + Defaults to `false`. + * On Windows, this field MUST be [unset](glossary.md#set) or `false`. ### Example (POSIX) @@ -173,8 +174,8 @@ For Linux-based systems the process structure supports the following process-spe * **`apparmorProfile`** (string, OPTIONAL) specifies the name of the AppArmor profile to be applied to processes in the container. For more information about AppArmor, see [AppArmor documentation][apparmor]. * **`oomScoreAdj`** *(int, OPTIONAL)* adjusts the oom-killer score in `[pid]/oom_score_adj` for the container process's `[pid]` in a [proc pseudo-filesystem][procfs]. - If `oomScoreAdj` is set, the runtime MUST set `oom_score_adj` to the given value. - If `oomScoreAdj` is not set, the runtime MUST NOT change the value of `oom_score_adj`. + If `oomScoreAdj` is [set](glossary.md#set), the runtime MUST set `oom_score_adj` to the given value. + If `oomScoreAdj` is [unset](glossary.md#set), the runtime MUST NOT change the value of `oom_score_adj`. This is a per-process setting, where as [`disableOOMKiller`](config-linux.md#disable-out-of-memory-killer) is scoped for a memory cgroup. For more information on how these two settings work together, see [the memory cgroup documentation section 10. OOM Contol][cgroup-v1-memory_2]. @@ -343,11 +344,11 @@ For Windows based systems the user structure has the following fields: Runtime implementations MAY support any valid values for platform-specific fields as part of this configuration. * **`linux`** (object, OPTIONAL) [Linux-specific configuration](config-linux.md). - This MAY be set if **`platform.os`** is `linux` and MUST NOT be set otherwise. + This MAY be [set](glossary.md#set) if **`platform.os`** is `linux` and MUST be [unset](glossary.md#set) otherwise. * **`windows`** (object, OPTIONAL) [Windows-specific configuration](config-windows.md). - This MUST be set if **`platform.os`** is `windows` and MUST NOT be set otherwise. + This MUST be [set](glossary.md#set) if **`platform.os`** is `windows` and MUST NOT be set otherwise. * **`solaris`** (object, OPTIONAL) [Solaris-specific configuration](config-solaris.md). - This MAY be set if **`platform.os`** is `solaris` and MUST NOT be set otherwise. + This MAY be [set](glossary.md#set) if **`platform.os`** is `solaris` and MUST be [unset](glossary.md#set) otherwise. ### Example (Linux) @@ -380,7 +381,7 @@ On Linux, they are run after the container namespaces are created. * **`args`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2001 `execv`'s *argv*][ieee-1003.1-2001-xsh-exec]. * **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2001's `environ`][ieee-1003.1-2001-xbd-c8.1]. * **`timeout`** (int, OPTIONAL) is the number of seconds before aborting the hook. - If set, `timeout` MUST be greater than zero. + If [set](glossary.md#set), `timeout` MUST be greater than zero. * **`poststart`** (array of objects, OPTIONAL) is an array of [post-start hooks](#poststart). Entries in the array have the same schema as pre-start entries. * **`poststop`** (array of objects, OPTIONAL) is an array of [post-stop hooks](#poststop). diff --git a/glossary.md b/glossary.md index 09f80e421..b6bb68d7d 100644 --- a/glossary.md +++ b/glossary.md @@ -33,6 +33,9 @@ It reads the [configuration files](#configuration) from a [bundle](#bundle), use On Linux, a leaf in the [namespace][namespaces.7] hierarchy from which the [runtime](#runtime) process is executed. New container namespaces will be created as children of the runtime namespaces. +## Set + +A property is "set" if its key appears in the parent JSON object and "unset" if its key does not appear in the parent JSON object. [JSON]: https://tools.ietf.org/html/rfc7159 [UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf diff --git a/runtime.md b/runtime.md index b9c3b94d7..df7a7760e 100644 --- a/runtime.md +++ b/runtime.md @@ -117,7 +117,7 @@ This operation MUST [generate an error](#errors) if it is not provided the conta Attempting to start a container that does not exist MUST [generate an error](#errors). Attempting to start an already started container MUST have no effect on the container and MUST [generate an error](#errors). This operation MUST run the user-specified program as specified by [`process`](config.md#process). -This operation MUST generate an error if `process` was not set. +This operation MUST generate an error if `process` was [unset](glossary.md#set). ### Kill `kill `