diff --git a/config-linux.md b/config-linux.md index 873982fc2..703b37b85 100644 --- a/config-linux.md +++ b/config-linux.md @@ -26,7 +26,7 @@ For more information, see the [namespaces(7)][namespaces.7_2] man page. Namespaces are specified as an array of entries inside the `namespaces` root field. The following parameters can be specified to setup namespaces: -* **`type`** *(string, REQUIRED)* - namespace type. The following namespace types are supported: +* **`type`** *(string, REQUIRED, linux)* - namespace type. The following namespace types are supported: * **`pid`** processes inside the container will only be able to see other processes inside the same container. * **`network`** the container will have its own network stack. * **`mount`** the container will have an isolated mount table. @@ -35,7 +35,7 @@ The following parameters can be specified to setup namespaces: * **`user`** the container will be able to remap user and group IDs from the host to local users and groups within the container. * **`cgroup`** the container will have an isolated view of the cgroup hierarchy. -* **`path`** *(string, OPTIONAL)* - an absolute path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace) +* **`path`** *(string, OPTIONAL, linux)* - an absolute path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace) If a path is specified, that particular file is used to join that type of namespace. 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. @@ -73,14 +73,14 @@ If a `namespaces` field contains duplicated namespaces with same `type`, the run ## User namespace mappings -**`uidMappings`** (array of objects, OPTIONAL) describes the user namespace uid mappings from the host to the container. -**`gidMappings`** (array of objects, OPTIONAL) describes the user namespace gid mappings from the host to the container. +**`uidMappings`** (array of objects, OPTIONAL, linux) describes the user namespace uid mappings from the host to the container. +**`gidMappings`** (array of objects, OPTIONAL, linux) describes the user namespace gid mappings from the host to the container. Each entry has the following structure: -* **`hostID`** *(uint32, REQUIRED)* - is the starting uid/gid on the host to be mapped to *containerID*. -* **`containerID`** *(uint32, REQUIRED)* - is the starting uid/gid in the container. -* **`size`** *(uint32, REQUIRED)* - is the number of ids to be mapped. +* **`hostID`** *(uint32, REQUIRED, linux)* - is the starting uid/gid on the host to be mapped to *containerID*. +* **`containerID`** *(uint32, REQUIRED, linux)* - is the starting uid/gid in the container. +* **`size`** *(uint32, REQUIRED, linux)* - is the number of ids to be mapped. The runtime SHOULD NOT modify the ownership of referenced filesystems to realize the mapping. Note that the number of mapping entries MAY be limited by the [kernel][user-namespaces]. @@ -106,20 +106,20 @@ Note that the number of mapping entries MAY be limited by the [kernel][user-name ## Devices -**`devices`** (array of objects, OPTIONAL) lists devices that MUST be available in the container. +**`devices`** (array of objects, OPTIONAL, linux) lists devices that MUST be available in the container. The runtime may supply them however it likes (with [mknod][mknod.2], by bind mounting from the runtime mount namespace, etc.). Each entry has the following structure: -* **`type`** *(string, REQUIRED)* - type of device: `c`, `b`, `u` or `p`. +* **`type`** *(string, REQUIRED, linux)* - type of device: `c`, `b`, `u` or `p`. More info in [mknod(1)][mknod.1]. -* **`path`** *(string, REQUIRED)* - full path to device inside container. +* **`path`** *(string, REQUIRED, linux)* - full path to device inside container. If a [file][file.1] 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][devices] for the device. -* **`fileMode`** *(uint32, OPTIONAL)* - file mode for the device. +* **`major, minor`** *(int64, REQUIRED unless `type` is `p`, linux)* - [major, minor numbers][devices] for the device. +* **`fileMode`** *(uint32, OPTIONAL, linux)* - file mode for the device. You can also control access to devices [with cgroups](#device-whitelist). -* **`uid`** *(uint32, OPTIONAL)* - id of device owner. -* **`gid`** *(uint32, OPTIONAL)* - id of device group. +* **`uid`** *(uint32, OPTIONAL, linux)* - id of device owner. +* **`gid`** *(uint32, OPTIONAL, linux)* - id of device group. The same `type`, `major` and `minor` SHOULD NOT be used for multiple devices. @@ -209,17 +209,17 @@ However, a runtime MAY attach the container process to additional cgroup control #### Device whitelist -**`devices`** (array of objects, OPTIONAL) configures the [device whitelist][cgroup-v1-devices]. +**`devices`** (array of objects, OPTIONAL, linux) configures the [device whitelist][cgroup-v1-devices]. The runtime MUST apply entries in the listed order. 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). +* **`allow`** *(boolean, REQUIRED, linux)* - whether the entry is allowed or denied. +* **`type`** *(string, OPTIONAL, linux)* - type of device: `a` (all), `c` (char), or `b` (block). `null` or unset values mean "all", mapping to `a`. -* **`major, minor`** *(int64, OPTIONAL)* - [major, minor numbers][devices] for the device. +* **`major, minor`** *(int64, OPTIONAL, linux)* - [major, minor numbers][devices] for the device. `null` or unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices]. -* **`access`** *(string, OPTIONAL)* - cgroup permissions for device. +* **`access`** *(string, OPTIONAL, linux)* - cgroup permissions for device. A composition of `r` (read), `w` (write), and `m` (mknod). ###### Example @@ -255,7 +255,7 @@ The OOM killer is enabled by default in every cgroup using the `memory` subsyste To disable it, specify a value of `true`. For more information, see [the memory cgroup man page][cgroup-v1-memory]. -* **`disableOOMKiller`** *(bool, OPTIONAL)* - enables or disables the OOM killer +* **`disableOOMKiller`** *(bool, OPTIONAL, linux)* - enables or disables the OOM killer ###### Example @@ -270,7 +270,7 @@ For more information, see [the proc filesystem documentation section 3.1][procfs This is a kernel/system level setting, where as `disableOOMKiller` 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]. -* **`oomScoreAdj`** *(int, OPTIONAL)* - adjust the oom-killer score +* **`oomScoreAdj`** *(int, OPTIONAL, linux)* - adjust the oom-killer score ###### Example @@ -280,22 +280,22 @@ For more information on how these two settings work together, see [the memory cg #### Memory -**`memory`** (object, OPTIONAL) represents the cgroup subsystem `memory` and it's used to set limits on the container's memory usage. +**`memory`** (object, OPTIONAL, linux) represents the cgroup subsystem `memory` and it's used to set limits on the container's memory usage. For more information, see [the memory cgroup man page][cgroup-v1-memory]. The following parameters can be specified to setup the controller: -* **`limit`** *(uint64, OPTIONAL)* - sets limit of memory usage in bytes +* **`limit`** *(uint64, OPTIONAL, linux)* - sets limit of memory usage in bytes -* **`reservation`** *(uint64, OPTIONAL)* - sets soft limit of memory usage in bytes +* **`reservation`** *(uint64, OPTIONAL, linux)* - sets soft limit of memory usage in bytes -* **`swap`** *(uint64, OPTIONAL)* - sets limit of memory+Swap usage +* **`swap`** *(uint64, OPTIONAL, linux)* - sets limit of memory+Swap usage -* **`kernel`** *(uint64, OPTIONAL)* - sets hard limit for kernel memory +* **`kernel`** *(uint64, OPTIONAL, linux)* - sets hard limit for kernel memory -* **`kernelTCP`** *(uint64, OPTIONAL)* - sets hard limit in bytes for kernel TCP buffer memory +* **`kernelTCP`** *(uint64, OPTIONAL, linux)* - sets hard limit in bytes for kernel TCP buffer memory -* **`swappiness`** *(uint64, OPTIONAL)* - sets swappiness parameter of vmscan (See sysctl's vm.swappiness) +* **`swappiness`** *(uint64, OPTIONAL, linux)* - sets swappiness parameter of vmscan (See sysctl's vm.swappiness) ###### Example @@ -312,24 +312,24 @@ The following parameters can be specified to setup the controller: #### CPU -**`cpu`** (object, OPTIONAL) represents the cgroup subsystems `cpu` and `cpusets`. +**`cpu`** (object, OPTIONAL, linux) represents the cgroup subsystems `cpu` and `cpusets`. For more information, see [the cpusets cgroup man page][cgroup-v1-cpusets]. The following parameters can be specified to setup the controller: -* **`shares`** *(uint64, OPTIONAL)* - specifies a relative share of CPU time available to the tasks in a cgroup +* **`shares`** *(uint64, OPTIONAL, linux)* - specifies a relative share of CPU time available to the tasks in a cgroup -* **`quota`** *(int64, OPTIONAL)* - specifies the total amount of time in microseconds for which all tasks in a cgroup can run during one period (as defined by **`period`** below) +* **`quota`** *(int64, OPTIONAL, linux)* - specifies the total amount of time in microseconds for which all tasks in a cgroup can run during one period (as defined by **`period`** below) -* **`period`** *(uint64, OPTIONAL)* - specifies a period of time in microseconds for how regularly a cgroup's access to CPU resources should be reallocated (CFS scheduler only) +* **`period`** *(uint64, OPTIONAL, linux)* - specifies a period of time in microseconds for how regularly a cgroup's access to CPU resources should be reallocated (CFS scheduler only) -* **`realtimeRuntime`** *(int64, OPTIONAL)* - specifies a period of time in microseconds for the longest continuous period in which the tasks in a cgroup have access to CPU resources +* **`realtimeRuntime`** *(int64, OPTIONAL, linux)* - specifies a period of time in microseconds for the longest continuous period in which the tasks in a cgroup have access to CPU resources -* **`realtimePeriod`** *(uint64, OPTIONAL)* - same as **`period`** but applies to realtime scheduler only +* **`realtimePeriod`** *(uint64, OPTIONAL, linux)* - same as **`period`** but applies to realtime scheduler only -* **`cpus`** *(string, OPTIONAL)* - list of CPUs the container will run in +* **`cpus`** *(string, OPTIONAL, linux)* - list of CPUs the container will run in -* **`mems`** *(string, OPTIONAL)* - list of Memory Nodes the container will run in +* **`mems`** *(string, OPTIONAL, linux)* - list of Memory Nodes the container will run in ###### Example @@ -347,26 +347,26 @@ The following parameters can be specified to setup the controller: #### Block IO -**`blockIO`** (object, OPTIONAL) represents the cgroup subsystem `blkio` which implements the block IO controller. +**`blockIO`** (object, OPTIONAL, linux) represents the cgroup subsystem `blkio` which implements the block IO controller. For more information, see [the kernel cgroups documentation about blkio][cgroup-v1-blkio]. The following parameters can be specified to setup the controller: -* **`blkioWeight`** *(uint16, OPTIONAL)* - specifies per-cgroup weight. This is default weight of the group on all devices until and unless overridden by per-device rules. The range is from 10 to 1000. +* **`blkioWeight`** *(uint16, OPTIONAL, linux)* - specifies per-cgroup weight. This is default weight of the group on all devices until and unless overridden by per-device rules. The range is from 10 to 1000. -* **`blkioLeafWeight`** *(uint16, OPTIONAL)* - equivalents of `blkioWeight` for the purpose of deciding how much weight tasks in the given cgroup has while competing with the cgroup's child cgroups. The range is from 10 to 1000. +* **`blkioLeafWeight`** *(uint16, OPTIONAL, linux)* - equivalents of `blkioWeight` for the purpose of deciding how much weight tasks in the given cgroup has while competing with the cgroup's child cgroups. The range is from 10 to 1000. -* **`blkioWeightDevice`** *(array of objects, OPTIONAL)* - specifies the list of devices which will be bandwidth rate limited. The following parameters can be specified per-device: - * **`major, minor`** *(int64, REQUIRED)* - major, minor numbers for device. More info in `man mknod`. - * **`weight`** *(uint16, OPTIONAL)* - bandwidth rate for the device, range is from 10 to 1000 - * **`leafWeight`** *(uint16, OPTIONAL)* - bandwidth rate for the device while competing with the cgroup's child cgroups, range is from 10 to 1000, CFQ scheduler only +* **`blkioWeightDevice`** *(array of objects, OPTIONAL, linux)* - specifies the list of devices which will be bandwidth rate limited. The following parameters can be specified per-device: + * **`major, minor`** *(int64, REQUIRED, linux)* - major, minor numbers for device. More info in `man mknod`. + * **`weight`** *(uint16, OPTIONAL, linux)* - bandwidth rate for the device, range is from 10 to 1000 + * **`leafWeight`** *(uint16, OPTIONAL, linux)* - bandwidth rate for the device while competing with the cgroup's child cgroups, range is from 10 to 1000, CFQ scheduler only You MUST specify at least one of `weight` or `leafWeight` in a given entry, and MAY specify both. -* **`blkioThrottleReadBpsDevice`**, **`blkioThrottleWriteBpsDevice`**, **`blkioThrottleReadIOPSDevice`**, **`blkioThrottleWriteIOPSDevice`** *(array of objects, OPTIONAL)* - specify the list of devices which will be IO rate limited. +* **`blkioThrottleReadBpsDevice`**, **`blkioThrottleWriteBpsDevice`**, **`blkioThrottleReadIOPSDevice`**, **`blkioThrottleWriteIOPSDevice`** *(array of objects, OPTIONAL, linux)* - specify the list of devices which will be IO rate limited. The following parameters can be specified per-device: - * **`major, minor`** *(int64, REQUIRED)* - major, minor numbers for device. More info in `man mknod`. - * **`rate`** *(uint64, REQUIRED)* - IO rate limit for the device + * **`major, minor`** *(int64, REQUIRED, linux)* - major, minor numbers for device. More info in `man mknod`. + * **`rate`** *(uint64, REQUIRED, linux)* - IO rate limit for the device ###### Example @@ -406,15 +406,15 @@ The following parameters can be specified to setup the controller: #### Huge page limits -**`hugepageLimits`** (array of objects, OPTIONAL) represents the `hugetlb` controller which allows to limit the +**`hugepageLimits`** (array of objects, OPTIONAL, linux) represents the `hugetlb` controller which allows to limit the HugeTLB usage per control group and enforces the controller limit during page fault. For more information, see the [kernel cgroups documentation about HugeTLB][cgroup-v1-hugetlb]. Each entry has the following structure: -* **`pageSize`** *(string, REQUIRED)* - hugepage size +* **`pageSize`** *(string, REQUIRED, linux)* - hugepage size -* **`limit`** *(uint64, REQUIRED)* - limit in bytes of *hugepagesize* HugeTLB usage +* **`limit`** *(uint64, REQUIRED, linux)* - limit in bytes of *hugepagesize* HugeTLB usage ###### Example @@ -429,17 +429,16 @@ Each entry has the following structure: #### Network -**`network`** (object, OPTIONAL) represents the cgroup subsystems `net_cls` and `net_prio`. +**`network`** (object, OPTIONAL, linux) represents the cgroup subsystems `net_cls` and `net_prio`. For more information, see [the net\_cls cgroup man page][cgroup-v1-net-cls] and [the net\_prio cgroup man page][cgroup-v1-net-prio]. The following parameters can be specified to setup the controller: -* **`classID`** *(uint32, OPTIONAL)* - is the network class identifier the cgroup's network packets will be tagged with - -* **`priorities`** *(array of objects, OPTIONAL)* - specifies a list of objects of the priorities assigned to traffic originating from processes in the group and egressing the system on various interfaces. +* **`classID`** *(uint32, OPTIONAL, linux)* - is the network class identifier the cgroup's network packets will be tagged with +* **`priorities`** *(array of objects, OPTIONAL, linux)* - specifies a list of objects of the priorities assigned to traffic originating from processes in the group and egressing the system on various interfaces. The following parameters can be specified per-priority: - * **`name`** *(string, REQUIRED)* - interface name - * **`priority`** *(uint32, REQUIRED)* - priority applied to the interface + * **`name`** *(string, REQUIRED, linux)* - interface name + * **`priority`** *(uint32, REQUIRED, linux)* - priority applied to the interface ###### Example @@ -461,12 +460,12 @@ The following parameters can be specified to setup the controller: #### PIDs -**`pids`** (object, OPTIONAL) represents the cgroup subsystem `pids`. +**`pids`** (object, OPTIONAL, linux) represents the cgroup subsystem `pids`. For more information, see [the pids cgroup man page][cgroup-v1-pids]. The following parameters can be specified to setup the controller: -* **`limit`** *(int64, REQUIRED)* - specifies the maximum number of tasks in the cgroup +* **`limit`** *(int64, REQUIRED, linux)* - specifies the maximum number of tasks in the cgroup ###### Example @@ -540,13 +539,13 @@ check if it is valid when writing. e.g., 0xfffff in root indicates the max bits of CBM is 20 bits, which mapping to entire L3 cache capacity. Some valid CBM values to set in a group: 0xf, 0xf0, 0x3ff, 0x1f00 and etc. -**`intelRdt`** (object, OPTIONAL) represents the L3 cache resource constraints in Intel Xeon platforms. +**`intelRdt`** (object, OPTIONAL, linux) represents the L3 cache resource constraints in Intel Xeon platforms. For more information, see [Intel RDT/CAT kernel interface][intel-rdt-cat-kernel-interface]. The following parameters can be specified for the container: -* **`l3CacheSchema`** *(string, OPTIONAL)* - specifies the schema for L3 cache id and capacity bitmask (CBM) +* **`l3CacheSchema`** *(string, OPTIONAL, linux)* - specifies the schema for L3 cache id and capacity bitmask (CBM) ###### Example ```json @@ -563,7 +562,7 @@ id 0 and the whole L3 cache id 1 for the container: ## Sysctl -**`sysctl`** (object, OPTIONAL) allows kernel parameters to be modified at runtime for the container. +**`sysctl`** (object, OPTIONAL, linux) allows kernel parameters to be modified at runtime for the container. For more information, see the [sysctl(8)][sysctl.8] man page. ###### Example @@ -582,13 +581,13 @@ Seccomp configuration allows one to configure actions to take for matched syscal For more information about Seccomp, see [Seccomp][seccomp] kernel documentation. The actions, architectures, and operators are strings that match the definitions in seccomp.h from [libseccomp][] and are translated to corresponding values. -**`seccomp`** (object, OPTIONAL) +**`seccomp`** (object, OPTIONAL, linux) The following parameters can be specified to setup seccomp: -* **`defaultAction`** *(string, REQUIRED)* - the default action for seccomp. Allowed values are the same as `syscalls[].action`. +* **`defaultAction`** *(string, REQUIRED, linux)* - the default action for seccomp. Allowed values are the same as `syscalls[].action`. -* **`architectures`** *(array of strings, OPTIONAL)* - the architecture used for system calls. +* **`architectures`** *(array of strings, OPTIONAL, linux)* - the architecture used for system calls. A valid list of constants as of libseccomp v2.3.2 is shown below. * `SCMP_ARCH_X86` @@ -610,13 +609,13 @@ The following parameters can be specified to setup seccomp: * `SCMP_ARCH_PARISC` * `SCMP_ARCH_PARISC64` -* **`syscalls`** *(array of objects, REQUIRED)* - match a syscall in seccomp. +* **`syscalls`** *(array of objects, REQUIRED, linux)* - match a syscall in seccomp. Each entry has the following structure: - * **`names`** *(array of strings, REQUIRED)* - the names of the syscalls. + * **`names`** *(array of strings, REQUIRED, linux)* - the names of the syscalls. - * **`action`** *(string, REQUIRED)* - the action for seccomp rules. + * **`action`** *(string, REQUIRED, linux)* - the action for seccomp rules. A valid list of constants as of libseccomp v2.3.2 is shown below. * `SCMP_ACT_KILL` @@ -625,17 +624,17 @@ The following parameters can be specified to setup seccomp: * `SCMP_ACT_TRACE` * `SCMP_ACT_ALLOW` - * **`args`** *(array of objects, OPTIONAL)* - the specific syscall in seccomp. + * **`args`** *(array of objects, OPTIONAL, linux)* - the specific syscall in seccomp. Each entry has the following structure: - * **`index`** *(uint, REQUIRED)* - the index for syscall arguments in seccomp. + * **`index`** *(uint, REQUIRED, linux)* - the index for syscall arguments in seccomp. - * **`value`** *(uint64, REQUIRED)* - the value for syscall arguments in seccomp. + * **`value`** *(uint64, REQUIRED, linux)* - the value for syscall arguments in seccomp. - * **`valueTwo`** *(uint64, REQUIRED)* - the value for syscall arguments in seccomp. + * **`valueTwo`** *(uint64, REQUIRED, linux)* - the value for syscall arguments in seccomp. - * **`op`** *(string, REQUIRED)* - the operator for syscall arguments in seccomp. + * **`op`** *(string, REQUIRED, linux)* - the operator for syscall arguments in seccomp. A valid list of constants as of libseccomp v2.3.2 is shown below. * `SCMP_CMP_NE` @@ -669,7 +668,7 @@ The following parameters can be specified to setup seccomp: ## Rootfs Mount Propagation -**`rootfsPropagation`** (string, OPTIONAL) sets the rootfs's mount propagation. +**`rootfsPropagation`** (string, OPTIONAL, linux) sets the rootfs's mount propagation. Its value is either slave, private, or shared. The [Shared Subtrees][sharedsubtree] article in the kernel documentation has more information about mount propagation. @@ -681,7 +680,7 @@ The [Shared Subtrees][sharedsubtree] article in the kernel documentation has mor ## Masked Paths -**`maskedPaths`** (array of strings, OPTIONAL) will mask over the provided paths inside the container so that they cannot be read. +**`maskedPaths`** (array of strings, OPTIONAL, linux) will mask over the provided paths inside the container so that they cannot be read. The values MUST be absolute paths in the [container namespace][container-namespace2]. ###### Example @@ -694,7 +693,7 @@ The values MUST be absolute paths in the [container namespace][container-namespa ## Readonly Paths -**`readonlyPaths`** (array of strings, OPTIONAL) will set the provided paths as readonly inside the container. +**`readonlyPaths`** (array of strings, OPTIONAL, linux) will set the provided paths as readonly inside the container. The values MUST be absolute paths in the [container namespace][container-namespace2]. ###### Example @@ -707,7 +706,7 @@ The values MUST be absolute paths in the [container namespace][container-namespa ## Mount Label -**`mountLabel`** (string, OPTIONAL) will set the Selinux context for the mounts in the container. +**`mountLabel`** (string, OPTIONAL, linux) will set the Selinux context for the mounts in the container. ###### Example diff --git a/config-solaris.md b/config-solaris.md index 7654b6b00..60ff27934 100644 --- a/config-solaris.md +++ b/config-solaris.md @@ -5,7 +5,7 @@ Solaris application containers can be configured using the following properties, ## milestone The SMF(Service Management Facility) FMRI which should go to "online" state before we start the desired process within the container. -**`milestone`** *(string, OPTIONAL)* +**`milestone`** *(string, OPTIONAL, solaris)* ### Example ```json @@ -16,7 +16,7 @@ The SMF(Service Management Facility) FMRI which should go to "online" state befo The maximum set of privileges any process in this container can obtain. The property should consist of a comma-separated privilege set specification as described in [priv_str_to_set(3C)][priv-str-to-set.3c] man page for the respective release of Solaris. -**`limitpriv`** *(string, OPTIONAL)* +**`limitpriv`** *(string, OPTIONAL, solaris)* ### Example ```json @@ -28,7 +28,7 @@ The maximum amount of shared memory allowed for this application container. A scale (K, M, G, T) can be applied to the value for each of these numbers (for example, 1M is one megabyte). Mapped to `max-shm-memory` in [zonecfg(1M)][zonecfg.1m] man page. -**`maxShmMemory`** *(string, OPTIONAL)* +**`maxShmMemory`** *(string, OPTIONAL, solaris)* ### Example ```json @@ -42,7 +42,7 @@ An ncpu value of 1 means 100% of a CPU, a value of 1.25 means 125%, .75 mean 75% When projects within a capped container have their own caps, the minimum value takes precedence. cappedCPU is mapped to `capped-cpu` in [zonecfg(1M)][zonecfg.1m] man page. -* **`ncpus`** *(string, OPTIONAL)* +* **`ncpus`** *(string, OPTIONAL, solaris)* ### Example ```json @@ -56,8 +56,8 @@ The physical and swap caps on the memory that can be used by this application co A scale (K, M, G, T) can be applied to the value for each of these numbers (for example, 1M is one megabyte). cappedMemory is mapped to `capped-memory` in [zonecfg(1M)][zonecfg.1m] man page. -* **`physical`** *(string, OPTIONAL)* -* **`swap`** *(string, OPTIONAL)* +* **`physical`** *(string, OPTIONAL, solaris)* +* **`swap`** *(string, OPTIONAL, solaris)* ### Example ```json @@ -80,22 +80,22 @@ The VNIC is deleted when the container is torn down. The following properties can be used to setup automatic networks. For additional information on properties, check the [zonecfg(1M)][zonecfg.1m] man page for the respective release of Solaris. -* **`linkname`** *(string, OPTIONAL)* Specify a name for the automatically created VNIC datalink. -* **`lowerLink`** *(string, OPTIONAL)* Specify the link over which the VNIC will be created. +* **`linkname`** *(string, OPTIONAL, solaris)* Specify a name for the automatically created VNIC datalink. +* **`lowerLink`** *(string, OPTIONAL, solaris)* Specify the link over which the VNIC will be created. Mapped to `lower-link` in the [zonecfg(1M)][zonecfg.1m] man page. -* **`allowedAddress`** *(string, OPTIONAL)* The set of IP addresses that the container can use might be constrained by specifying the allowedAddress property. +* **`allowedAddress`** *(string, OPTIONAL, solaris)* 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. Mapped to `allowed-address` in the [zonecfg(1M)][zonecfg.1m] 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. +* **`configureAllowedAddress`** *(string, OPTIONAL, solaris)* 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. Mapped to `configure-allowed-address` in the [zonecfg(1M)][zonecfg.1m] 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. +* **`defrouter`** *(string, OPTIONAL, solaris)* The value for the OPTIONAL default router. +* **`macAddress`** *(string, OPTIONAL, solaris)* Set the VNIC's MAC addresses based on the specified value or keyword. If not a keyword, it is interpreted as a unicast MAC address. For a list of the supported keywords please refer to the [zonecfg(1M)][zonecfg.1m] man page of the respective Solaris release. Mapped to `mac-address` in the [zonecfg(1M)][zonecfg.1m] man page. -* **`linkProtection`** *(string, OPTIONAL)* Enables one or more types of link protection using comma-separated values. +* **`linkProtection`** *(string, OPTIONAL, solaris)* Enables one or more types of link protection using comma-separated values. See the protection property in dladm(8) for supported values in respective release of Solaris. Mapped to `link-protection` in the [zonecfg(1M)][zonecfg.1m] man page. diff --git a/config-windows.md b/config-windows.md index 883998fb8..2d43f4d0d 100644 --- a/config-windows.md +++ b/config-windows.md @@ -5,17 +5,19 @@ The Windows container specification uses APIs provided by the Windows Host Compu ## Resources -You can configure a container's resource limits via the OPTIONAL `resources` field of the Windows configuration. +**`resources`** (object, OPTIONAL, windows) configurs the container's resource limits. + +The following subsections specify parameters for `resources`. ### Memory -`memory` is an OPTIONAL configuration for the container's memory usage. +**`memory`** *(object, OPTIONAL, windows)* configures the container's memory usage. The following parameters can be specified: -* **`limit`** *(uint64, OPTIONAL)* - sets limit of memory usage in bytes. +* **`limit`** *(uint64, OPTIONAL, windows)* - sets limit of memory usage in bytes. -* **`reservation`** *(uint64, OPTIONAL)* - sets the guaranteed minimum amount of memory for a container in bytes. +* **`reservation`** *(uint64, OPTIONAL, windows)* - sets the guaranteed minimum amount of memory for a container in bytes. #### Example @@ -32,15 +34,15 @@ The following parameters can be specified: ### CPU -`cpu` is an OPTIONAL configuration for the container's CPU usage. +**`cpu`** *(object, OPTIONAL, windows)* configures for the container's CPU usage. The following parameters can be specified: -* **`count`** *(uint64, OPTIONAL)* - specifies the number of CPUs available to the container. +* **`count`** *(uint64, OPTIONAL, windows)* - specifies the number of CPUs available to the container. -* **`shares`** *(uint16, OPTIONAL)* - specifies the relative weight to other containers with CPU shares. The range is from 1 to 10000. +* **`shares`** *(uint16, OPTIONAL, windows)* - specifies the relative weight to other containers with CPU shares. The range is from 1 to 10000. -* **`percent`** *(uint, OPTIONAL)* - specifies the percentage of available CPUs usable by the container. +* **`percent`** *(uint, OPTIONAL, windows)* - specifies the percentage of available CPUs usable by the container. #### Example @@ -56,15 +58,15 @@ The following parameters can be specified: ### Storage -`storage` is an OPTIONAL configuration for the container's storage usage. +**`storage`** *(object, OPTIONAL, windows)* configures the container's storage usage. The following parameters can be specified: -* **`iops`** *(uint64, OPTIONAL)* - specifies the maximum IO operations per second for the system drive of the container. +* **`iops`** *(uint64, OPTIONAL, windows)* - specifies the maximum IO operations per second for the system drive of the container. -* **`bps`** *(uint64, OPTIONAL)* - specifies the maximum bytes per second for the system drive of the container. +* **`bps`** *(uint64, OPTIONAL, windows)* - specifies the maximum bytes per second for the system drive of the container. -* **`sandboxSize`** *(uint64, OPTIONAL)* - specifies the minimum size of the system drive in bytes. +* **`sandboxSize`** *(uint64, OPTIONAL, windows)* - specifies the minimum size of the system drive in bytes. #### Example @@ -80,11 +82,11 @@ The following parameters can be specified: ### Network -`network` is an OPTIONAL configuration for the container's network usage. +**`network`** *(object, OPTIONAL, windows)* configures the container's network usage. The following parameters can be specified: -* **`egressBandwidth`** *(uint64, OPTIONAL)* - specified the maximum egress bandwidth in bytes per second for the container. +* **`egressBandwidth`** *(uint64, OPTIONAL, windows)* - specified the maximum egress bandwidth in bytes per second for the container. #### Example diff --git a/config.md b/config.md index efaf0a0e5..dbbe18913 100644 --- a/config.md +++ b/config.md @@ -150,12 +150,9 @@ For Windows, see [mountvol][mountvol] and [SetVolumeMountPoint][set-volume-mount * **`noNewPrivileges`** (bool, OPTIONAL) setting `noNewPrivileges` to true prevents the processes in the container from gaining additional privileges. As an example, the ['no_new_privs'][no-new-privs] article in the kernel documentation has information on how this is achieved using a prctl system call on Linux. - -For Linux-based systems the process structure supports the following process specific fields. - -* **`apparmorProfile`** (string, OPTIONAL) specifies the name of the AppArmor profile to be applied to processes in the container. +* **`apparmorProfile`** (string, OPTIONAL, linux) specifies the name of the AppArmor profile to be applied to processes in the container. For more information about AppArmor, see [AppArmor documentation][apparmor]. -* **`selinuxLabel`** (string, OPTIONAL) specifies the SELinux label to be applied to the processes in the container. +* **`selinuxLabel`** (string, OPTIONAL, linux) specifies the SELinux label to be applied to the processes in the container. For more information about SELinux, see [SELinux documentation][selinux]. ### User @@ -166,9 +163,9 @@ The user for the process is a platform-specific structure that allows specific c For Linux and Solaris based systems the user structure has the following fields: -* **`uid`** (int, REQUIRED) specifies the user ID in the [container namespace](glossary.md#container-namespace). -* **`gid`** (int, REQUIRED) specifies the group ID in the [container namespace](glossary.md#container-namespace). -* **`additionalGids`** (array of ints, OPTIONAL) specifies additional group IDs (in the [container namespace](glossary.md#container-namespace) to be added to the process. +* **`uid`** (int, REQUIRED, linux solaris) specifies the user ID in the [container namespace](glossary.md#container-namespace). +* **`gid`** (int, REQUIRED, linux solaris) specifies the group ID in the [container namespace](glossary.md#container-namespace). +* **`additionalGids`** (array of ints, OPTIONAL, linux solaris) specifies additional group IDs (in the [container namespace](glossary.md#container-namespace) to be added to the process. _Note: symbolic name for uid and gid, such as uname and gname respectively, are left to upper levels to derive (i.e. `/etc/passwd` parsing, NSS, etc)_ @@ -259,7 +256,7 @@ _Note: symbolic name for uid and gid, such as uname and gname respectively, are For Windows based systems the user structure has the following fields: -* **`username`** (string, OPTIONAL) specifies the user name for the process. +* **`username`** (string, OPTIONAL, windows) specifies the user name for the process. ### Example (Windows) @@ -297,6 +294,7 @@ For Windows based systems the user structure has the following fields: **`platform`** (object, REQUIRED) specifies the configuration's target platform. * **`os`** (string, REQUIRED) specifies the operating system family of the container configuration's specified [`root`](#root) file system bundle. + **`os`** also selects the [specification platform](spec.md#platforms), which dermines which other [properties are specified](spec.md#property-specification). The runtime MUST generate an error if it does not support the specified **`os`**. Bundles SHOULD use, and runtimes SHOULD understand, **`os`** entries listed in the Go Language document for [`GOOS`][go-environment]. If an operating system is not included in the `GOOS` documentation, it SHOULD be submitted to this specification for standardization. @@ -320,12 +318,9 @@ 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. Implementations MUST error out when invalid values are encountered and MUST generate an error message and error out when encountering valid values it chooses to not support. -* **`linux`** (object, OPTIONAL) [Linux-specific configuration](config-linux.md). - This MAY be set if **`platform.os`** is `linux` and MUST NOT be set otherwise. -* **`windows`** (object, OPTIONAL) [Windows-specific configuration](config-windows.md). - This MAY be 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. +* **`linux`** (object, OPTIONAL, linux) [Linux-specific configuration](config-linux.md). +* **`windows`** (object, OPTIONAL, windows) [Windows-specific configuration](config-windows.md). +* **`solaris`** (object, OPTIONAL, solaris) [Solaris-specific configuration](config-solaris.md). ### Example (Linux) diff --git a/spec.md b/spec.md index 3324eadc2..652f682bf 100644 --- a/spec.md +++ b/spec.md @@ -40,7 +40,37 @@ The key words "unspecified", "undefined", and "implementation-defined" are to be An implementation is not compliant for a given CPU architecture if it fails to satisfy one or more of the MUST, REQUIRED, or SHALL requirements for the [platforms](#platforms) it implements. An implementation is compliant for a given CPU architecture if it satisfies all the MUST, REQUIRED, and SHALL requirements for the [platforms](#platforms) it implements. +## Property Specification + +JSON properties are specified with the following [ABNF][rfc5234]: + +```ABNF +property = name *(", " name) " (" type ", " requirement-level [", " platforms] ")" +name = ALPHA *(ALPHA / DIGIT) +type = ALPHA *(ALPHA / DIGIT / " ") +requirement-level = ("REQUIRED" [requirement-condition]) / "OPTIONAL" +requirement-condition = ("when" / "unless") " " *(ALPHA / DIGIT / " ") +platforms = platform *(" " platform) +platform = "linux" / "solaris" / "windows" +``` + +`platforms` lists the platforms for which the property is specified. +For example, if a property specification did not list `linux` in `properties`, then the Linux specification should be read as if that property had not been mentioned. +When `platforms` is not given the property is specified on all platforms. + +When a `requirement-condition` is given, the property is REQUIRED when the condition is met and OPTIONAL when the condition is not met. + +If an OPTIONAL parent property is an object with a REQUIRED child, the child is only REQUIRED if the parent is set. +For example, with a definition like: + +* **`foo`** (object, OPTIONAL) Something about foo. + The following parameters are defined: + + * **`bar`** (int, REQUIRED) Something about bar. + +both `{}` and `{"foo": {"bar": 0}}` would be compliant, but `{"foo": {}}` would not be compliant. [c99-unspecified]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18 [oci]: http://www.opencontainers.org [rfc2119]: http://tools.ietf.org/html/rfc2119 +[rfc5234]: https://tools.ietf.org/html/rfc5234