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 `