From d49c29f0423a08cd2085c1f81cdf535989be4a55 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 17 Sep 2016 22:01:53 -0700 Subject: [PATCH] config: Replace "required" with "REQUIRED" In all of these cases we want to use the RFC 2119 semantics. Generated with: $ sed -i 's/required/REQUIRED/g' config*.md after which I rolled back the change for: ...controllers required to fulfill... since that was already MUSTed. Signed-off-by: W. Trevor King --- config-linux.md | 26 +++++++++++++------------- config.md | 28 ++++++++++++++-------------- 2 files changed, 27 insertions(+), 27 deletions(-) diff --git a/config-linux.md b/config-linux.md index 63df9250..996b546a 100644 --- a/config-linux.md +++ b/config-linux.md @@ -26,7 +26,7 @@ For more information, see [the man page](http://man7.org/linux/man-pages/man7/na 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 namespaces types are supported: +* **`type`** *(string, REQUIRED)* - namespace type. The following namespaces 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. @@ -104,10 +104,10 @@ The runtime may supply them however it likes (with [mknod][mknod.2], by bind mou The following parameters can be specified: -* **`type`** *(string, required)* - type of device: `c`, `b`, `u` or `p`. +* **`type`** *(string, REQUIRED)* - type of device: `c`, `b`, `u` or `p`. 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. +* **`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. You can also control access to devices [with cgroups](#device-whitelist). * **`uid`** *(uint32, OPTIONAL)* - id of device owner. @@ -204,7 +204,7 @@ 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. +* **`allow`** *(boolean, REQUIRED)* - whether the entry is allowed or denied. * **`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. @@ -347,15 +347,15 @@ The following parameters can be specified to setup the controller: * **`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: - * **`major, minor`** *(int64, required)* - major, minor numbers for device. More info in `man mknod`. + * **`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 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: - * **`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)* - major, minor numbers for device. More info in `man mknod`. + * **`rate`** *(uint64, REQUIRED)* - IO rate limit for the device ###### Example @@ -401,9 +401,9 @@ For more information, see the [kernel cgroups documentation about HugeTLB][cgrou `hugepageLimits` is an array of entries, each having the following structure: -* **`pageSize`** *(string, required)* - hugepage size +* **`pageSize`** *(string, REQUIRED)* - hugepage size -* **`limit`** *(uint64, required)* - limit in bytes of *hugepagesize* HugeTLB usage +* **`limit`** *(uint64, REQUIRED)* - limit in bytes of *hugepagesize* HugeTLB usage ###### Example @@ -427,8 +427,8 @@ The following parameters can be specified to setup these cgroup controllers: * **`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 + * **`name`** *(string, REQUIRED)* - interface name + * **`priority`** *(uint32, REQUIRED)* - priority applied to the interface ###### Example @@ -455,7 +455,7 @@ 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)* - specifies the maximum number of tasks in the cgroup ###### Example diff --git a/config.md b/config.md index 8422073c..ccd3bf80 100644 --- a/config.md +++ b/config.md @@ -10,7 +10,7 @@ Below is a detailed description of each field defined in the configuration forma ## Specification version -* **`ociVersion`** (string, required) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the Open Container Runtime Specification with which the bundle complies. +* **`ociVersion`** (string, REQUIRED) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the Open Container Runtime Specification with which the bundle complies. The Open Container Runtime Specification follows semantic versioning and retains forward and backward compatibility within major versions. For example, if a configuration is compliant with version 1.1 of this specification, it is compatible with all runtimes that support any 1.1 or later release of this specification, but is not compatible with a runtime that supports 1.0 and not 1.1. @@ -22,9 +22,9 @@ For example, if a configuration is compliant with version 1.1 of this specificat ## Root Configuration -**`root`** (object, required) configures the container's root filesystem. +**`root`** (object, REQUIRED) configures the container's root filesystem. -* **`path`** (string, required) Specifies the path to the root filesystem for the container. +* **`path`** (string, REQUIRED) Specifies the path to the root filesystem for the container. 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. @@ -45,12 +45,12 @@ For example, if a configuration is compliant with version 1.1 of this specificat 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). -* **`destination`** (string, required) Destination of mount point: path inside container. +* **`destination`** (string, REQUIRED) Destination of mount point: path inside container. For the Windows operating system, one mount destination MUST NOT be nested within another mount (e.g., c:\\foo and c:\\foo\\bar). -* **`type`** (string, required) The filesystem type of the filesystem to be mounted. +* **`type`** (string, REQUIRED) The filesystem type of the filesystem to be mounted. Linux: *filesystemtype* argument supported by the kernel are listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660"). Windows: ntfs. -* **`source`** (string, required) A device name, but can also be a directory name or a dummy. +* **`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. Linux: [supported][mount.8-filesystem-independent] [options][mount.8-filesystem-specific] are listed in [mount(8)][mount.8]. @@ -92,15 +92,15 @@ See links for details about [mountvol](http://ss64.com/nt/mountvol.html) and [Se ## Process configuration -**`process`** (object, required) configures the container process. +**`process`** (object, REQUIRED) configures the container process. * **`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. +* **`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. 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. +* **`args`** (array of strings, REQUIRED) executable to launch and any flags as an array. The executable is the first element and MUST be available at the given path inside of the rootfs. If the executable path is not an absolute path then the search $PATH is interpreted to find the executable. @@ -126,8 +126,8 @@ 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][container-namespace]. -* **`gid`** (int, required) specifies the group ID in the [container namespace][container-namespace]. +* **`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. _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)_ @@ -230,11 +230,11 @@ For Windows based systems the user structure has the following fields: **`platform`** specifies the configuration's target platform. -* **`os`** (string, required) specifies the operating system family this image targets. +* **`os`** (string, REQUIRED) specifies the operating system family this image targets. The runtime MUST generate an error if it does not support the configured **`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. -* **`arch`** (string, required) specifies the instruction set for which the binaries in the image have been compiled. +* **`arch`** (string, REQUIRED) specifies the instruction set for which the binaries in the image have been compiled. The runtime MUST generate an error if it does not support the configured **`arch`**. Values for **`arch`** SHOULD use, and runtimes SHOULD understand, **`arch`** entries listed in the Go Language document for [`$GOARCH`][go-environment]. If an architecture is not included in the `$GOARCH` documentation, it SHOULD be submitted to this specification for standardization. @@ -341,7 +341,7 @@ If a hook returns a non-zero exit code, then an error is logged and the remainin } ``` -`path` is required for a hook. +`path` is REQUIRED for a hook. `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).