From f9dc90b05a0bbb1a5e907c5d6f09bc05496b44ac Mon Sep 17 00:00:00 2001 From: Jesse Butler Date: Thu, 9 Feb 2017 15:32:39 -0500 Subject: [PATCH] make link usage consistent across the specification Signed-off-by: Jesse Butler --- README.md | 26 +++++++++++++-------- ROADMAP.md | 7 ++++-- bundle.md | 4 +++- config-linux.md | 38 +++++++++++++++++++------------ config-solaris.md | 35 ++++++++++++++++------------- config.md | 56 +++++++++++++++++++++++++++------------------- glossary.md | 2 ++ implementations.md | 20 ++++++++++++----- project.md | 4 +++- runtime-linux.md | 5 ++++- spec.md | 4 +++- style.md | 36 +++++++++++++++++++++++++++++ 12 files changed, 164 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 5ee88d0e7..6da5f6deb 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Open Container Initiative Runtime Specification -The [Open Container Initiative](http://www.opencontainers.org/) develops specifications for standards on Operating System process and application containers. +The [Open Container Initiative][oci] develops specifications for standards on Operating System process and application containers. The specification can be found [here](spec.md). @@ -8,7 +8,7 @@ The specification can be found [here](spec.md). Additional documentation about how this group operates: -- [Code of Conduct](https://github.com/opencontainers/tob/blob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md) +- [Code of Conduct][code-of-conduct] - [Style and Conventions](style.md) - [Roadmap](ROADMAP.md) - [Implementations](implementations.md) @@ -61,13 +61,13 @@ When in doubt, start on the [mailing-list](#mailing-list). ### Weekly Call The contributors and maintainers of all OCI projects have a weekly meeting Wednesdays at 2:00 PM (USA Pacific). -Everyone is welcome to participate via [UberConference web][UberConference] or audio-only: 415-968-0849 (no PIN needed.) +Everyone is welcome to participate via [UberConference web][uberconference] or audio-only: 415-968-0849 (no PIN needed.) An initial agenda will be posted to the [mailing list](#mailing-list) earlier in the week, and everyone is welcome to propose additional topics or suggest other agenda alterations there. -Minutes are posted to the [mailing list](#mailing-list) and minutes from past calls are archived to the [wiki](https://github.com/opencontainers/runtime-spec/wiki) for those who are unable to join the call. +Minutes are posted to the [mailing list](#mailing-list) and minutes from past calls are archived to the [wiki][runtime-wiki]. ### Mailing List -You can subscribe and join the mailing list on [Google Groups](https://groups.google.com/a/opencontainers.org/forum/#!forum/dev). +You can subscribe and join the mailing list on [Google Groups][dev-list]. ### IRC @@ -78,7 +78,7 @@ OCI discussion happens on #opencontainers on Freenode ([logs][irc-logs]). #### Sign your work The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. -The rules are pretty simple: if you can certify the below (from [developercertificate.org](http://developercertificate.org/)): +The rules are pretty simple: if you can certify the below (from http://developercertificate.org): ``` Developer Certificate of Origin @@ -130,7 +130,7 @@ You can add the sign off when creating the git commit via `git commit -s`. #### Commit Style Simple house-keeping for clean git history. -Read more on [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/) or the Discussion section of [`git-commit(1)`](http://git-scm.com/docs/git-commit). +Read more on [How to Write a Git Commit Message][how-to-git-commit] or the Discussion section of [git-commit(1)][git-commit.1]. 1. Separate the subject from body with a blank line 2. Limit the subject line to 50 characters @@ -142,6 +142,14 @@ Read more on [How to Write a Git Commit Message](http://chris.beams.io/posts/git * If there was important/useful/essential conversation or information, copy or include a reference 8. When possible, one keyword to scope the change in the subject (i.e. "README: ...", "runtime: ...") -[UberConference]: https://www.uberconference.com/opencontainers -[irc-logs]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/ + [charter]: https://www.opencontainers.org/about/governance +[code-of-conduct]: https://github.com/opencontainers/tob/blob/master/code-of-conduct.md +[dev-list]: https://groups.google.com/a/opencontainers.org/forum/#!forum/dev +[how-to-git-commit]: http://chris.beams.io/posts/git-commit +[irc-logs]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/ +[oci]: https://www.opencontainers.org +[runtime-wiki]: https://github.com/opencontainers/runtime-spec/wiki +[uberconference]: https://www.uberconference.com/opencontainers + +[git-commit.1]: http://git-scm.com/docs/git-commit diff --git a/ROADMAP.md b/ROADMAP.md index e7dcaad25..6199b9b8b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -6,7 +6,7 @@ The items in the 1.0 roadmap can be broken down into smaller milestones that are The topics below are broad and small working groups will be needed for each to define scope and requirements or if the feature is required at all for the OCI level. Topics listed in the roadmap do not mean that they will be implemented or added but are areas that need discussion to see if they fit in to the goals of the OCI. -Listed topics may defer to the [project wiki](https://github.com/opencontainers/runtime-spec/wiki/RoadMap:) for collaboration. +Listed topics may defer to the [project wiki][runtime-wiki] for collaboration. ## 1.0 @@ -32,9 +32,9 @@ Ensure that the base configuration format is viable for various platforms. Systems: +* Linux * Solaris * Windows -* Linux *Owner:* robdolinms as lead coordinator @@ -45,3 +45,6 @@ Ensure that we have lifecycle hooks in the correct places with full coverage ove Will probably go away with Vish's work on splitting create and start, and if we have exec. *Owner:* + + +[runtime-wiki]: https://github.com/opencontainers/runtime-spec/wiki/RoadMap diff --git a/bundle.md b/bundle.md index 42a7e5b97..d0fd12599 100644 --- a/bundle.md +++ b/bundle.md @@ -3,7 +3,7 @@ ## Container Format This section defines a format for encoding a container as a *filesystem bundle* - a set of files organized in a certain way, and containing all the necessary data and metadata for any compliant runtime to perform all standard operations against it. -See also [OS X application bundles](http://en.wikipedia.org/wiki/Bundle_%28OS_X%29) for a similar use of the term *bundle*. +See also [MacOS application bundles][macos_bundle] for a similar use of the term *bundle*. The definition of a bundle is only concerned with how a container, and its configuration data, are stored on a local filesystem so that it can be consumed by a compliant runtime. @@ -20,3 +20,5 @@ This directory MUST be referenced from within the `config.json` file. While these artifacts MUST all be present in a single directory on the local filesystem, that directory itself is not part of the bundle. In other words, a tar archive of a *bundle* will have these artifacts at the root of the archive, not nested within a top-level directory. + +[macos_bundle]: https://en.wikipedia.org/wiki/Bundle_%28macOS%29 diff --git a/config-linux.md b/config-linux.md index c04c9d9ea..8f5f70a3e 100644 --- a/config-linux.md +++ b/config-linux.md @@ -10,18 +10,18 @@ Applications expecting a Linux environment will very likely expect these file pa The following filesystems SHOULD be made available in each container's filesystem: -| Path | Type | +| Path | Type | | -------- | ------ | -| /proc | [proc](https://www.kernel.org/doc/Documentation/filesystems/proc.txt) | -| /sys | [sysfs](https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt) | -| /dev/pts | [devpts](https://www.kernel.org/doc/Documentation/filesystems/devpts.txt) | -| /dev/shm | [tmpfs](https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt) | +| /proc | [procfs][procfs] | +| /sys | [sysfs][sysfs] | +| /dev/pts | [devpts][devpts] | +| /dev/shm | [tmpfs][tmpfs] | ## Namespaces A namespace wraps a global system resource in an abstraction that makes it appear to the processes within the namespace that they have their own isolated instance of the global resource. Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes. -For more information, see [the man page](http://man7.org/linux/man-pages/man7/namespaces.7.html). +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: @@ -266,7 +266,7 @@ For more information, see [the memory cgroup man page][cgroup-v1-memory]. #### Set oom_score_adj `oomScoreAdj` sets heuristic regarding how the process is evaluated by the kernel during memory pressure. -For more information, see [the proc filesystem documentation section 3.1](https://www.kernel.org/doc/Documentation/filesystems/proc.txt). +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]. @@ -479,7 +479,7 @@ The following parameters can be specified to setup the controller: ## Sysctl **`sysctl`** (object, OPTIONAL) allows kernel parameters to be modified at runtime for the container. -For more information, see [the man page](http://man7.org/linux/man-pages/man8/sysctl.8.html) +For more information, see the [sysctl(8)][sysctl.8] man page. ###### Example @@ -494,8 +494,8 @@ For more information, see [the man page](http://man7.org/linux/man-pages/man8/sy Seccomp provides application sandboxing mechanism in the Linux kernel. Seccomp configuration allows one to configure actions to take for matched syscalls and furthermore also allows matching on values passed as arguments to syscalls. -For more information about Seccomp, see [Seccomp kernel documentation](https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt) -The actions, architectures, and operators are strings that match the definitions in seccomp.h from [libseccomp](https://github.com/seccomp/libseccomp) and are translated to corresponding values. +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. A valid list of constants as of libseccomp v2.3.2 is shown below. Architecture Constants @@ -560,7 +560,7 @@ Operator Constants: **`rootfsPropagation`** (string, OPTIONAL) sets the rootfs's mount propagation. Its value is either slave, private, or shared. -[The kernel doc](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) has more information about mount propagation. +The [Shared Subtrees][sharedsubtree] article in the kernel documentation has more information about mount propagation. ###### Example @@ -604,7 +604,9 @@ The values MUST be absolute paths in the [container namespace][container-namespa "mountLabel": "system_u:object_r:svirt_sandbox_file_t:s0:c715,c811" ``` + [container-namespace2]: glossary.md#container_namespace + [cgroup-v1]: https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt [cgroup-v1-blkio]: https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt [cgroup-v1-cpusets]: https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.txt @@ -617,15 +619,23 @@ The values MUST be absolute paths in the [container namespace][container-namespa [cgroup-v2]: https://www.kernel.org/doc/Documentation/cgroup-v2.txt [devices]: https://www.kernel.org/doc/Documentation/devices.txt [devpts]: https://www.kernel.org/doc/Documentation/filesystems/devpts.txt -[file.1]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_164 +[file]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_164 +[libseccomp]: https://github.com/seccomp/libseccomp +[procfs]: https://www.kernel.org/doc/Documentation/filesystems/proc.txt +[seccomp]: https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt +[sharedsubtree]: https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt +[sysfs]: https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt +[tmpfs]: https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt -[mknod.1]: http://man7.org/linux/man-pages/man1/mknod.1.html -[mknod.2]: http://man7.org/linux/man-pages/man2/mknod.2.html [console.4]: http://man7.org/linux/man-pages/man4/console.4.html [full.4]: http://man7.org/linux/man-pages/man4/full.4.html +[mknod.1]: http://man7.org/linux/man-pages/man1/mknod.1.html +[mknod.2]: http://man7.org/linux/man-pages/man2/mknod.2.html +[namespaces.7_2]: http://man7.org/linux/man-pages/man7/namespaces.7.html [null.4]: http://man7.org/linux/man-pages/man4/null.4.html [pts.4]: http://man7.org/linux/man-pages/man4/pts.4.html [random.4]: http://man7.org/linux/man-pages/man4/random.4.html +[sysctl.8]: http://man7.org/linux/man-pages/man8/sysctl.8.html [tty.4]: http://man7.org/linux/man-pages/man4/tty.4.html [zero.4]: http://man7.org/linux/man-pages/man4/zero.4.html [user-namespaces]: http://man7.org/linux/man-pages/man7/user_namespaces.7.html diff --git a/config-solaris.md b/config-solaris.md index 8343f23f9..fb28a66e0 100644 --- a/config-solaris.md +++ b/config-solaris.md @@ -1,6 +1,6 @@ # Solaris Application Container Configuration -Solaris application containers can be configured using the following properties, all of the below properties have mappings to properties specified under zonecfg(8) man page, except milestone. +Solaris application containers can be configured using the following properties, all of the below properties have mappings to properties specified under [zonecfg(1M)][zonecfg.1m_2] man page, except milestone. ## milestone The SMF(Service Management Facility) FMRI which should go to "online" state before we start the desired process within the container. @@ -14,7 +14,7 @@ The SMF(Service Management Facility) FMRI which should go to "online" state befo ## limitpriv 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. +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)* @@ -26,7 +26,7 @@ The property should consist of a comma-separated privilege set specification as ## maxShmMemory 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(8) man page. +Mapped to `max-shm-memory` in [zonecfg(1M)][zonecfg.1m] man page. **`maxShmMemory`** *(string, OPTIONAL)* @@ -40,7 +40,7 @@ Sets a limit on the amount of CPU time that can be used by a container. The unit used translates to the percentage of a single CPU that can be used by all user threads in a container, expressed as a fraction (for example, .75) or a mixed number (whole number and fraction, for example, 1.25). An ncpu value of 1 means 100% of a CPU, a value of 1.25 means 125%, .75 mean 75%, and so forth. When projects within a capped container have their own caps, the minimum value takes precedence. -cappedCPU is mapped to capped-cpu in zonecfg(8) man page. +cappedCPU is mapped to `capped-cpu` in [zonecfg(1M)][zonecfg.1m] man page. * **`ncpus`** *(string, OPTIONAL)* @@ -54,7 +54,7 @@ cappedCPU is mapped to capped-cpu in zonecfg(8) man page. ## cappedMemory The physical and swap caps on the memory that can be used by 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). -cappedMemory is mapped to capped-memory in zonecfg(8) man page. +cappedMemory is mapped to `capped-memory` in [zonecfg(1M)][zonecfg.1m] man page. * **`physical`** *(string, OPTIONAL)* * **`swap`** *(string, OPTIONAL)* @@ -73,31 +73,31 @@ cappedMemory is mapped to capped-memory in zonecfg(8) man page. anet is specified as an array that is used to setup networking for Solaris application containers. The anet resource represents the automatic creation of a network resource for an application container. The zones administration daemon, zoneadmd, is the primary process for managing the container's virtual platform. -One of the daemons is responsibilities is creation and teardown of the networks for the container. -For more information on the daemon check the zoneadmd(1M) man page. +One of the daemon's responsibilities is creation and teardown of the networks for the container. +For more information on the daemon see the [zoneadmd(1M)][zoneadmd.1m] man page. When such a container is started, a temporary VNIC(Virtual NIC) is automatically created for the container. 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(8) man page for the respective release of Solaris. +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. -Mapped to lower-link in the zonecfg(8) man page. +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. 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(8) man page. +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. When it is set to false, the allowedAddress will not be configured on container start. -Mapped to configure-allowed-address in the zonecfg(8) man page. +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. +* **`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(8) man page of the respective Solaris release. -Mapped to mac-address in the zonecfg(8) man page. +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. See the protection property in dladm(8) for supported values in respective release of Solaris. -Mapped to link-protection in the zonecfg(8) man page. +Mapped to `link-protection` in the [zonecfg(1M)][zonecfg.1m] man page. #### Example ```json @@ -113,3 +113,8 @@ Mapped to link-protection in the zonecfg(8) man page. } ] ``` + + +[priv-str-to-set.3c]: http://docs.oracle.com/cd/E53394_01/html/E54766/priv-str-to-set-3c.html +[zoneadmd.1m]: http://docs.oracle.com/cd/E53394_01/html/E54764/zoneadmd-1m.html +[zonecfg.1m_2]: http://docs.oracle.com/cd/E53394_01/html/E54764/zonecfg-1m.html diff --git a/config.md b/config.md index 947c9d3e2..92cad0ba8 100644 --- a/config.md +++ b/config.md @@ -15,7 +15,7 @@ For all platform-specific configuration values, the scope defined below in the [ ## 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][semver-v2.0.0] 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. @@ -48,25 +48,25 @@ For example, if a configuration is compliant with version 1.1 of this specificat **`mounts`** (array, OPTIONAL) specifies additional mounts beyond [`root`](#root-configuration). The runtime MUST mount entries in the listed order. -For Linux, the parameters are as documented in [the mount system call](http://man7.org/linux/man-pages/man2/mount.2.html). -For Solaris, the mount entry corresponds to the 'fs' resource in zonecfg(8). -For Windows, see links for details about [mountvol](http://ss64.com/nt/mountvol.html) and [SetVolumeMountPoint](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365561(v=vs.85).aspx). +For Linux, the parameters are as documented in [mount(2)][mount.2] system call man page. +For Solaris, the mount entry corresponds to the 'fs' resource in the [zonecfg(1M)][zonecfg.1m] man page. +For Windows, see [mountvol][mountvol] and [SetVolumeMountPoint][set-volume-mountpoint] for details. * **`destination`** (string, REQUIRED) Destination of mount point: path inside container. This value MUST be an absolute path. * Windows: one mount destination MUST NOT be nested within another mount (e.g., c:\\foo and c:\\foo\\bar). - * Solaris: corresponds to "dir" of the fs resource in zonecfg(8). + * Solaris: corresponds to "dir" of the fs resource in [zonecfg(1M)][zonecfg.1m]. * **`type`** (string, OPTIONAL) The filesystem type of the filesystem to be mounted. * Linux: valid *filesystemtype* supported by the kernel as listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660"). * Windows: the type of file system on the volume, e.g. "ntfs". - * Solaris: corresponds to "type" of the fs resource in zonecfg(8). + * Solaris: corresponds to "type" of the fs resource in [zonecfg(1M)][zonecfg.1m]. * **`source`** (string, OPTIONAL) 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). - * Solaris: corresponds to "special" of the fs resource in zonecfg(8). + * Solaris: corresponds to "special" of the fs resource in [zonecfg(1M)][zonecfg.1m]. * **`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]. - * Solaris: corresponds to "options" of the fs resource in zonecfg(8). + * Linux: supported options are listed in the [mount(8)][mount.8] man page. Note both [filesystem-independent][mount.8-filesystem-independent] and [filesystem-specific][mount.8-filesystem-specific] options are listed. + * Solaris: corresponds to "options" of the fs resource in [zonecfg(1M)][zonecfg.1m]. ### Example (Linux) @@ -132,7 +132,7 @@ For Windows, see links for details about [mountvol](http://ss64.com/nt/mountvol. * **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2001's `environ`][ieee-1003.1-2001-xbd-c8.1]. * **`args`** (array of strings, REQUIRED) with similar semantics to [IEEE Std 1003.1-2001 `execvp`'s *argv*][ieee-1003.1-2001-xsh-exec]. This specification extends the IEEE standard in that at least one entry is REQUIRED, and that entry is used with the same semantics as `execvp`'s *file*. -* **`capabilities`** (object, OPTIONAL) is an object containing arrays that specifies the sets of capabilities for the process(es) inside the container. Valid values are platform-specific. For example, valid values for Linux are defined in the [CAPABILITIES(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html) man page. +* **`capabilities`** (object, OPTIONAL) is an object containing arrays that specifies the sets of capabilities for the process(es) inside the container. Valid values are platform-specific. For example, valid values for Linux are defined in the [capabilities(7)][capabilities.7] man page. capabilities contains the following properties: * **`effective`** (array of strings, OPTIONAL) - the `effective` field is an array of effective capabilities that are kept for the process. * **`bounding`** (array of strings, OPTIONAL) - the `bounding` field is an array of bounding capabilities that are kept for the process. @@ -142,21 +142,21 @@ For Windows, see links for details about [mountvol](http://ss64.com/nt/mountvol. * **`rlimits`** (array of objects, OPTIONAL) allows setting resource limits for a process inside the container. Each entry has the following structure: - * **`type`** (string, REQUIRED) - the platform resource being limited, for example on Linux as defined in the [SETRLIMIT(2)](http://man7.org/linux/man-pages/man2/setrlimit.2.html) man page. + * **`type`** (string, REQUIRED) - the platform resource being limited, for example on Linux as defined in the [setrlimit(2)][setrlimit.2] man page. * **`soft`** (uint64, REQUIRED) - the value of the limit enforced for the corresponding resource. * **`hard`** (uint64, REQUIRED) - the ceiling for the soft limit that could be set by an unprivileged process. Only a privileged process (e.g. under Linux: one with the CAP_SYS_RESOURCE capability) can raise a hard limit. If `rlimits` contains duplicated entries with same `type`, the runtime MUST error out. * **`noNewPrivileges`** (bool, OPTIONAL) setting `noNewPrivileges` to true prevents the processes in the container from gaining additional privileges. - As an example, the ['no_new_privs' 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 on Linux. + 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. - For more information about AppArmor, see [AppArmor documentation](https://wiki.ubuntu.com/AppArmor) + 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. - For more information about SELinux, see [SELinux documentation](http://selinuxproject.org/page/Main_Page) + For more information about SELinux, see [SELinux documentation][selinux]. ### User @@ -166,9 +166,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][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. +* **`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. _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)_ @@ -283,8 +283,8 @@ For Windows based systems the user structure has the following fields: ## Hostname * **`hostname`** (string, OPTIONAL) specifies the container's hostname as seen by processes running inside the container. - On Linux, for example, this will change the hostname in the [container][container-namespace] [UTS namespace][uts-namespace]. - Depending on your [namespace configuration](config-linux.md#namespaces), the container UTS namespace may be the [runtime UTS namespace][runtime-namespace]. + On Linux, for example, this will change the hostname in the [container](glossary.md#container-namespace) [UTS namespace][uts-namespace.7]. + Depending on your [namespace configuration](config-linux.md#namespaces), the container UTS namespace may be the [runtime UTS namespace](glossary.md#runtime-namespace). ### Example @@ -817,13 +817,23 @@ Here is a full example `config.json` for reference. } ``` -[container-namespace]: glossary.md#container-namespace + +[apparmor]: https://wiki.ubuntu.com/AppArmor +[selinux]:http://selinuxproject.org/page/Main_Page +[no-new-privs]: https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt +[semver-v2.0.0]: http://semver.org/spec/v2.0.0.html [go-environment]: https://golang.org/doc/install/source#environment [ieee-1003.1-2001-xbd-c8.1]: http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html#tag_08_01 [ieee-1003.1-2001-xsh-exec]: http://pubs.opengroup.org/onlinepubs/009695399/functions/exec.html -[runtime-namespace]: glossary.md#runtime-namespace -[uts-namespace]: http://man7.org/linux/man-pages/man7/namespaces.7.html +[mountvol]: http://ss64.com/nt/mountvol.html +[set-volume-mountpoint]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365561(v=vs.85).aspx + +[capabilities.7]: http://man7.org/linux/man-pages/man7/capabilities.7.html +[mount.2]: http://man7.org/linux/man-pages/man2/mount.2.html +[mount.8]: http://man7.org/linux/man-pages/man8/mount.8.html [mount.8-filesystem-independent]: http://man7.org/linux/man-pages/man8/mount.8.html#FILESYSTEM-INDEPENDENT_MOUNT%20OPTIONS [mount.8-filesystem-specific]: http://man7.org/linux/man-pages/man8/mount.8.html#FILESYSTEM-SPECIFIC_MOUNT%20OPTIONS -[mount.8]: http://man7.org/linux/man-pages/man8/mount.8.html +[setrlimit.2]: http://man7.org/linux/man-pages/man2/setrlimit.2.html [stdin.3]: http://man7.org/linux/man-pages/man3/stdin.3.html +[uts-namespace.7]: http://man7.org/linux/man-pages/man7/namespaces.7.html +[zonecfg.1m]: http://docs.oracle.com/cd/E53394_01/html/E54764/zonecfg-1m.html diff --git a/glossary.md b/glossary.md index 273541149..09f80e421 100644 --- a/glossary.md +++ b/glossary.md @@ -33,6 +33,8 @@ 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. + [JSON]: https://tools.ietf.org/html/rfc7159 [UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf + [namespaces.7]: http://man7.org/linux/man-pages/man7/namespaces.7.html diff --git a/implementations.md b/implementations.md index c4076b629..1631073ba 100644 --- a/implementations.md +++ b/implementations.md @@ -5,15 +5,23 @@ If you know of any associated projects that are not listed here, please file a p ## Runtime (Container) -* [opencontainers/runc](https://github.com/opencontainers/runc) - Reference implementation of OCI runtime +* [opencontainers/runc][runc] - Reference implementation of OCI runtime ## Runtime (Virtual Machine) -* [hyperhq/runv](https://github.com/hyperhq/runv) - Hypervisor-based runtime for OCI -* [01org/cc-oci-runtime](https://github.com/01org/cc-oci-runtime) - Hypervisor-based OCI runtime for Intel® Architecture +* [hyperhq/runv][runv] - Hypervisor-based runtime for OCI +* [01org/cc-oci-runtime][cc-oci] - Hypervisor-based OCI runtime for Intel® Architecture ## Testing & Tools -* [kunalkushwaha/octool](https://github.com/kunalkushwaha/octool) - A config linter and validator. -* [huawei-openlab/oct](https://github.com/huawei-openlab/oct) - Open Container Testing framework for OCI configuration and runtime -* [opencontainers/runtime-tools](https://github.com/opencontainers/runtime-tools) - A config generator and runtime/bundle testing framework. +* [kunalkushwaha/octool][octool] - A config linter and validator. +* [huawei-openlab/oct][oct] - Open Container Testing framework for OCI configuration and runtime +* [opencontainers/runtime-tools][runtime-tools] - A config generator and runtime/bundle testing framework. + + +[runc]: https://github.com/opencontainers/runc +[runv]: https://github.com/hyperhq/runv +[cc-oci]: https://github.com/01org/cc-oci-runtime +[octool]: https://github.com/kunalkushwaha/octool +[oct]: https://github.com/huawei-openlab/oct +[runtime-tools]: https://github.com/opencontainers/runtime-tools diff --git a/project.md b/project.md index f58f8f53d..3f8a09b9d 100644 --- a/project.md +++ b/project.md @@ -6,5 +6,7 @@ * `git commit` version increment * `git tag` the prior commit (preferably signed tag) * `make docs` to produce PDF and HTML copies of the spec -* Make a release on [github.com/opencontainers/runtime-spec](https://github.com/opencontainers/runtime-spec/releases) for the version. Attach the produced docs. +* Make a [release][releases] for the version. Attach the produced docs. + +[releases]: https://github.com/opencontainers/runtime-spec/releases diff --git a/runtime-linux.md b/runtime-linux.md index d60418b85..a47b89693 100644 --- a/runtime-linux.md +++ b/runtime-linux.md @@ -3,7 +3,7 @@ ## File descriptors By default, only the `stdin`, `stdout` and `stderr` file descriptors are kept open for the application by the runtime. -The runtime MAY pass additional file descriptors to the application to support features such as [socket activation](http://0pointer.de/blog/projects/socket-activated-containers.html). +The runtime MAY pass additional file descriptors to the application to support features such as [socket activation][socket-activated-containers]. Some of the file descriptors MAY be redirected to `/dev/null` even though they are open. ## Dev symbolic links @@ -16,3 +16,6 @@ After the container has `/proc` mounted, the following standard symlinks MUST be | /proc/self/fd/0 | /dev/stdin | | /proc/self/fd/1 | /dev/stdout | | /proc/self/fd/2 | /dev/stderr | + + +[socket-activated-containers]: http://0pointer.de/blog/projects/socket-activated-containers.html diff --git a/spec.md b/spec.md index 38ae7a137..200f4e90e 100644 --- a/spec.md +++ b/spec.md @@ -1,6 +1,6 @@ # Open Container Initiative Runtime Specification -The [Open Container Initiative](http://www.opencontainers.org/) develops specifications for standards on Operating System process and application containers. +The [Open Container Initiative][oci] develops specifications for standards on Operating System process and application containers. # Abstract @@ -40,5 +40,7 @@ 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. + [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 diff --git a/style.md b/style.md index f2879e223..124b82a3a 100644 --- a/style.md +++ b/style.md @@ -21,6 +21,22 @@ The redundancy reduction from removing the namespacing prefix is not useful enou Because in many cases the Go default for the type is a no-op in the spec (sources [here][no-pointer-for-strings], [here][no-pointer-for-slices], and [here][no-pointer-for-boolean]). The exceptions are entries where we need to distinguish between “not set” and “set to the Go default for that type” ([source][pointer-when-updates-require-changes]), and this decision should be made on a per-setting case. +## Links + +Internal links should be [relative links][markdown-relative-links] when linking to content within the repository. +Internal links should be used inline. + +External links should be collected at the bottom of a markdown file and used as referenced links. +See 'Referenced Links' in this [markdown quick reference][markdown-quick-reference]. +The use of referenced links in the markdown body helps to keep files clean and organized. +This also facilitates updates of external link targets on a per-file basis. + +Referenced links should be kept in two alphabetically sorted sets, a general reference section followed by a man page section. +To keep Pandoc happy, duplicate naming of links within pages listed in the Makefile's DOC_FILES variable should be avoided by appending an '_N' to the link tagname, where 'N' is some number not currently in use. +The organization and style of an existing reference section should be maintained unless it violates these style guidelines. + +An exception to these rules is when a URL is needed contextually, for example when showing an explicit link to the reader. + ## Examples ### Anchoring @@ -86,6 +102,24 @@ Following is a fully populated example (not necessarily for copy/paste use) } ``` +### Links + +The following is an example of different types of links. +This is shown as a complete markdown file, where the referenced links are at the bottom. + +```markdown +The specification repository's [glossary](glossary.md) is where readers can find definitions of commonly used terms. + +Readers may click through to the [Open Containers namespace][open-containers] on [GitHub][github]. + +The URL for the Open Containers link above is: https://github.com/opencontainers + + +[github]: https://github.com +[open-containers]: https://github.com/opencontainers +``` + + [capabilities]: config-linux.md#capabilities [class-id]: config-linux.md#network [integer-over-hex]: https://github.com/opencontainers/runtime-spec/pull/267#r48360013 @@ -95,3 +129,5 @@ Following is a fully populated example (not necessarily for copy/paste use) [no-pointer-for-strings]: https://github.com/opencontainers/runtime-spec/pull/653#issue-200439192 [pointer-when-updates-require-changes]: https://github.com/opencontainers/runtime-spec/pull/317#r50932706 [markdown-headers]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#headings +[markdown-quick-reference]: https://en.support.wordpress.com/markdown-quick-reference +[markdown-relative-links]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#relative-links