jasder
/
runc
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

config: Replace "optional" with "OPTIONAL" 

In all of these cases we want to use the RFC 2119 semantics.
Generated with:

  $ sed -i 's/optional/OPTIONAL/g' config*.md

Signed-off-by: W. Trevor King <wking@tremily.us>
This commit is contained in:
W. Trevor King 2016-09-17 21:59:07 -07:00
parent 2239827079
commit c35cf57303
3 changed files with 63 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
config-linux.md
View File

@ -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)* - path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace)
* **`path`** *(string, OPTIONAL)* - 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.
@ -99,7 +99,7 @@ There is a limit of 5 mappings which is the Linux kernel hard limit.
## Devices
**`devices`** (array, optional) lists devices that MUST be available in the container.
**`devices`** (array, OPTIONAL) 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.).
The following parameters can be specified:
@ -108,10 +108,10 @@ The following parameters can be specified:
More info in [mknod(1)][mknod.1].
* **`path`** *(string, required)* - full path to device inside container.
* **`major, minor`** *(int64, required unless **`type`** is `p`)* - [major, minor numbers][devices] for the device.
* **`fileMode`** *(uint32, optional)* - file mode for the device.
* **`fileMode`** *(uint32, OPTIONAL)* - 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)* - id of device owner.
* **`gid`** *(uint32, OPTIONAL)* - id of device group.
###### Example
@ -199,17 +199,17 @@ However, a runtime MAY attach the container process to additional cgroup control
#### Device whitelist
**`devices`** (array, optional) configures the [device whitelist][cgroup-v1-devices].
**`devices`** (array, OPTIONAL) configures the [device whitelist][cgroup-v1-devices].
The runtime MUST apply entries in the listed order.
The following parameters can be specified:
* **`allow`** *(boolean, required)* - whether the entry is allowed or denied.
* **`type`** *(string, optional)* - type of device: `a` (all), `c` (char), or `b` (block).
* **`type`** *(string, OPTIONAL)* - 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)* - [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)* - cgroup permissions for device.
A composition of `r` (read), `w` (write), and `m` (mknod).
###### Example
@ -245,7 +245,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)* - enables or disables the OOM killer
###### Example
@ -260,7 +260,7 @@ For more information, see [the proc filesystem documentation section 3.1](https:
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)* - adjust the oom-killer score
###### Example
@ -275,17 +275,17 @@ 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)* - sets limit of memory usage in bytes
* **`reservation`** *(uint64, optional)* - sets soft limit of memory usage in bytes
* **`reservation`** *(uint64, OPTIONAL)* - sets soft limit of memory usage in bytes
* **`swap`** *(uint64, optional)* - sets limit of memory+Swap usage
* **`swap`** *(uint64, OPTIONAL)* - sets limit of memory+Swap usage
* **`kernel`** *(uint64, optional)* - sets hard limit for kernel memory
* **`kernel`** *(uint64, OPTIONAL)* - sets hard limit for kernel memory
* **`kernelTCP`** *(uint64, optional)* - sets hard limit in bytes for kernel TCP buffer memory
* **`kernelTCP`** *(uint64, OPTIONAL)* - 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)* - sets swappiness parameter of vmscan (See sysctl's vm.swappiness)
###### Example
@ -307,19 +307,19 @@ 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)* - specifies a relative share of CPU time available to the tasks in a cgroup
* **`quota`** *(uint64, 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`** *(uint64, 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)
* **`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)* - specifies a period of time in microseconds for how regularly a cgroup's access to CPU resources should be reallocated (CFS scheduler only)
* **`realtimeRuntime`** *(uint64, 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`** *(uint64, 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
* **`realtimePeriod`** *(uint64, optional)* - same as **`period`** but applies to realtime scheduler only
* **`realtimePeriod`** *(uint64, OPTIONAL)* - same as **`period`** but applies to realtime scheduler only
* **`cpus`** *(string, optional)* - list of CPUs the container will run in
* **`cpus`** *(string, OPTIONAL)* - list of CPUs the container will run in
* **`mems`** *(string, optional)* - list of Memory Nodes the container will run in
* **`mems`** *(string, OPTIONAL)* - list of Memory Nodes the container will run in
###### Example
@ -342,18 +342,18 @@ For more information, see [the kernel cgroups documentation about blkio][cgroup-
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)* - 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)* - 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, optional)* - specifies the list of devices which will be bandwidth rate limited. The following parameters can be specified per-device:
* **`blkioWeightDevice`** *(array, 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
* **`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
You must specify at least one of `weight` or `leafWeight` in a given entry, and can specify both.
* **`blkioThrottleReadBpsDevice`**, **`blkioThrottleWriteBpsDevice`**, **`blkioThrottleReadIOPSDevice`**, **`blkioThrottleWriteIOPSDevice`** *(array, optional)* - specify the list of devices which will be IO rate limited. The following parameters can be specified per-device:
* **`blkioThrottleReadBpsDevice`**, **`blkioThrottleWriteBpsDevice`**, **`blkioThrottleReadIOPSDevice`**, **`blkioThrottleWriteIOPSDevice`** *(array, OPTIONAL)* - 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
@ -423,9 +423,9 @@ For more information, see [the net\_cls cgroup man page][cgroup-v1-net-cls] and
The following parameters can be specified to setup these cgroup controllers:
* **`classID`** *(uint32, optional)* - is the network class identifier the cgroup's network packets will be tagged with
* **`classID`** *(uint32, OPTIONAL)* - is the network class identifier the cgroup's network packets will be tagged with
* **`priorities`** *(array, optional)* - specifies a list of objects of the priorities assigned to traffic originating from
* **`priorities`** *(array, 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. The following parameters can be specified per-priority:
* **`name`** *(string, required)* - interface name
* **`priority`** *(uint32, required)* - priority applied to the interface

26
config-solaris.md
View File

@ -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)*
### 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) man page for the respective release of Solaris.
**`limitpriv`** *(string, optional)*
**`limitpriv`** *(string, OPTIONAL)*
### 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) man page.
**`maxShmMemory`** *(string, optional)*
**`maxShmMemory`** *(string, OPTIONAL)*
### 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) man page.
* **`ncpus`** *(string, optional)*
* **`ncpus`** *(string, OPTIONAL)*
### 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) man page.
* **`physical`** *(string, optional)*
* **`swap`** *(string, optional)*
* **`physical`** *(string, OPTIONAL)*
* **`swap`** *(string, OPTIONAL)*
### 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 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)* Specify a name for the automatically created VNIC datalink.
* **`lowerLink`** *(string, OPTIONAL)* Specify the link over which the VNIC will be created.
Mapped to lower-link in the 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)* 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) 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)* 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) 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)* The value for the OPTIONAL default router.
* **`macAddress`** *(string, OPTIONAL)* 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) man page of the respective Solaris release.
Mapped to mac-address in the zonecfg(1M) man page.
* **`linkProtection`** *(string, optional)* Enables one or more types of link protection using comma-separated values.
* **`linkProtection`** *(string, OPTIONAL)* 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) man page.

36
config.md
View File

@ -28,7 +28,7 @@ For example, if a configuration is compliant with version 1.1 of this specificat
The path can be an absolute path (starting with /) or a relative path (not starting with /), which is relative to the bundle.
For example (Linux), 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`.
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.
* **`readonly`** (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container, defaults to false.
### Example
@ -41,7 +41,7 @@ For example, if a configuration is compliant with version 1.1 of this specificat
## Mounts
**`mounts`** (array, optional) configures additional mounts (on top of [`root`](#root-configuration)).
**`mounts`** (array, OPTIONAL) configures additional mounts (on top of [`root`](#root-configuration)).
The runtime MUST mount entries in the listed order.
The parameters are similar to the ones in [the Linux mount system call](http://man7.org/linux/man-pages/man2/mount.2.html).
@ -52,7 +52,7 @@ The parameters are similar to the ones in [the Linux mount system call](http://m
Windows: ntfs.
* **`source`** (string, required) A device name, but can also be a directory name or a dummy.
Windows: the volume name that is the target of the mount point, \\?\Volume\{GUID}\ (on Windows source is called target).
* **`options`** (list of strings, optional) Mount options of the filesystem to be used.
* **`options`** (list of strings, OPTIONAL) Mount options of the filesystem to be used.
Linux: [supported][mount.8-filesystem-independent] [options][mount.8-filesystem-specific] are listed in [mount(8)][mount.8].
### Example (Linux)
@ -94,10 +94,10 @@ See links for details about [mountvol](http://ss64.com/nt/mountvol.html) and [Se
**`process`** (object, required) configures the container process.
* **`terminal`** (bool, optional) specifies whether you want a terminal attached to that process, defaults to false.
* **`terminal`** (bool, OPTIONAL) specifies whether you want a terminal attached to that process, defaults to false.
* **`cwd`** (string, required) is the working directory that will be set for the executable.
This value MUST be an absolute path.
* **`env`** (array of strings, optional) contains a list of variables that will be set in the process's environment prior to execution.
* **`env`** (array of strings, OPTIONAL) contains a list of variables that will be set in the process's environment prior to execution.
Elements in the array are specified as Strings in the form "KEY=value".
The left hand side MUST consist solely of letters, digits, and underscores `_` as outlined in [IEEE Std 1003.1-2001](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html).
* **`args`** (array of strings, required) executable to launch and any flags as an array.
@ -106,16 +106,16 @@ See links for details about [mountvol](http://ss64.com/nt/mountvol.html) and [Se
For Linux-based systems the process structure supports the following process specific fields:
* **`capabilities`** (array of strings, optional) capabilities is an array that specifies Linux capabilities that can be provided to the process inside the container.
* **`capabilities`** (array of strings, OPTIONAL) capabilities is an array that specifies Linux capabilities that can be provided to the process inside the container.
Valid values are the strings for capabilities defined in [the man page](http://man7.org/linux/man-pages/man7/capabilities.7.html)
* **`rlimits`** (array of rlimits, optional) rlimits is an array of rlimits that allows setting resource limits for a process inside the container.
* **`rlimits`** (array of rlimits, OPTIONAL) rlimits is an array of rlimits that allows setting resource limits for a process inside the container.
The kernel enforces the `soft` limit for a resource while the `hard` limit acts as a ceiling for that value that could be set by an unprivileged process.
Valid values for the 'type' field are the resources defined in [the man page](http://man7.org/linux/man-pages/man2/setrlimit.2.html).
* **`apparmorProfile`** (string, optional) apparmor profile specifies the name of the apparmor profile that will be used for the container.
* **`apparmorProfile`** (string, OPTIONAL) apparmor profile specifies the name of the apparmor profile that will be used for the container.
For more information about Apparmor, see [Apparmor documentation](https://wiki.ubuntu.com/AppArmor)
* **`selinuxLabel`** (string, optional) SELinux process label specifies the label with which the processes in a container are run.
* **`selinuxLabel`** (string, OPTIONAL) SELinux process label specifies the label with which the processes in a container are run.
For more information about SELinux, see [Selinux documentation](http://selinuxproject.org/page/Main_Page)
* **`noNewPrivileges`** (bool, optional) setting `noNewPrivileges` to true prevents the processes in the container from gaining additional privileges.
* **`noNewPrivileges`** (bool, OPTIONAL) setting `noNewPrivileges` to true prevents the processes in the container from gaining additional privileges.
[The kernel doc](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt) has more information on how this is achieved using a prctl system call.
### User
@ -128,7 +128,7 @@ For Linux and Solaris based systems the user structure has the following fields:
* **`uid`** (int, required) specifies the user ID in the [container namespace][container-namespace].
* **`gid`** (int, required) specifies the group ID in the [container namespace][container-namespace].
* **`additionalGids`** (array of ints, optional) specifies additional group IDs (in the [container namespace][container-namespace]) to be added to the process.
* **`additionalGids`** (array of ints, OPTIONAL) specifies additional group IDs (in the [container namespace][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)_
@ -194,7 +194,7 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th
For Windows based systems the user structure has the following fields:
* **`username`** (string, optional) specifies the user name for the process.
* **`username`** (string, OPTIONAL) specifies the user name for the process.
### Example (Windows)
@ -217,7 +217,7 @@ For Windows based systems the user structure has the following fields:
## Hostname
* **`hostname`** (string, optional) configures the container's hostname as seen by processes running inside the container.
* **`hostname`** (string, OPTIONAL) configures the container's hostname as seen by processes running inside the container.
On Linux, you can only set this if your bundle creates a new [UTS namespace][uts-namespace].
### Example
@ -252,9 +252,9 @@ For Windows based systems the user structure has the following fields:
[**`platform.os`**](#platform) is used to lookup further platform-specific configuration.
* **`linux`** (object, optional) [Linux-specific configuration](config-linux.md).
* **`linux`** (object, OPTIONAL) [Linux-specific configuration](config-linux.md).
This SHOULD only be set if **`platform.os`** is `linux`.
* **`solaris`** (object, optional) [Solaris-specific configuration](config-solaris.md).
* **`solaris`** (object, OPTIONAL) [Solaris-specific configuration](config-solaris.md).
This SHOULD only be set if **`platform.os`** is `solaris`.
### Example (Linux)
@ -277,7 +277,7 @@ For Windows based systems the user structure has the following fields:
## Hooks
**`hooks`** (object, optional) configures callbacks for container lifecycle events.
**`hooks`** (object, OPTIONAL) configures callbacks for container lifecycle events.
Lifecycle hooks allow custom events for different points in a container's runtime.
Presently there are `Prestart`, `Poststart` and `Poststop`.
@ -342,13 +342,13 @@ If a hook returns a non-zero exit code, then an error is logged and the remainin
```
`path` is required for a hook.
`args` and `env` are optional.
`args` and `env` are OPTIONAL.
`timeout` is the number of seconds before aborting the hook.
The semantics are the same as `Path`, `Args` and `Env` in [golang Cmd](https://golang.org/pkg/os/exec/#Cmd).
## Annotations
**`annotations`** (object, optional) contains arbitrary metadata for the container.
**`annotations`** (object, OPTIONAL) contains arbitrary metadata for the container.
This information MAY be structured or unstructured.
Annotations MUST be a key-value map where both the key and value MUST be strings.
While the value MUST be present, it MAY be an empty string.