pax_global_header00006660000000000000000000000064125704112740014515gustar00rootroot0000000000000052 comment=e9cb5644fa03cc66f46657266b724f74ee86b04e specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/000077500000000000000000000000001257041127400176005ustar00rootroot00000000000000specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/.travis.yml000066400000000000000000000003431257041127400217110ustar00rootroot00000000000000language: go go: - 1.4.2 - 1.3.3 sudo: false before_install: - go get golang.org/x/tools/cmd/vet - go get github.com/golang/lint/golint install: true script: - go vet -x ./... - $HOME/gopath/bin/golint ./... specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/LICENSE000066400000000000000000000250171257041127400206120ustar00rootroot00000000000000 Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS Copyright 2015 The Linux Foundation. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/README.md000066400000000000000000000216521257041127400210650ustar00rootroot00000000000000# Open Container Specifications This project is where the [Open Container Initiative](http://www.opencontainers.org/) Specifications are written. This is a work in progress. We should have a first draft by end of July 2015. Table of Contents - [Filesystem Bundle](bundle.md) - [Container Configuration](config.md) - [Linux Specific Configuration](config-linux.md) - [Runtime and Lifecycle](runtime.md) - [Implementations](implementations.md) ## Use Cases To provide context for users the following section gives example use cases for each part of the spec. ### Filesystem Bundle & Configuration - A user can create a root filesystem and configuration, with low-level OS and host specific details, and launch it as a container under an Open Container runtime. # The 5 principles of Standard Containers Define a unit of software delivery called a Standard Container. The goal of a Standard Container is to encapsulate a software component and all its dependencies in a format that is self-describing and portable, so that any compliant runtime can run it without extra dependencies, regardless of the underlying machine and the contents of the container. The specification for Standard Containers is straightforward. It mostly defines 1) a file format, 2) a set of standard operations, and 3) an execution environment. A great analogy for this is the shipping container. Just like how Standard Containers are a fundamental unit of software delivery, shipping containers are a fundamental unit of physical delivery. ## 1. Standard operations Just like shipping containers, Standard Containers define a set of STANDARD OPERATIONS. Shipping containers can be lifted, stacked, locked, loaded, unloaded and labelled. Similarly, Standard Containers can be created, started, and stopped using standard container tools (what this spec is about); copied and snapshotted using standard filesystem tools; and downloaded and uploaded using standard network tools. ## 2. Content-agnostic Just like shipping containers, Standard Containers are CONTENT-AGNOSTIC: all standard operations have the same effect regardless of the contents. A shipping container will be stacked in exactly the same way whether it contains Vietnamese powder coffee or spare Maserati parts. Similarly, Standard Containers are started or uploaded in the same way whether they contain a postgres database, a php application with its dependencies and application server, or Java build artifacts. ## 3. Infrastructure-agnostic Both types of containers are INFRASTRUCTURE-AGNOSTIC: they can be transported to thousands of facilities around the world, and manipulated by a wide variety of equipment. A shipping container can be packed in a factory in Ukraine, transported by truck to the nearest routing center, stacked onto a train, loaded into a German boat by an Australian-built crane, stored in a warehouse at a US facility, etc. Similarly, a standard container can be bundled on my laptop, uploaded to S3, downloaded, run and snapshotted by a build server at Equinix in Virginia, uploaded to 10 staging servers in a home-made Openstack cluster, then sent to 30 production instances across 3 EC2 regions. ## 4. Designed for automation Because they offer the same standard operations regardless of content and infrastructure, Standard Containers, just like their physical counterparts, are extremely well-suited for automation. In fact, you could say automation is their secret weapon. Many things that once required time-consuming and error-prone human effort can now be programmed. Before shipping containers, a bag of powder coffee was hauled, dragged, dropped, rolled and stacked by 10 different people in 10 different locations by the time it reached its destination. 1 out of 50 disappeared. 1 out of 20 was damaged. The process was slow, inefficient and cost a fortune - and was entirely different depending on the facility and the type of goods. Similarly, before Standard Containers, by the time a software component ran in production, it had been individually built, configured, bundled, documented, patched, vendored, templated, tweaked and instrumented by 10 different people on 10 different computers. Builds failed, libraries conflicted, mirrors crashed, post-it notes were lost, logs were misplaced, cluster updates were half-broken. The process was slow, inefficient and cost a fortune - and was entirely different depending on the language and infrastructure provider. ## 5. Industrial-grade delivery There are 17 million shipping containers in existence, packed with every physical good imaginable. Every single one of them can be loaded onto the same boats, by the same cranes, in the same facilities, and sent anywhere in the World with incredible efficiency. It is embarrassing to think that a 30 ton shipment of coffee can safely travel half-way across the World in *less time* than it takes a software team to deliver its code from one datacenter to another sitting 10 miles away. With Standard Containers we can put an end to that embarrassment, by making INDUSTRIAL-GRADE DELIVERY of software a reality. # Contributing Development happens on GitHub for the spec. Issues are used for bugs and actionable items and longer discussions can happen on the [mailing list](#mailing-list). The specification and code is licensed under the Apache 2.0 license found in the `LICENSE` file of this repository. ## Discuss your design The project welcomes submissions, but please let everyone know what you are working on. Before undertaking a nontrivial change to this specification, send mail to the [mailing list](#mailing-list) to discuss what you plan to do. This gives everyone a chance to validate the design, helps prevent duplication of effort, and ensures that the idea fits. It also guarantees that the design is sound before code is written; a GitHub pull-request is not the place for high-level discussions. Typos and grammatical errors can go straight to a pull-request. When in doubt, start on the [mailing-list](#mailing-list). ## Weekly Call The contributors and maintainers of the project have a weekly meeting Wednesdays at 10:00 AM PST. Everyone is welcome to participate in the [BlueJeans call][BlueJeans]. 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 for the call will be posted to the [mailing list](#mailing-list) for those who are unable to join the call. ## Mailing List You can subscribe and join the mailing list on [Google Groups](https://groups.google.com/a/opencontainers.org/forum/#!forum/dev). ## IRC OCI discussion happens on #opencontainers on Freenode. ## Markdown style To keep consistency throughout the Markdown files in the Open Container spec all files should be formatted one sentence per line. This fixes two things: it makes diffing easier with git and it resolves fights about line wrapping length. For example, this paragraph will span three lines in the Markdown source. ### 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/)): ``` Developer Certificate of Origin Version 1.1 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 660 York Street, Suite 102, San Francisco, CA 94110 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. ``` then you just add a line to every git commit message: Signed-off-by: Joe Smith using your real name (sorry, no pseudonyms or anonymous contributions.) You can add the sign off when creating the git commit via `git commit -s`. [BlueJeans]: https://bluejeans.com/1771332256/ specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/bundle.md000066400000000000000000000036561257041127400214050ustar00rootroot00000000000000# Bundle Container Format This section defines a format for encoding a container as a *bundle* - a directory 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*. The format does not define distribution. In other words, it only specifies how a container must be stored on a local filesystem, for consumption by a runtime. It does not specify how to transfer a container between computers, how to discover containers, or assign names or versions to them. Any distribution method capable of preserving the original layout of a container, as specified here, is considered compliant. A standard container bundle is made of the following 3 parts: - A top-level directory holding everything else - One or more content directories - A configuration file # Directory layout A Standard Container bundle is a directory containing all the content needed to load and run a container. This includes two configuration files `config.json` and `runtime.json`, and a rootfs directory. The `config.json` file contains settings that are host independent and application specific such as security permissions, environment variables and arguments. The `runtime.json` file contains settings that are host specific such as memory limits, local device access and mount points. The goal is that the bundle can be moved as a unit to another machine and run the same application if `runtime.json` is removed or reconfigured. The syntax and semantics for `config.json` are described in [this specification](config.md). A single `rootfs` directory MUST be in the same directory as the `config.json`. The names of the directories may be arbitrary, but users should consider using conventional names as in the example below. ``` config.json runtime.json rootfs/ ``` specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/config-linux.md000066400000000000000000000034441257041127400225310ustar00rootroot00000000000000# Linux-specific configuration The Linux container specification uses various kernel features like namespaces, cgroups, capabilities, LSM, and file system jails to fulfill the spec. Additional information is needed for Linux over the [default spec configuration](config.md) in order to configure these various kernel features. ## Capabilities Capabilities is an array that specifies Linux capabilities that can be provided to the process inside the container. Valid values are the string after `CAP_` for capabilities defined in [the man page](http://man7.org/linux/man-pages/man7/capabilities.7.html) ```json "capabilities": [ "AUDIT_WRITE", "KILL", "NET_BIND_SERVICE" ] ``` ## Rootfs Mount Propagation rootfsPropagation 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. ```json "rootfsPropagation": "slave", ``` ## User namespace mappings ```json "uidMappings": [ { "hostID": 1000, "containerID": 0, "size": 10 } ], "gidMappings": [ { "hostID": 1000, "containerID": 0, "size": 10 } ] ``` uid/gid mappings describe the user namespace mappings from the host to the container. The mappings represent how the bundle `rootfs` expects the user namespace to be setup and the runtime SHOULD NOT modify the permissions on the rootfs to realize the mapping. *hostID* is the starting uid/gid on the host to be mapped to *containerID* which is the starting uid/gid in the container and *size* refers to the number of ids to be mapped. There is a limit of 5 mappings which is the Linux kernel hard limit. specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/config.go000066400000000000000000000043421257041127400213770ustar00rootroot00000000000000package specs // Spec is the base configuration for the container. It specifies platform // independent configuration. type Spec struct { // Version is the version of the specification that is supported. Version string `json:"version"` // Platform is the host information for OS and Arch. Platform Platform `json:"platform"` // Process is the container's main process. Process Process `json:"process"` // Root is the root information for the container's filesystem. Root Root `json:"root"` // Hostname is the container's host name. Hostname string `json:"hostname"` // Mounts profile configuration for adding mounts to the container's filesystem. MountPoints []MountPoint `json:"mounts"` } // Process contains information to start a specific application inside the container. type Process struct { // Terminal creates an interactive terminal for the container. Terminal bool `json:"terminal"` // User specifies user information for the process. User User `json:"user"` // Args specifies the binary and arguments for the application to execute. Args []string `json:"args"` // Env populates the process environment for the process. Env []string `json:"env"` // Cwd is the current working directory for the process and must be // relative to the container's root. Cwd string `json:"cwd"` } // Root contains information about the container's root filesystem on the host. type Root struct { // Path is the absolute path to the container's root filesystem. Path string `json:"path"` // Readonly makes the root filesystem for the container readonly before the process is executed. Readonly bool `json:"readonly"` } // Platform specifies OS and arch information for the host system that the container // is created for. type Platform struct { // OS is the operating system. OS string `json:"os"` // Arch is the architecture Arch string `json:"arch"` } // MountPoint describes a directory that may be fullfilled by a mount in the runtime.json. type MountPoint struct { // Name is a unique descriptive identifier for this mount point. Name string `json:"name"` // Path specifies the path of the mount. The path and child directories MUST exist, a runtime MUST NOT create directories automatically to a mount point. Path string `json:"path"` } specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/config.md000066400000000000000000000102751257041127400213740ustar00rootroot00000000000000# Configuration file The container's top-level directory MUST contain a configuration file called `config.json`. For now the canonical schema is defined in [spec.go](spec.go) and [spec_linux.go](spec_linux.go), but this will be moved to a formal JSON schema over time. The configuration file contains metadata necessary to implement standard operations against the container. This includes the process to run, environment variables to inject, sandboxing features to use, etc. Below is a detailed description of each field defined in the configuration format. ## Manifest version * **version** (string, required) must be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the OCF specification with which the container bundle complies. The Open Container spec follows semantic versioning and retains forward and backward compatibility within major versions. For example, if an implementation is compliant with version 1.0.1 of the spec, it is compatible with the complete 1.x series. *Example* ```json "version": "0.1.0" ``` ## Root Configuration Each container has exactly one *root filesystem*, specified in the *root* object: * **path** (string, required) Specifies the path to the root filesystem for the container, relative to the path where the manifest is. A directory MUST exist at the relative path declared by the field. * **readonly** (bool, optional) If true then the root filesystem MUST be read-only inside the container. Defaults to false. *Example* ```json "root": { "path": "rootfs", "readonly": true } ``` ## Process configuration * **terminal** (bool, optional) specifies whether you want a terminal attached to that process. Defaults to false. * **cwd** (string, optional) is the working directory that will be set for the executable. * **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** (string, 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. The user for the process is a platform-specific structure that allows specific control over which user the process runs as. For Linux-based systems the user structure has the following fields: * **uid** (int, required) specifies the user id. * **gid** (int, required) specifies the group id. * **additionalGids** (array of ints, optional) specifies additional group ids to be added to the process. *Example (Linux)* ```json "process": { "terminal": true, "user": { "uid": 1, "gid": 1, "additionalGids": [5, 6] }, "env": [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", "TERM=xterm" ], "cwd": "/root", "args": [ "sh" ] } ``` ## Hostname * **hostname** (string, optional) as it is accessible to processes running inside. *Example* ```json "hostname": "mrsdalloway" ``` ## Platform-specific configuration * **os** (string, required) specifies the operating system family this image must run on. Values for os must be in the list specified by the Go Language document for [`$GOOS`](https://golang.org/doc/install/source#environment). * **arch** (string, required) specifies the instruction set for which the binaries in the image have been compiled. Values for arch must be in the list specified by the Go Language document for [`$GOARCH`](https://golang.org/doc/install/source#environment). ```json "platform": { "os": "linux", "arch": "amd64" } ``` Interpretation of the platform section of the JSON file is used to find which platform-specific sections may be available in the document. For example, if `os` is set to `linux`, then a JSON object conforming to the [Linux-specific schema](config-linux.md) SHOULD be found at the key `linux` in the `config.json`. specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/config_linux.go000066400000000000000000000016251257041127400226170ustar00rootroot00000000000000// +build linux package specs // LinuxSpec is the full specification for linux containers. type LinuxSpec struct { Spec // Linux is platform specific configuration for linux based containers. Linux Linux `json:"linux"` } // Linux contains platform specific configuration for linux based containers. type Linux struct { // Capabilities are linux capabilities that are kept for the container. Capabilities []string `json:"capabilities"` // RootfsPropagation is the rootfs mount propagation mode for the container. RootfsPropagation string `json:"rootfsPropagation"` } // User specifies linux specific user and group information for the container's // main process. type User struct { // Uid is the user id. Uid int32 `json:"uid"` // Gid is the group id. Gid int32 `json:"gid"` // AdditionalGids are additional group ids set for the container's process. AdditionalGids []int32 `json:"additionalGids"` } specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/implementations.md000066400000000000000000000012551257041127400233350ustar00rootroot00000000000000# Implementations The following sections link to associated projects, some of which are maintained by the OCI and some of which are maintained by external organizations. If you know of any associated projects that are not listed here, please file a pull request adding a link to that project. ## Runtime (Container) * [opencontainers/runc](https://github.com/opencontainers/runc) - Reference implementation of OCI runtime ## Runtime (Virtual Machine) * [hyperhq/runv](https://github.com/hyperhq/runv) - Hypervisor-based runtime for OCI ## Testing * [huawei-openlab/oct](https://github.com/huawei-openlab/oct) - Open Container Testing framework for OCI configuration and runtime specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/runtime-config-linux.md000066400000000000000000000141221257041127400242050ustar00rootroot00000000000000## 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). Namespaces are specified in the spec as an array of entries. Each entry has a type field with possible values described below and an optional path element. If a path is specified, that particular file is used to join that type of namespace. ```json "namespaces": [ { "type": "pid", "path": "/proc/1234/ns/pid" }, { "type": "net", "path": "/var/run/netns/neta" }, { "type": "mnt", }, { "type": "ipc", }, { "type": "uts", }, { "type": "user", }, ] ``` #### Namespace types * **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. * **mnt** the container will have an isolated mount table. * **ipc** processes inside the container will only be able to communicate to other processes inside the same container via system level IPC. * **uts** the container will be able to have its own hostname and domain name. * **user** the container will be able to remap user and group IDs from the host to local users and groups within the container. ### Access to devices Devices is an array specifying the list of devices to be created in the container. Next parameters can be specified: * type - type of device: 'c', 'b', 'u' or 'p'. More info in `man mknod` * path - full path to device inside container * major, minor - major, minor numbers for device. More info in `man mknod`. There is special value: `-1`, which means `*` for `device` cgroup setup. * permissions - cgroup permissions for device. A composition of 'r' (read), 'w' (write), and 'm' (mknod). * fileMode - file mode for device file * uid - uid of device owner * gid - gid of device owner ```json "devices": [ { "path": "/dev/random", "type": "c", "major": 1, "minor": 8, "permissions": "rwm", "fileMode": 0666, "uid": 0, "gid": 0 }, { "path": "/dev/urandom", "type": "c", "major": 1, "minor": 9, "permissions": "rwm", "fileMode": 0666, "uid": 0, "gid": 0 }, { "path": "/dev/null", "type": "c", "major": 1, "minor": 3, "permissions": "rwm", "fileMode": 0666, "uid": 0, "gid": 0 }, { "path": "/dev/zero", "type": "c", "major": 1, "minor": 5, "permissions": "rwm", "fileMode": 0666, "uid": 0, "gid": 0 }, { "path": "/dev/tty", "type": "c", "major": 5, "minor": 0, "permissions": "rwm", "fileMode": 0666, "uid": 0, "gid": 0 }, { "path": "/dev/full", "type": "c", "major": 1, "minor": 7, "permissions": "rwm", "fileMode": 0666, "uid": 0, "gid": 0 } ] ``` ## Control groups Also known as cgroups, they are used to restrict resource usage for a container and handle device access. cgroups provide controls to restrict cpu, memory, IO, and network for the container. For more information, see the [kernel cgroups documentation](https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt). ## Sysctl sysctl 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) ```json "sysctl": { "net.ipv4.ip_forward": "1", "net.core.somaxconn": "256" } ``` ## Rlimits ```json "rlimits": [ { "type": "RLIMIT_NPROC", "soft": 1024, "hard": 102400 } ] ``` rlimits allow setting resource limits. The type is from the values defined in [the man page](http://man7.org/linux/man-pages/man2/setrlimit.2.html). 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. ## SELinux process label 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) ```json "selinuxProcessLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675" ``` ## Apparmor profile 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) ```json "apparmorProfile": "acme_secure_profile" ``` ## seccomp 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 and operators are strings that match the definitions in seccomp.h from [libseccomp](https://github.com/seccomp/libseccomp) and are translated to corresponding values. ```json "seccomp": { "defaultAction": "SCMP_ACT_ALLOW", "syscalls": [ { "name": "getcwd", "action": "SCMP_ACT_ERRNO" } ] } ``` specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/runtime-config.md000066400000000000000000000040131257041127400230460ustar00rootroot00000000000000## Mount Configuration Additional filesystems can be declared as "mounts", specified in the *mounts* array. The parameters are similar to the ones in Linux mount system call. [http://linux.die.net/man/2/mount](http://linux.die.net/man/2/mount) * **type** (string, required) 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. Windows, the volume name that is the target of the mount point. \\?\Volume\{GUID}\ (on Windows source is called target) * **destination** (string, required) where the source filesystem is mounted relative to the container rootfs. * **options** (list of strings, optional) in the fstab format [https://wiki.archlinux.org/index.php/Fstab](https://wiki.archlinux.org/index.php/Fstab). *Example (Linux)* ```json "mounts": [ { "type": "proc", "source": "proc", "destination": "/proc", "options": [] }, { "type": "tmpfs", "source": "tmpfs", "destination": "/dev", "options": ["nosuid","strictatime","mode=755","size=65536k"] }, { "type": "devpts", "source": "devpts", "destination": "/dev/pts", "options": ["nosuid","noexec","newinstance","ptmxmode=0666","mode=0620","gid=5"] }, { "type": "bind", "source": "/volumes/testing", "destination": "/data", "options": ["rbind","rw"] } ] ``` *Example (Windows)* ```json "mounts": [ { "type": "ntfs", "source": "\\\\?\\Volume\\{2eca078d-5cbc-43d3-aff8-7e8511f60d0e}\\", "destination": "C:\\Users\\crosbymichael\\My Fancy Mount Point\\", "options": [] } ] ``` 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) in Windows. specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/runtime-linux.md000066400000000000000000000006361257041127400227470ustar00rootroot00000000000000## 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). Some of the file descriptors may be redirected to `/dev/null` even though they are open. specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/runtime.md000066400000000000000000000035741257041127400216160ustar00rootroot00000000000000# Runtime and Lifecycle ## Lifecycle ### Create Creates the container: file system, namespaces, cgroups, capabilities. ### Start (process) Runs a process in a container. Can be invoked several times. ### Stop (process) Not sure we need that from runc cli. Process is killed from the outside. This event needs to be captured by runc to run onstop event handlers. ## Hooks Hooks allow one to run code before/after various lifecycle events of the container. The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work. Hook paths are absolute and are executed from the host's filesystem. ### Pre-start The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed. They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container. In Linux, for e.g., the network namespace could be configured in this hook. If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down. ### Post-stop The post-stop hooks are called after the container process is stopped. Cleanup or debugging could be performed in such a hook. If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed. *Example* ```json "hooks" : { "prestart": [ { "path": "/usr/bin/fix-mounts", "args": ["arg1", "arg2"], "env": [ "key1=value1"] }, { "path": "/usr/bin/setup-network" } ], "poststop": [ { "path": "/usr/sbin/cleanup.sh", "args": ["-f"] } ] } ``` `path` is required for a hook. `args` and `env` are optional. specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/runtime_config.go000066400000000000000000000024301257041127400231360ustar00rootroot00000000000000package specs type RuntimeSpec struct { // Mounts profile configuration for adding mounts to the container's filesystem. Mounts []Mount `json:"mounts"` // Hooks are the commands run at various lifecycle events of the container. Hooks Hooks `json:"hooks"` } // Hook specifies a command that is run at a particular event in the lifecycle of a container. type Hook struct { Path string `json:"path"` Args []string `json:"args"` Env []string `json:"env"` } type Hooks struct { // Prestart is a list of hooks to be run before the container process is executed. // On Linux, they are run after the container namespaces are created. Prestart []Hook `json:"prestart"` // Poststop is a list of hooks to be run after the container process exits. Poststop []Hook `json:"poststop"` } // Mount specifies a mount for a container. type Mount struct { // Type specifies the mount kind. Type string `json:"type"` // Source specifies the source path of the mount. In the case of bind mounts on // linux based systems this would be the file on the host. Source string `json:"source"` // Destination is the path where the mount will be placed relative to the container's root. Destination string `json:"destination"` // Options are fstab style mount options. Options []string `json:"options"` } specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/runtime_config_linux.go000066400000000000000000000155701257041127400243660ustar00rootroot00000000000000package specs import "os" // LinuxRuntimeSpec is the full specification for linux containers. type LinuxRuntimeSpec struct { RuntimeSpec // Linux is platform specific configuration for linux based containers. LinuxRuntime Linux `json:"linux"` } type LinuxRuntime struct { // UidMapping specifies user mappings for supporting user namespaces on linux. UidMappings []IDMapping `json:"uidMappings"` // UidMapping specifies group mappings for supporting user namespaces on linux. GidMappings []IDMapping `json:"gidMappings"` // Rlimits specifies rlimit options to apply to the container's process. Rlimits []Rlimit `json:"rlimits"` // Sysctl are a set of key value pairs that are set for the container on start Sysctl map[string]string `json:"sysctl"` // Resources contain cgroup information for handling resource constraints // for the container Resources Resources `json:"resources"` // Namespaces contains the namespaces that are created and/or joined by the container Namespaces []Namespace `json:"namespaces"` // Devices are a list of device nodes that are created and enabled for the container Devices []Device `json:"devices"` // ApparmorProfile specified the apparmor profile for the container. ApparmorProfile string `json:"apparmorProfile"` // SelinuxProcessLabel specifies the selinux context that the container process is run as. SelinuxProcessLabel string `json:"selinuxProcessLabel"` // Seccomp specifies the seccomp security settings for the container. Seccomp Seccomp `json:"seccomp"` // RootfsPropagation is the rootfs mount propagation mode for the container RootfsPropagation string `json:"rootfsPropagation"` } // Namespace is the configuration for a linux namespace. type Namespace struct { // Type is the type of Linux namespace Type string `json:"type"` // Path is a path to an existing namespace persisted on disk that can be joined // and is of the same type Path string `json:"path"` } // IDMapping specifies UID/GID mappings type IDMapping struct { // HostID is the UID/GID of the host user or group HostID int32 `json:"hostID"` // ContainerID is the UID/GID of the container's user or group ContainerID int32 `json:"containerID"` // Size is the length of the range of IDs mapped between the two namespaces Size int32 `json:"size"` } // Rlimit type and restrictions type Rlimit struct { // Type of the rlimit to set Type int `json:"type"` // Hard is the hard limit for the specified type Hard uint64 `json:"hard"` // Soft is the soft limit for the specified type Soft uint64 `json:"soft"` } // HugepageLimit structure corresponds to limiting kernel hugepages type HugepageLimit struct { Pagesize string `json:"pageSize"` Limit int `json:"limit"` } // InterfacePriority for network interfaces type InterfacePriority struct { // Name is the name of the network interface Name string `json:"name"` // Priority for the interface Priority int64 `json:"priority"` } // BlockIO for Linux cgroup 'blockio' resource management type BlockIO struct { // Specifies per cgroup weight, range is from 10 to 1000 Weight int64 `json:"blkioWeight"` // Weight per cgroup per device, can override BlkioWeight WeightDevice string `json:"blkioWeightDevice"` // IO read rate limit per cgroup per device, bytes per second ThrottleReadBpsDevice string `json:"blkioThrottleReadBpsDevice"` // IO write rate limit per cgroup per divice, bytes per second ThrottleWriteBpsDevice string `json:"blkioThrottleWriteBpsDevice"` // IO read rate limit per cgroup per device, IO per second ThrottleReadIOpsDevice string `json:"blkioThrottleReadIopsDevice"` // IO write rate limit per cgroup per device, IO per second ThrottleWriteIOpsDevice string `json:"blkioThrottleWriteIopsDevice"` } // Memory for Linux cgroup 'memory' resource management type Memory struct { // Memory limit (in bytes) Limit int64 `json:"limit"` // Memory reservation or soft_limit (in bytes) Reservation int64 `json:"reservation"` // Total memory usage (memory + swap); set `-1' to disable swap Swap int64 `json:"swap"` // Kernel memory limit (in bytes) Kernel int64 `json:"kernel"` // How aggressive the kernel will swap memory pages. Range from 0 to 100. Set -1 to use system default Swappiness int64 `json:"swappiness"` } // CPU for Linux cgroup 'cpu' resource management type CPU struct { // CPU shares (relative weight vs. other cgroups with cpu shares) Shares int64 `json:"shares"` // CPU hardcap limit (in usecs). Allowed cpu time in a given period Quota int64 `json:"quota"` // CPU period to be used for hardcapping (in usecs). 0 to use system default Period int64 `json:"period"` // How many time CPU will use in realtime scheduling (in usecs) RealtimeRuntime int64 `json:"realtimeRuntime"` // CPU period to be used for realtime scheduling (in usecs) RealtimePeriod int64 `json:"realtimePeriod"` // CPU to use within the cpuset Cpus string `json:"cpus"` // MEM to use within the cpuset Mems string `json:"mems"` } // Network identification and priority configuration type Network struct { // Set class identifier for container's network packets ClassID string `json:"classId"` // Set priority of network traffic for container Priorities []InterfacePriority `json:"priorities"` } // Resources has container runtime resource constraints type Resources struct { // DisableOOMKiller disables the OOM killer for out of memory conditions DisableOOMKiller bool `json:"disableOOMKiller"` // Memory restriction configuration Memory Memory `json:"memory"` // CPU resource restriction configuration CPU CPU `json:"cpu"` // BlockIO restriction configuration BlockIO BlockIO `json:"blockIO"` // Hugetlb limit (in bytes) HugepageLimits []HugepageLimit `json:"hugepageLimits"` // Network restriction configuration Network Network `json:"network"` } type Device struct { // Path to the device. Path string `json:"path"` // Device type, block, char, etc. Type rune `json:"type"` // Major is the device's major number. Major int64 `json:"major"` // Minor is the device's minor number. Minor int64 `json:"minor"` // Cgroup permissions format, rwm. Permissions string `json:"permissions"` // FileMode permission bits for the device. FileMode os.FileMode `json:"fileMode"` // UID of the device. UID uint32 `json:"uid"` // Gid of the device. GID uint32 `json:"gid"` } // Seccomp represents syscall restrictions type Seccomp struct { DefaultAction Action `json:"defaultAction"` Syscalls []*Syscall `json:"syscalls"` } // Action taken upon Seccomp rule match type Action string // Operator used to match syscall arguments in Seccomp type Operator string // Arg used for matching specific syscall arguments in Seccomp type Arg struct { Index uint `json:"index"` Value uint64 `json:"value"` ValueTwo uint64 `json:"valueTwo"` Op Operator `json:"op"` } // Syscall is used to match a syscall in Seccomp type Syscall struct { Name string `json:"name"` Action Action `json:"action"` Args []*Arg `json:"args"` } specs-e9cb5644fa03cc66f46657266b724f74ee86b04e/version.go000066400000000000000000000001631257041127400216140ustar00rootroot00000000000000package specs // Version is the specification version that the package types support. const Version = "pre-draft"