pax_global_header00006660000000000000000000000064131756161150014520gustar00rootroot0000000000000052 comment=4e3b9264a330d094b0386c3703c5f379119711e8 runtime-spec-1.0.1/000077500000000000000000000000001317561611500141325ustar00rootroot00000000000000runtime-spec-1.0.1/.gitattributes000066400000000000000000000001061317561611500170220ustar00rootroot00000000000000# https://tools.ietf.org/html/rfc5545#section-3.1 *.ics text eol=crlf runtime-spec-1.0.1/.gitignore000066400000000000000000000000421317561611500161160ustar00rootroot00000000000000output schema/validate version.md runtime-spec-1.0.1/.mailmap000066400000000000000000000022051317561611500155520ustar00rootroot00000000000000Aleksa Sarai Alexander Morozov Amit Saha Antonio Murdaca Brandon Philips Brandon Philips ChengTiesheng Daniel, Dao Quang Minh Doug Davis James O. D. Hunt John Howard LinZhinan(Zen Lin) Mrunal Patel Mrunal Patel Mrunal Patel Vincent Batts Vincent Batts Vishnu Kannan Vishnu Kannan Zefan Li 梁辰晔 (Liang Chenye) runtime-spec-1.0.1/.pullapprove.yml000066400000000000000000000007011317561611500173020ustar00rootroot00000000000000version: 2 requirements: signed_off_by: required: true group_defaults: required: 2 approve_by_comment: enabled: true approve_regex: ^LGTM reject_regex: ^Rejected reset_on_push: enabled: true author_approval: ignored: true always_pending: title_regex: ^WIP explanation: 'Work in progress...' conditions: branches: - master groups: runtime-spec: teams: - runtime-spec-maintainers runtime-spec-1.0.1/.tool/000077500000000000000000000000001317561611500151655ustar00rootroot00000000000000runtime-spec-1.0.1/.tool/version-doc.go000066400000000000000000000006411317561611500177450ustar00rootroot00000000000000// +build ignore package main import ( "fmt" "html/template" "os" "github.com/opencontainers/runtime-spec/specs-go" ) var markdownTemplateString = ` **Specification Version:** *{{.}}* ` var markdownTemplate = template.Must(template.New("markdown").Parse(markdownTemplateString)) func main() { if err := markdownTemplate.Execute(os.Stdout, specs.Version); err != nil { fmt.Fprintln(os.Stderr, err) } } runtime-spec-1.0.1/.travis.yml000066400000000000000000000006711317561611500162470ustar00rootroot00000000000000language: go go: - 1.7 - 1.6.3 - 1.5.4 sudo: required services: - docker before_install: - make install.tools - docker pull vbatts/pandoc install: true script: - env | grep TRAVIS_ - make .govet - make .golint - echo "${TRAVIS_COMMIT_RANGE} -> ${TRAVIS_COMMIT_RANGE/.../..} (travis-ci/travis-ci#4596)" - TRAVIS_COMMIT_RANGE="${TRAVIS_COMMIT_RANGE/.../..}" make .gitvalidation - make docs - make -C schema test runtime-spec-1.0.1/ChangeLog000066400000000000000000000677051317561611500157230ustar00rootroot00000000000000OpenContainers Specifications Changes with v1.0.1: Minor fixes and documentation: * spec: Expand "OCI" in spec-title reference and add "Initiative" (#900) * config: Simplify title to "Configuration" (#901) * config: Fix "procfs_2" -> "proc_2" link label (#906) * config: Fix IEEE Std 1003.1-2008 exec link markup (#913) * config: Add a trailing period to the "cannot be mapped" rlimits line (#915) * config-linux: RFC 2119 MUST for absolute linux.namespaces[].path (#925). This is technically a breaking change, because a config with a relative namespace path would have been compliant before, but will be non compliant with this change. However, the previous "an absolute path to namespace file" wording was clear enough that config authors are unlikely to be relying on relative namespace paths in configs. * config-linux: More specific documentation for weightDevice and throttle* (#825) * config-linux: Modify procfs to proc (#905) * config-linux: Fix "psuedo" -> "pseudo" typo (#921) * config-windows: Make maximum a uint16 (was a uint) (#891) * runtime: Change "process in the container" -> "container process" (#907) * schema/config-schema: Use ArrayOfStrings in capabilities properties. (#886) * schema/config-linux: s/throttleWriteIopsDevice/throttleWriteIOPSDevice/ (#899) * schema/config-linux: add intelRdt field (#889) * schema/config-solaris: Replaced refs with some fields (cappedCPU.ncpus, etc.) (#892) Changes with v1.0.0: Breaking changes: * config: Shift disableOOMKiller from linux.resources to linux.resources.memory (#896) Decreased restrictions: * runtime: Make the state JSON's pid optional on non-Linux platforms (#897) Minor fixes and documentation: * schema/defs-linux: Require Syscall.action (#885) * specs-go/config: Fix 'omiempty' -> 'omitempty' typo for LinuxSeccompArg.ValueTwo (#884) * ROAMAP: remove the pre-v1.0.0 roadmap (#890) Changes with v1.0.0-rc6: Breaking changes: * config: Shift oomScoreAdj to process and add RFC 2119 requirements for the runtime (#781, #789, #836) * config: Forbid 'root' on Hyper-V (#820, #838). * config: process.capabilities and process.noNewPrivileges are Linux-only again (#880). This partially reverses #673, which had landed in v1.0.0-rc5. * config: Remove process.rlimits from Windows (#880). It is now POSIX-only, while in v1.0.0-rc5 it was cross-platform (because of #673). Before #673 (in v1.0.0-rc4 and earlier), it was Linux-only. * config-linux: Drop redundant 'blkio' prefix from blockIO properties (#860) * config-linux: Make memory limits int64 instead of uint64 (#876). This partially reverses #704, which had landed in v1.0.0-rc5. * config-windows: Change CPU 'percent' to 'maximum' (#777) * config-windows: Remove memory 'reservation' (#788) * config-windows: Remove 'resources.network' and add 'network' (#801) Additions: * config: Windows runtimes MUST support the 'ro' mount option (#868) * config-linux: Add Intel RDT/CAT Linux support (#630, #787) * config-linux: Add Markdown specification for syscalls (#706) * config-linux: Add 'unbindable' rootfsPropagation value (#770, #775) * config-windows: Add 'credentialSpec' (#814, #859) * config-windows: Add 'servicing' (#815) * config-windows: Add 'ignoreFlushesDuringBoot' (#816, #859) * config-windows: Add 'hyperv' (#818, #849, #859) * config-windows: Add 'layerFolders' (#828) Removals and increased restrictions: * config: Remove 'platform' (#850) * config: Require strictly-postitive 'timeout' values (#764) * config: Strengthen punt to kernel for valid capabilities strings (#766, #790) * config: Require volume GUID paths for root.path (#849) * config: Forbid setting 'readonly' true on Windows (#819) * config: Forbid setting mount 'type' entirely on Windows and forbid UNC paths and mapped drives in 'source' on Windows (#821) * config: Remove 'hooks' from Windows spec (#855, #869, #870) * config-linux: Clearly require absolute path for namespace (#720) * config-linux: RFC 2119 tightening for namespaces (#767) * config-linux: Require at least one entry in linux.seccomp.syscalls[].names (#769) * config-linux: Remove syscall.comment (#714) * config-linux: Use MUST and MAY for weight and leafWeight (#751) * config-linux: Remove explicit 'null' from device cgroup values (#804) * runtime: Remove "features the runtime chooses to support" (#732) * runtime: Drop "not supported by the base OS" loophole (#733) * runtime-linux: Condition /proc/self/fd symlinks on source existence (#736) Decreased restrictions: * config: Make 'process' optional (#701, #805) * config-linux: Make linux.seccomp.syscalls optional (#768) * config-linux: valueTwo is now optional in `linux.seccomp.syscalls[].args` entries (#877) * config-linux: Remove local range restrictions for blkioWeight, blkioLeafWeight, weight, leafWeight, and shares (#780) * config-linux: Explicitly allow symlinks for providing devices (#873) Minor fixes and documentation: * config: Remove "MAY support any valid values" sentence (#851) * config: Remove the previously-forbidden mounts[].type from the Windows spec (#854) * config: Clarify mounts[].source relative path anchor (#735) * config: Explicitly make consoleSize ignored if terminal is false or unset (#863) * config: Specify height/width units (characters) for consoleSize (#761) * config: Use "POSIX platforms" instead of "Linux and Solaris" (#838) * config-linux: Explicit namespace for interface names (#713) * config-linux: Explicitly list cgroupsPath as optional (#823) * runtime: Clarify valid container states for 'start', 'kill', and 'delete' (#875) * runtime: Explicitly make process.* timing implementation-defined (#700) * specs-go/config: Remove range restrictions from Windows comments (#783) * specs-go/config: Add omitempty to LinuxSyscall.Args (#763) * specs-go/config: Use a pointer for Process.ConsoleSize (#792) * schema/README: Use v1.0.0 URL in examples to prepare for the 1.0.0 release (#881) * schema/Makefile: Make 'validate' the default target (#750) * schema/Makefile: Add 'clean' target (#774) * schema: Add 'test' target to the Makefile (#785) * *: Remove unnecessary .PHONY entries (#750, #778, #802) * *: Typo fixes and polishing (#681, #708, #702, #703, #709, #711, #712, #721, #722, #723, #724, #730, #737, #738, #741, #744, #749, #753, #756, #765, #773, #776, #784, #786, #793, #794, #796, #798, #799, #800, #803, #807, #809, #811, #812, #822, #824, #826, #827, #832, #839, #840, #846, #847, #848, #852, #856, #858, #862, #865, #871, #874) Changes with v1.0.0-rc5: Breaking changes: * config: Explicitly require `platform` (#695). * config: The platform-specific sections (`linux`, `solaris`, and `windows`) MUST NOT be set unless they match `platform.os` (#673). * config: `process.capabilities` is now an object instead of an array of strings (#675). * config-linux: No longer allow negative values for some resources, partially reversing #648 from v1.0.0-rc4 (#704). * config-linux: `linux.seccomp.syscalls` entries have `names` instead of `name` (#657). * runtime: Rename the state `bundlePath` property to `bundle` (#674). Additions: * config: `process.capabilities` is no longer Linux-only (#673). * config-linux: `linux.seccomp.syscalls` entries have a new `comment` property (#657). * config-linux: Add new architectures from libseccomp 2.3.2 (#705) * runtime: Add a `creating` state `status` (#507, #694). Removals and increased restrictions: * runtime: Document hook timing and exit code handling (#532). * schema/config-linux: Explicit `null` values are no longer compliant (#662). Decreased restrictions: * config: `type` and `source` properties are now optional for `mounts` entries (#699). * config: `args` property is now optional for hooks (#685). * config-linux: Runtimes no longer need to provide `/proc` and other filesystems unless they are explicitly requested in the configuration JSON (#666). Minor fixes and documentation: * spec: Add OCI Runtime Abstract (#691). * config: Document the Go `platform` tag (#570). * config-linux: Remove local uid/gid mapping limit and punt to the kernel (#693). * schema: Fix broken `string` and similar `$ref`s (#684). * schema: Remove `mounts` from required properties (#696). * schema: Remove `major` and `minor` from `linux.devices` entries (#688). * schema: Check for the required `type`, `hard`, and `soft` in `process.rlimits` entries (#696). * schema/validate: Gained usage documentation and fixed `schemaPath` logic when the argument did not contain `://` (#552). * *: Add anchor tags to a number of spec locations (#707). * *: Consistent link syntax (#687). * *: Minor cleanup and rewording (#697). Changes with v1.0.0-rc4: Additions: * config-linux: Allow negative values for some resources (#648) * config-linux: Lift no-tweaking namespace restriction (#649) Removals and increased restrictions: * config: Rlimit types must be unique (#607) * config: Forbid empty-string keys in 'annotations' (#645, #654) * config-linux: Require runtime errors for pre-existing devices (#647) * runtime: Only require 'pid' in the state for created/running statuses (#664) * schema: Add 'consoleSize' and update requirements (#646) * schema: Remove string pointers (#656) * schema/config-linux: Remove blockIODeviceThrottle and other pointers (#545) Breaking Go changes: * specs-go/config: Remove string pointers (#653) * specs-go/config: Make Spec.Hooks a pointer (#427) * specs-go/config: Convert some resources from unsigned integers to signed integers (#648) Minor fixes and documentation: * config: Explicitly list 'hooks' as optional and cite POSIX for 'env' and 'args' (#427) * runtime: Replace "process is stopped" with "process exits" (#465) * schema/config-linux: Add missing kernelTCP (#655) * schema/validate: Allow schema identifiers to contain a URL scheme (#490) * .travis: Fix git-validation commit ranges (#216) * *: Add anchor tags to a number of spec locations (#612, #636, #637, #638, #639, #640) * *: Typo fixes and polishing (#643, #650, #652, #656, #660, #665) Changes with v1.0.0-rc3: Additions: * config: Add support for Windows-based containers (#565, #573) * config: Add process.consoleSize (#563) * config: Explicitly allow unknown extensions and document annotations key conventions (#510) * config: Define mounts entries for Solaris (#588) Removals and increased restrictions: * config: Require absolute paths for mount destinations (#609) * config-linux: Require absolute path for maskedPaths and readonlyPaths (#587) * config-linux: Only require /dev/console when process.terminal is true. Also require /dev/console to be provided by a bind mount (#518) * runtime: Require runtimes to generate errors when the container specified in config.json cannot be created (#559) Breaking Go changes: * specs-go/config: Aggressive namespacing (#567) * specs-go/config: Remove pointers from LinuxHugepageLimit, LinuxInterfacePriority, and LinuxPids properties (#586) * specs-go/state: Rename version to ociVersion (#633) LinuxInterfacePriority, and LinuxPids properties (#586) Minor fixes and documentation: * spec: Separate the spec from project scaffolding (#626) * README: Define "unspecified", "undefined", and "implementation-defined" (#575) * config: Clarify absolue and relative values for root.path (#558) * config: Clarify ociVersion covering the configuration <-> runtime API (#523) * config-linux: Forbid duplicated namespaces with same `type` (#597) * glossary: Make objects explicitly unordered and forbid duplicate names (#584) * specs-go/config: Add platform tags to Rlimits and NoNewPRivileges (#564) * schema/defs-linux: Use int64 for major/minor types (#610) * Makefile: Add support for Go 1.7 (#547) * Makefile: Require Go >= 1.6 for golint (#589) * Makefile: Use a POSIX-compatible test ('==' -> '=') (#542) * implementations: Rename ocitools -> runtime-tools (#585) * *: Typo fixes and polishing (#556, #566, #568, #569, #571, #572, #574, #595, #596, #599, #600, #601, #603, #605, #608, #613, #617, #619, #621, #622, #623, #624, #625, #627, #629) Changes with v1.0.0-rc2: Additions: * config-linux: Add new architectures from libseccomp 2.3.0 (#505) * schema: Add JSON Schema for state JSON and move schema.json to config-schema.json and similar (#481, #498, #519) Minor fixes and documentation: * Add compliance language for platforms and architectures (#527) * Remove "unconditionally compliant" language (#553) * bundle: Remove distribution references (#487) * runtime: Fix sub-bullet indentation (#495) * config: Replace Arch fstab reference with mount(8) (#443) * config: Synchronize comments between Markdown and Go (#525) * config: Drop v0.x compatibility statement (#488) * config-linux: RFC 2119 wording for cgroupsPath (#493) * config-linux: Make linux.devices and linux.resources.devices optional (#526) * config-linux: Extend no-tweak requirement to runtime namespaces (#538) * schema: Add hook.timeout (#544) * schema: Add missing '"type": "object"' (#528) * schema: Run 'make fmt' and remove duplicates (#546, #551) * schema/config: Make 'hostname' optional (#491) * schema/config-linux: Add linux.resources.devices (#550) * specs-go/config: Add Solaris tags to User properties (#496) * specs-go/config: Make Linux and Solaris omitempty again (#502) * specs-go/config: Make KernelTCP and ClassID omitempty (#531) * specs-go/config: Fix "specified" typo for ApparmorProfile (#503) * Makefile: Remove code-of-conduct.md and version.md when clean (#541) * implementations: Mention cc-oci-runtime (#539) * Use filesystem instead of file system (#529) * .pullapprove: Add DCO check via PullApprove * GOVERNANCE: Add governance and release process docs (#521) * README: Change meeting time from 10am to 2pm Pacific (#524) * README: Update conference-call phone number (#512, #515) Changes with v1.0.0-rc1: Breaking changes: * runtime: Split create and start, #384, #450, #463, #464, #467, #468 * runtime: Remove exec, #388 * runtime: Enviroment MUST match the configuration, #397 * config: Runtime MUST generate errors for unsupported platforms, #441 * config: Windows mount destinations MUST NOT be nested, #437 Additions: * solaris: Added platform-specific configuration, #411, #424, #431, #436 * runtime: Add 'annotations' and 'status' to the state structure, #462, #484, #485 * runtime: State no longer needs to be serialized as JSON, #446 * runtime-linux: Add /dev symbolic links, #449 * config: Allow absolute paths for root.path (which previously required relative paths), #394 * config-linux: Add linux.mountLabel, #393 * config-linux: Add suport for cgroup namespace, #397 * config-linux: Runtime SHOULD NOT modify ownership of any referenced filesystem (previously the restriction only applied to the root filesystem), #452 * specs-go/seccomp: Add ppc and s390x to specs-go/config.go, #475 Minor fixes and documentation: * README: Add project.md to the Table of Contents, #376 * README: Consistenly indent the Table of Contents, #400 * README: Link to LICENSE, #442 * README: Weekly call is OCI-wide, #378 * config: Explicit runtime namespace for hooks, #415 * config: Explicit container namespace for uid, gid, and additionalGids, #412 * config: Fix 'string' -> 'array of strings' typo for process.args, #416 * runtime: The runtime MAY validate config.json, #418 * runtime: Move errors section out of operations, #445 * runtime: MAY -> SHOULD for post-stop error logging, #410 * schema/README: Document JSON Schema usage, #360, #385 * schema: Minor description updates, #456, #461 * schema/validate: Support reading documents via stdin, #482 * .pullapprove: Automate review approval, #458, #474 * .gitignore: Hide more auto-generated files, #386, #392 * .travis: git-validation detects Travis now, #366 * .travis: Regress on failure to produce docs, #479 * Makefile: Filename docs.* -> oci-runtime-spec.*, #478 * Makefile: Add install.tools target, #349 * Makefile: Allow native pandoc implementations, #428, #448 * Makefile: Prefer Bash, #455 * Makefile: Travis support for .gitvalidation, #422 * specs-go/config: Add missing omitempties for Process.Terminal, Root.Readonly, Spec.Linux, and Spec.Mounts, #408, #429, #430, #431 * specs-go/config: Remove incorrect omitempties for User.UID and User.GID, #425 * specs-go/config: Drop platform-independent comment, #451 * version: Include version in generated documentation, #406 * *: Anchor examples, #348 * *: Fix remnants from SelinuxProcessLabel to SelinuxLabel rename, #396 * *: Outsource code-of-conduct to TOB repository, #375, #413 * *: RFC 2119 consistency, #407, #409, #438, #444, #449 * *: Typo fixes, #390, #401 * *: Whitespace fixes and validation, #380, #381, #426 * ROADMAP: Remove stale targets, #435 Changes with v0.5.0: Breaking changes: * specs-go: Renamed the repository from opencontainers/specs to opencontainers/runtime-spec, #365 Additions: * config: Add 'timeout' for hooks, #346 * config-linux: Add 'maskedPaths' and 'readonlyPaths', #364 Minor fixes and documentation: * JSON Schema bug-fixes and improved examples, #370 * README: Define "unconditionally compliant", #374 * config: Make Markdown canonical, #342 * config: Explicitly list mapping from symbolic names to UID/GIDs as out-of-scope, #347 * config-linux: Require the runtime mount namespace for namespace 'path' values, #275 * config-linux: Reword kernelTCP docs, #377 * specs-go: Add omitempty to 'Device' and 'Namespace', #340 * .travis.yml: Use built-in 'go vet' and current 'go lint', dropping Go < 1.5, #372, #352 * implementations: Expand ocitools scope to include testing, #328 * style: Move one-sentence-per-line rule from the README, #369 * style: Remove dangling parenthesis, #359 * README: Add a link to the IRC logs, #358 * Fix "manadate", "exmaple", "paramters", and "preferrably" typos, #353, #354 Changes with v0.4.0: Breaking changes: * config: Move capabilities, selinuxProcessLabel, apparmorProfile, and noNewPrivileges from the linux setting to the process setting and make them optional, renaming selinuxProcessLabel to selinuxLabel, #329, #330, #339 * runtime: Rename version to ociVerison in the state JSON, #225 * runtime: Remove the directory requirement for storing state, now that there is a 'state' operation, #225, #334 * go: Shift *.go to specs-go/*.go, #276 * config: Move rlimits to process, #341 * go: Move config_linux.go content into config.go, removing LinuxSpec, #310 Additions: * schema: Add JSON Schema (and validator) for `config.json`, #313 * config: Add annotations for opaque-to-the-runtime data, #331 * config-linux: Make seccomp optional, #333 * runtime: Added additional operations: state, stop, and exec. #225 Minor fixes and documentation: * config-linux: Change mount type from *rune to *string and fix octal fileMode examples, #323 * runtime: RFC 2119 phrasing for the lifecycle, #225 * README: Add a full example of config.json, #276 * README: Replace BlueJeans with UberConference, #326, #338 * style: Document Go-pointer exceptions, #317 Changes with v0.3.0: Breaking changes: * config: Single, unified config file, #284 * config: cwd is a required default, and must be absolute, #286, #307, #308, #312 * config: qualify the name of the version field, #309 * config-linux: Convert classID from hex to uint32, #296 * config-linux: Separate mknod from cgroups, #298 Additions: * config-linux: Add NoNewPrivileges setting for linux, #290 Minor fixes and documentation: * config-linux: clarify oom_score_adj, #236, #292 * config-linux: Update links to cgroups documentation, #318 * config-linux: Remove pointers for slices preferring omitempty tag instead, #316 * README: add runtime, bundle, and hook author user, #280 * ROADMAP: reshuffled and split into GitHub issues, #300, #301, #304, #306 * style: Collect established styles in a discoverable location, #287, #311 Changes with v0.2.0: * Add Apparmor, Selinux and Seccomp * Add Apparmor, Selinux and Seccomp sections * Add bind mount example * Add fd section for linux container process * Add Go types for specification * *: adding a code of conduct * Adding cgroups path to the Spec. * .: Adding listing of implementations * .: adding travis file for future CI * Add license and DCO information for contributions * Add linux spec description * Add MAINTAINERS file * Add memory swappiness to linux spec * Add runtime state configuration and structs * Adds a section for user namespace mappings * Adds link to kernel cgroups documentation * Adds section for Linux Rlimits * Adds section for Linux Sysctl. * Adds user namespace to the list of namespaces * bundle: add initial run use case * bundle: Fix 'and any number of and other related' typo * bundle.md: clarify arbitrary/conventional dirnames * bundle.md: fix link formatting * bundle.md: fix off-by-one error * bundle.md: various updates to latest spec * bundle: Move 'Linux sysctl' header to its own line * Change commiter to committer * Change Device field order in spec_linux.go, 'Path' should be top of the 'Type' field, according to the different of the config-linux.md, 'Path' field is the unique key. * Change layout of mountpoints and mounts * Change the rlimit type to string instead of int * Clarify behavior around namespaces paths. * config: Add example additionalGids * config: Add example cwd * config: cleanup language on readonly parameter * config: fix links to go files * config-linux: specify the default devices/filesystems available * config.md: clarify destination for mounts * config.md: make the version a semver * config.md: make the version field example a semver * config.md: minor clean up of process specification * config.md: reformat into a standard style * config.md: update links to spec schema code * config.md: various cleanup/consistency fixes * config: minor cleanup * Deduplicate the field of RootfsPropagation * Define constants for Linux Namespace names * Fix LinuxRuntime field * Fix root object keys * Fix typos in config.md * Fix typos in the "Namespace types" section * Fix typos in the rlimits section * Fix Windows path escaping in example mount JSON * JSON objects are easier to parse/manipulate * made repo public. Added warning in README * Make namespaces match runc * make rootfs mount propagation mode settable * Makes namespaces description linux specific * *.md: markdown formatting * Modify the capabilities constants to match header files like other constants * Move linux specific options to linux spec * README: add a rule for paragraph formatting in markdown * README: Document BlueJeans and wiki archive for meetings * README: Document pre-meeting agenda alteration * README: Document YouTube and IRC backchannel for meetings * README: Focus on local runtime (create/start/stop) * README.md: Add a git commit style guide * README.md: contribution about discussion * README: releases section * README: Remove blank line from infrastructure-agnostic paragraph * removed boilerplate file * *: remove superfluous comma in code-of-conduct * Remove trailing whitespace * Rename SystemProperties to Sysctl * Rename the header "Access to devices" to "Devices" to fit with the config * *: re-org the spec * Replace Linux.Device with more specific config * restore formatting * Return golang compliant names for UID and GID in User * Return golint-compliant naming for mappings * runtime: Add prestart/poststop hooks * runtime_config: comments for golint * runtime-config-linux: Drop 'Linux' from headers * runtime_config_linux: Fix 'LinuxSpec' -> 'LinuxRuntimeSpec' in comment * runtime-config-linux: One sentence per line for opening two paragraphs * runtime-config: Remove blank lines from the end of files * runtime-config: Remove 'destination' docs from mounts * runtime.md: convert oc to runc * runtime: use opencontainer vs oci * *: small spelling fixes * Specific platform specific user struct for spec * spec: linux: add support for the PIDs cgroup * spec_linux: conform to `golint` * spec_linux.go: Rename IDMapping fields to follow syscall.SysProcIDMap * spec_linux: remove ending periods on one-line comments * spec: rename ocp to oci and add a link * specs: add json notation * specs: align the ascii graph * specs: fix the description for the [ug]idMappings * specs: introduce the concept of a runtime.json * .tools: cleanup the commit entry * .tools: repo validation tool * travis: fix DCO validation for merges * typo: containers -> container's * typo: the -> for * Update config-linux for better formatting on values * Update README.md * Update readme with weekly call and mailing list * Update runtime.md * Update runtime.md * Update runtime.md * version: more explicit version for comparison Changes with v0.1.0: * Add Architecture field to Seccomp configuration in Linux runtime * Add @hqhq as maintainer * Add hyphen for host specific * Adding Vishnu Kannan as a Maintainer. * Add initial roadmap * Add lifecycle for containers * Add oom_score_adj to the runtime Spec. * Add post-start hooks * Add Seccomp constants to description of Linux runtime spec * Add Seccomp constants to Linux runtime config * Add some clarity around the state.json file * adds text describing the upper-case keywords used in the spec * add testing framework to ROADMAP * Appropriately mark optional fields as omitempty * cgroup: Add support for memory.kmem.tcp.limit_in_bytes * Change HugepageLimit.Limit type to uint64 * Change the behavior when cgroupsPath is absent * Change version from 0.1.0 to 0.2.0 * Clarify the semantics of hook elements * Cleanup bundle.md * Cleanup principles * config: linux: update description of PidsLimit * config: Require a new UTS namespace for config.json's hostname * config: Require the runtime to mount Spec.Mounts in order * convert **name** to **`name`** * Example lists "root' but text mentions "bundlePath" * Fix an extra space in VersionMinor * Fix golint warnings * Fix typo in BlockIO struct comment * Fix typo in Filesystem Bundle * Fix value of swappiness * glossary: Provide a quick overview of important terms * glossary: Specify UTF-8 for all our JSON * hooks: deduplicate the hooks docs * implementations: Link to kunalkushwaha/octool * implementations: Link to mrunalp/ocitools * lifecycle: Don't require /run/opencontainer//containers * lifecycle: Mention runtime.json * lifecycle: no hypens * MAINTAINERS: add tianon per the charter * MAINTAINERS: correct Vish's github account * Makefile: Add glossary to DOC_FILES * Make optional Cgroup related config params pointers along with `omitempty` json tag. * Mark RootfsPropagation as omitempty * *.md: update TOC and links * move the description of Rlimits before example * move the description of user ns mapping to proper file * principles: Give principles their own home * *: printable documents * Project: document release process * README: Fix some headers * README: make header more concise * remove blank char from blank line * Remove the unneeded build tag from the config_linux.go * Remove trailing comma in hooks json example * Rename State's Root to Bundle * ROADMAP.md: remove the tail spaces * roadmap: update links and add wiki reference * runtime: Add 'version' to the state.json example * runtime-config: add example label before json example * runtime-config: add section about Hooks * runtime: config: linux: add cgroups information * runtime: config: linux: Edit BlockIO struct * runtime: config: linux: Fix typo and trailing commas in json example * runtime_config_linux.go: add missing pointer * runtime-config-linux.md: fix the type of cpus and mems * runtime.md: fix spacing * Talk about host specific/independent instead of mutability * .tools: commit validator is a separate project * .tools: make GetFetchHeadCommit do what it says * .travis.yml: add go 1.5.1, update from 1.4.2 to 1.4.3 * Update readme with wiki link to minutes * Update Typo in ROADMAP.md * Use unsigned for IDs * version: introduce a string for dev indication runtime-spec-1.0.1/GOVERNANCE.md000066400000000000000000000074311317561611500161100ustar00rootroot00000000000000# Project governance The [OCI charter][charter] §5.b.viii tasks an OCI Project's maintainers (listed in the repository's MAINTAINERS file and sometimes referred to as "the TDC", [§5.e][charter]) with: > Creating, maintaining and enforcing governance guidelines for the TDC, approved by the maintainers, and which shall be posted visibly for the TDC. This section describes generic rules and procedures for fulfilling that mandate. ## Proposing a motion A maintainer SHOULD propose a motion on the dev@opencontainers.org mailing list (except [security issues](#security-issues)) with another maintainer as a co-sponsor. ## Voting Voting on a proposed motion SHOULD happen on the dev@opencontainers.org mailing list (except [security issues](#security-issues)) with maintainers posting LGTM or REJECT. Maintainers MAY also explicitly not vote by posting ABSTAIN (which is useful to revert a previous vote). Maintainers MAY post multiple times (e.g. as they revise their position based on feedback), but only their final post counts in the tally. A proposed motion is adopted if two-thirds of votes cast, a quorum having voted, are in favor of the release. Voting SHOULD remain open for a week to collect feedback from the wider community and allow the maintainers to digest the proposed motion. Under exceptional conditions (e.g. non-major security fix releases) proposals which reach quorum with unanimous support MAY be adopted earlier. A maintainer MAY choose to reply with REJECT. A maintainer posting a REJECT MUST include a list of concerns or links to written documentation for those concerns (e.g. GitHub issues or mailing-list threads). The maintainers SHOULD try to resolve the concerns and wait for the rejecting maintainer to change their opinion to LGTM. However, a motion MAY be adopted with REJECTs, as outlined in the previous paragraphs. ## Quorum A quorum is established when at least two-thirds of maintainers have voted. For projects that are not specifications, a [motion to release](#release-approval) MAY be adopted if the tally is at least three LGTMs and no REJECTs, even if three votes does not meet the usual two-thirds quorum. ## Security issues Motions with sensitive security implications MUST be proposed on the security@opencontainers.org mailing list instead of dev@opencontainers.org, but should otherwise follow the standard [proposal](#proposing-a-motion) process. The security@opencontainers.org mailing list includes all members of the TOB. The TOB will contact the project maintainers and provide a channel for discussing and voting on the motion, but voting will otherwise follow the standard [voting](#voting) and [quorum](#quorum) rules. The TOB and project maintainers will work together to notify affected parties before making an adopted motion public. ## Amendments The [project governance](#project-governance) rules and procedures MAY be amended or replaced using the procedures themselves. The MAINTAINERS of this project governance document is the total set of MAINTAINERS from all Open Containers projects (runC, runtime-spec, and image-spec). ## Subject templates Maintainers are busy and get lots of email. To make project proposals recognizable, proposed motions SHOULD use the following subject templates. ### Proposing a motion > [{project} VOTE]: {motion description} (closes {end of voting window}) For example: > [runtime-spec VOTE]: Tag 0647920 as 1.0.0-rc (closes 2016-06-03 20:00 UTC) ### Tallying results After voting closes, a maintainer SHOULD post a tally to the motion thread with a subject template like: > [{project} {status}]: {motion description} (+{LGTMs} -{REJECTs} #{ABSTAINs}) Where `{status}` is either `adopted` or `rejected`. For example: > [runtime-spec adopted]: Tag 0647920 as 1.0.0-rc (+6 -0 #3) [charter]: https://www.opencontainers.org/about/governance runtime-spec-1.0.1/LICENSE000066400000000000000000000250171317561611500151440ustar00rootroot00000000000000 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. runtime-spec-1.0.1/MAINTAINERS000066400000000000000000000006021317561611500156250ustar00rootroot00000000000000Michael Crosby (@crosbymichael) Vishnu Kannan (@vishh) Mrunal Patel (@mrunalp) Vincent Batts (@vbatts) Daniel, Dao Quang Minh (@dqminh) Brandon Philips (@philips) Tianon Gravi (@tianon) Qiang Huang (@hqhq) runtime-spec-1.0.1/Makefile000066400000000000000000000055251317561611500156010ustar00rootroot00000000000000 EPOCH_TEST_COMMIT := 78e6667ae2d67aad100b28ee9580b41b7a24e667 OUTPUT_DIRNAME ?= output DOC_FILENAME ?= oci-runtime-spec DOCKER ?= $(shell command -v docker 2>/dev/null) PANDOC ?= $(shell command -v pandoc 2>/dev/null) ifeq "$(strip $(PANDOC))" '' ifneq "$(strip $(DOCKER))" '' PANDOC = $(DOCKER) run \ -it \ --rm \ -v $(shell pwd)/:/input/:ro \ -v $(shell pwd)/$(OUTPUT_DIRNAME)/:/$(OUTPUT_DIRNAME)/ \ -u $(shell id -u) \ vbatts/pandoc PANDOC_SRC := /input/ PANDOC_DST := / endif endif # These docs are in an order that determines how they show up in the PDF/HTML docs. DOC_FILES := \ version.md \ spec.md \ principles.md \ bundle.md \ runtime.md \ runtime-linux.md \ config.md \ config-linux.md \ config-solaris.md \ glossary.md default: docs docs: $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html ifeq "$(strip $(PANDOC))" '' $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: $(error cannot build $@ without either pandoc or docker) else $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES) mkdir -p $(OUTPUT_DIRNAME)/ && \ $(PANDOC) -f markdown_github -t latex -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES)) $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: $(DOC_FILES) mkdir -p $(OUTPUT_DIRNAME)/ && \ $(PANDOC) -f markdown_github -t html5 -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES)) endif version.md: ./specs-go/version.go go run ./.tool/version-doc.go > $@ HOST_GOLANG_VERSION = $(shell go version | cut -d ' ' -f3 | cut -c 3-) # this variable is used like a function. First arg is the minimum version, Second arg is the version to be checked. ALLOWED_GO_VERSION = $(shell test '$(shell /bin/echo -e "$(1)\n$(2)" | sort -V | head -n1)' = '$(1)' && echo 'true') test: .govet .golint .gitvalidation .govet: go vet -x ./... # `go get github.com/golang/lint/golint` .golint: ifeq ($(call ALLOWED_GO_VERSION,1.6,$(HOST_GOLANG_VERSION)),true) @which golint > /dev/null 2>/dev/null || (echo "ERROR: golint not found. Consider 'make install.tools' target" && false) golint ./... endif # When this is running in travis, it will only check the travis commit range .gitvalidation: @which git-validation > /dev/null 2>/dev/null || (echo "ERROR: git-validation not found. Consider 'make install.tools' target" && false) ifdef TRAVIS_COMMIT_RANGE git-validation -q -run DCO,short-subject,dangling-whitespace else git-validation -v -run DCO,short-subject,dangling-whitespace -range $(EPOCH_TEST_COMMIT)..HEAD endif install.tools: .install.golint .install.gitvalidation # golint does not even build for 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`. #### Commit Style Simple house-keeping for clean git history. 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 3. Capitalize the subject line 4. Do not end the subject line with a period 5. Use the imperative mood in the subject line 6. Wrap the body at 72 characters 7. Use the body to explain what and why vs. how * 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: ...") [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/ [iso-week]: https://en.wikipedia.org/wiki/ISO_week_date#Calculating_the_week_number_of_a_given_date [minutes]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/ [oci]: https://www.opencontainers.org [rfc5545]: https://tools.ietf.org/html/rfc5545 [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 runtime-spec-1.0.1/RELEASES.md000066400000000000000000000067021317561611500156640ustar00rootroot00000000000000# Releases The release process hopes to encourage early, consistent consensus-building during project development. The mechanisms used are regular community communication on the mailing list about progress, scheduled meetings for issue resolution and release triage, and regularly paced and communicated releases. Releases are proposed and adopted or rejected using the usual [project governance](GOVERNANCE.md) rules and procedures. An anti-pattern that we want to avoid is heavy development or discussions "late cycle" around major releases. We want to build a community that is involved and communicates consistently through all releases instead of relying on "silent periods" as a judge of stability. ## Parallel releases A single project MAY consider several motions to release in parallel. However each motion to release after the initial 0.1.0 MUST be based on a previous release that has already landed. For example, runtime-spec maintainers may propose a v1.0.0-rc2 on the 1st of the month and a v0.9.1 bugfix on the 2nd of the month. They may not propose a v1.0.0-rc3 until the v1.0.0-rc2 is accepted (on the 7th if the vote initiated on the 1st passes). ## Specifications The OCI maintains three categories of projects: specifications, applications, and conformance-testing tools. However, specification releases have special restrictions in the [OCI charter][charter]: * They are the target of backwards compatibility (§7.g), and * They are subject to the OFWa patent grant (§8.d and e). To avoid unfortunate side effects (onerous backwards compatibity requirements or Member resignations), the following additional procedures apply to specification releases: ### Planning a release Every OCI specification project SHOULD hold meetings that involve maintainers reviewing pull requests, debating outstanding issues, and planning releases. This meeting MUST be advertised on the project README and MAY happen on a phone call, video conference, or on IRC. Maintainers MUST send updates to the dev@opencontainers.org with results of these meetings. Before the specification reaches v1.0.0, the meetings SHOULD be weekly. Once a specification has reached v1.0.0, the maintainers may alter the cadence, but a meeting MUST be held within four weeks of the previous meeting. The release plans, corresponding milestones and estimated due dates MUST be published on GitHub (e.g. https://github.com/opencontainers/runtime-spec/milestones). GitHub milestones and issues are only used for community organization and all releases MUST follow the [project governance](GOVERNANCE.md) rules and procedures. ### Timelines Specifications have a variety of different timelines in their lifecycle. * Pre-v1.0.0 specifications SHOULD release on a monthly cadence to garner feedback. * Major specification releases MUST release at least three release candidates spaced a minimum of one week apart. This means a major release like a v1.0.0 or v2.0.0 release will take 1 month at minimum: one week for rc1, one week for rc2, one week for rc3, and one week for the major release itself. Maintainers SHOULD strive to make zero breaking changes during this cycle of release candidates and SHOULD restart the three-candidate count when a breaking change is introduced. For example if a breaking change is introduced in v1.0.0-rc2 then the series would end with v1.0.0-rc4 and v1.0.0. - Minor and patch releases SHOULD be made on an as-needed basis. [charter]: https://www.opencontainers.org/about/governance runtime-spec-1.0.1/bundle.md000066400000000000000000000027461317561611500157360ustar00rootroot00000000000000# Filesystem Bundle ## 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 [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. A Standard Container bundle contains all the information needed to load and run a container. This includes the following artifacts: 1. `config.json`: contains configuration data. This REQUIRED file MUST reside in the root of the bundle directory and MUST be named `config.json`. See [`config.json`](config.md) for more details. 2. container's root filesystem: the directory referenced by [`root.path`](config.md#root), if that property is set in `config.json`. When supplied, 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 runtime-spec-1.0.1/config-linux.md000066400000000000000000000650241317561611500170650ustar00rootroot00000000000000# Linux Container Configuration This document describes the schema for the [Linux-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md). The Linux container specification uses various kernel features like namespaces, cgroups, capabilities, LSM, and filesystem jails to fulfill the spec. ## Default Filesystems The Linux ABI includes both syscalls and several special file paths. Applications expecting a Linux environment will very likely expect these file paths to be set up correctly. The following filesystems SHOULD be made available in each container's filesystem: | Path | Type | | -------- | ------ | | /proc | [proc][] | | /sys | [sysfs][] | | /dev/pts | [devpts][] | | /dev/shm | [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 [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 set up namespaces: * **`type`** *(string, REQUIRED)* - namespace type. The following namespace types are supported: * **`pid`** processes inside the container will only be able to see other processes inside the same container. * **`network`** the container will have its own network stack. * **`mount`** the container will have an isolated mount table. * **`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. * **`cgroup`** the container will have an isolated view of the cgroup hierarchy. * **`path`** *(string, OPTIONAL)* - namespace file. This value MUST be an absolute path in the [runtime mount namespace](glossary.md#runtime-namespace). The runtime MUST place the container process in the namespace associated with that `path`. The runtime MUST [generate an error](runtime.md#errors) if `path` is not associated with a namespace of type `type`. If `path` is not specified, the runtime MUST create a new [container namespace](glossary.md#container-namespace) of type `type`. If a namespace type is not specified in the `namespaces` array, the container MUST inherit the [runtime namespace](glossary.md#runtime-namespace) of that type. If a `namespaces` field contains duplicated namespaces with same `type`, the runtime MUST [generate an error](runtime.md#errors). ### Example ```json "namespaces": [ { "type": "pid", "path": "/proc/1234/ns/pid" }, { "type": "network", "path": "/var/run/netns/neta" }, { "type": "mount" }, { "type": "ipc" }, { "type": "uts" }, { "type": "user" }, { "type": "cgroup" } ] ``` ## User namespace mappings **`uidMappings`** (array of objects, OPTIONAL) describes the user namespace uid mappings from the host to the container. **`gidMappings`** (array of objects, OPTIONAL) describes the user namespace gid mappings from the host to the container. Each entry has the following structure: * **`hostID`** *(uint32, REQUIRED)* - is the starting uid/gid on the host to be mapped to *containerID*. * **`containerID`** *(uint32, REQUIRED)* - is the starting uid/gid in the container. * **`size`** *(uint32, REQUIRED)* - is the number of ids to be mapped. The runtime SHOULD NOT modify the ownership of referenced filesystems to realize the mapping. Note that the number of mapping entries MAY be limited by the [kernel][user-namespaces]. ### Example ```json "uidMappings": [ { "hostID": 1000, "containerID": 0, "size": 32000 } ], "gidMappings": [ { "hostID": 1000, "containerID": 0, "size": 32000 } ] ``` ## Devices **`devices`** (array of objects, OPTIONAL) lists devices that MUST be available in the container. The runtime MAY supply them however it likes (with [`mknod`][mknod.2], by bind mounting from the runtime mount namespace, using symlinks, etc.). Each entry has the following structure: * **`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. If a [file][] already exists at `path` that does not match the requested device, the runtime MUST generate an error. * **`major, minor`** *(int64, REQUIRED unless `type` is `p`)* - [major, minor numbers][devices] for the device. * **`fileMode`** *(uint32, OPTIONAL)* - file mode for the device. You can also control access to devices [with cgroups](#device-whitelist). * **`uid`** *(uint32, OPTIONAL)* - id of device owner. * **`gid`** *(uint32, OPTIONAL)* - id of device group. The same `type`, `major` and `minor` SHOULD NOT be used for multiple devices. ### Example ```json "devices": [ { "path": "/dev/fuse", "type": "c", "major": 10, "minor": 229, "fileMode": 438, "uid": 0, "gid": 0 }, { "path": "/dev/sda", "type": "b", "major": 8, "minor": 0, "fileMode": 432, "uid": 0, "gid": 0 } ] ``` ### Default Devices In addition to any devices configured with this setting, the runtime MUST also supply: * [`/dev/null`][null.4] * [`/dev/zero`][zero.4] * [`/dev/full`][full.4] * [`/dev/random`][random.4] * [`/dev/urandom`][random.4] * [`/dev/tty`][tty.4] * [`/dev/console`][console.4] is set up if terminal is enabled in the config by bind mounting the pseudoterminal slave to /dev/console. * [`/dev/ptmx`][pts.4]. A [bind-mount or symlink of the container's `/dev/pts/ptmx`][devpts]. ## Control groups Also known as cgroups, they are used to restrict resource usage for a container and handle device access. cgroups provide controls (through controllers) to restrict cpu, memory, IO, pids and network for the container. For more information, see the [kernel cgroups documentation][cgroup-v1]. ### Cgroups Path **`cgroupsPath`** (string, OPTIONAL) path to the cgroups. It can be used to either control the cgroups hierarchy for containers or to run a new process in an existing container. The value of `cgroupsPath` MUST be either an absolute path or a relative path. * In the case of an absolute path (starting with `/`), the runtime MUST take the path to be relative to the cgroups mount point. * In the case of a relative path (not starting with `/`), the runtime MAY interpret the path relative to a runtime-determined location in the cgroups hierarchy. If the value is specified, the runtime MUST consistently attach to the same place in the cgroups hierarchy given the same value of `cgroupsPath`. If the value is not specified, the runtime MAY define the default cgroups path. Runtimes MAY consider certain `cgroupsPath` values to be invalid, and MUST generate an error if this is the case. Implementations of the Spec can choose to name cgroups in any manner. The Spec does not include naming schema for cgroups. The Spec does not support per-controller paths for the reasons discussed in the [cgroupv2 documentation][cgroup-v2]. The cgroups will be created if they don't exist. You can configure a container's cgroups via the `resources` field of the Linux configuration. Do not specify `resources` unless limits have to be updated. For example, to run a new process in an existing container without updating limits, `resources` need not be specified. Runtimes MAY attach the container process to additional cgroup controllers beyond those necessary to fulfill the `resources` settings. ### Example ```json "cgroupsPath": "/myRuntime/myContainer", "resources": { "memory": { "limit": 100000, "reservation": 200000 }, "devices": [ { "allow": false, "access": "rwm" } ] } ``` ### Device whitelist **`devices`** (array of objects, OPTIONAL) configures the [device whitelist][cgroup-v1-devices]. The runtime MUST apply entries in the listed order. Each entry has the following structure: * **`allow`** *(boolean, REQUIRED)* - whether the entry is allowed or denied. * **`type`** *(string, OPTIONAL)* - type of device: `a` (all), `c` (char), or `b` (block). Unset values mean "all", mapping to `a`. * **`major, minor`** *(int64, OPTIONAL)* - [major, minor numbers][devices] for the device. Unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices]. * **`access`** *(string, OPTIONAL)* - cgroup permissions for device. A composition of `r` (read), `w` (write), and `m` (mknod). #### Example ```json "devices": [ { "allow": false, "access": "rwm" }, { "allow": true, "type": "c", "major": 10, "minor": 229, "access": "rw" }, { "allow": true, "type": "b", "major": 8, "minor": 0, "access": "r" } ] ``` ### Memory **`memory`** (object, OPTIONAL) represents the cgroup subsystem `memory` and it's used to set limits on the container's memory usage. For more information, see the kernel cgroups documentation about [memory][cgroup-v1-memory]. Values for memory specify the limit in bytes, or `-1` for unlimited memory. * **`limit`** *(int64, OPTIONAL)* - sets limit of memory usage * **`reservation`** *(int64, OPTIONAL)* - sets soft limit of memory usage * **`swap`** *(int64, OPTIONAL)* - sets limit of memory+Swap usage * **`kernel`** *(int64, OPTIONAL)* - sets hard limit for kernel memory * **`kernelTCP`** *(int64, OPTIONAL)* - sets hard limit for kernel TCP buffer memory The following properties do not specify memory limits, but are covered by the `memory` controller: * **`swappiness`** *(uint64, OPTIONAL)* - sets swappiness parameter of vmscan (See sysctl's vm.swappiness) The values are from 0 to 100. Higher means more swappy. * **`disableOOMKiller`** *(bool, OPTIONAL)* - enables or disables the OOM killer. If enabled (`false`), tasks that attempt to consume more memory than they are allowed are immediately killed by the OOM killer. The OOM killer is enabled by default in every cgroup using the `memory` subsystem. To disable it, specify a value of `true`. #### Example ```json "memory": { "limit": 536870912, "reservation": 536870912, "swap": 536870912, "kernel": -1, "kernelTCP": -1, "swappiness": 0, "disableOOMKiller": false } ``` ### CPU **`cpu`** (object, OPTIONAL) represents the cgroup subsystems `cpu` and `cpusets`. For more information, see the kernel cgroups documentation about [cpusets][cgroup-v1-cpusets]. The following parameters can be specified to set up the controller: * **`shares`** *(uint64, OPTIONAL)* - specifies a relative share of CPU time available to the tasks in a cgroup * **`quota`** *(int64, OPTIONAL)* - specifies the total amount of time in microseconds for which all tasks in a cgroup can run during one period (as defined by **`period`** below) * **`period`** *(uint64, OPTIONAL)* - specifies a period of time in microseconds for how regularly a cgroup's access to CPU resources should be reallocated (CFS scheduler only) * **`realtimeRuntime`** *(int64, OPTIONAL)* - specifies a period of time in microseconds for the longest continuous period in which the tasks in a cgroup have access to CPU resources * **`realtimePeriod`** *(uint64, OPTIONAL)* - same as **`period`** but applies to realtime scheduler only * **`cpus`** *(string, OPTIONAL)* - list of CPUs the container will run in * **`mems`** *(string, OPTIONAL)* - list of Memory Nodes the container will run in #### Example ```json "cpu": { "shares": 1024, "quota": 1000000, "period": 500000, "realtimeRuntime": 950000, "realtimePeriod": 1000000, "cpus": "2-3", "mems": "0-7" } ``` ### Block IO **`blockIO`** (object, OPTIONAL) represents the cgroup subsystem `blkio` which implements the block IO controller. For more information, see the kernel cgroups documentation about [blkio][cgroup-v1-blkio]. The following parameters can be specified to set up the controller: * **`weight`** *(uint16, OPTIONAL)* - specifies per-cgroup weight. This is default weight of the group on all devices until and unless overridden by per-device rules. * **`leafWeight`** *(uint16, OPTIONAL)* - equivalents of `weight` for the purpose of deciding how much weight tasks in the given cgroup has while competing with the cgroup's child cgroups. * **`weightDevice`** *(array of objects, OPTIONAL)* - an array of per-device bandwidth weights. Each entry has the following structure: * **`major, minor`** *(int64, REQUIRED)* - major, minor numbers for device. For more information, see the [mknod(1)][mknod.1] man page. * **`weight`** *(uint16, OPTIONAL)* - bandwidth weight for the device. * **`leafWeight`** *(uint16, OPTIONAL)* - bandwidth weight for the device while competing with the cgroup's child cgroups, CFQ scheduler only You MUST specify at least one of `weight` or `leafWeight` in a given entry, and MAY specify both. * **`throttleReadBpsDevice`**, **`throttleWriteBpsDevice`** *(array of objects, OPTIONAL)* - an array of per-device bandwidth rate limits. Each entry has the following structure: * **`major, minor`** *(int64, REQUIRED)* - major, minor numbers for device. For more information, see the [mknod(1)][mknod.1] man page. * **`rate`** *(uint64, REQUIRED)* - bandwidth rate limit in bytes per second for the device * **`throttleReadIOPSDevice`**, **`throttleWriteIOPSDevice`** *(array of objects, OPTIONAL)* - an array of per-device IO rate limits. Each entry has the following structure: * **`major, minor`** *(int64, REQUIRED)* - major, minor numbers for device. For more information, see the [mknod(1)][mknod.1] man page. * **`rate`** *(uint64, REQUIRED)* - IO rate limit for the device #### Example ```json "blockIO": { "weight": 10, "leafWeight": 10, "weightDevice": [ { "major": 8, "minor": 0, "weight": 500, "leafWeight": 300 }, { "major": 8, "minor": 16, "weight": 500 } ], "throttleReadBpsDevice": [ { "major": 8, "minor": 0, "rate": 600 } ], "throttleWriteIOPSDevice": [ { "major": 8, "minor": 16, "rate": 300 } ] } ``` ### Huge page limits **`hugepageLimits`** (array of objects, OPTIONAL) represents the `hugetlb` controller which allows to limit the HugeTLB usage per control group and enforces the controller limit during page fault. For more information, see the kernel cgroups documentation about [HugeTLB][cgroup-v1-hugetlb]. Each entry has the following structure: * **`pageSize`** *(string, REQUIRED)* - hugepage size * **`limit`** *(uint64, REQUIRED)* - limit in bytes of *hugepagesize* HugeTLB usage #### Example ```json "hugepageLimits": [ { "pageSize": "2MB", "limit": 209715200 } ] ``` ### Network **`network`** (object, OPTIONAL) represents the cgroup subsystems `net_cls` and `net_prio`. For more information, see the kernel cgroups documentations about [net\_cls cgroup][cgroup-v1-net-cls] and [net\_prio cgroup][cgroup-v1-net-prio]. The following parameters can be specified to set up the controller: * **`classID`** *(uint32, OPTIONAL)* - is the network class identifier the cgroup's network packets will be tagged with * **`priorities`** *(array of objects, OPTIONAL)* - specifies a list of objects of the priorities assigned to traffic originating from processes in the group and egressing the system on various interfaces. The following parameters can be specified per-priority: * **`name`** *(string, REQUIRED)* - interface name in [runtime network namespace](glossary.md#runtime-namespace) * **`priority`** *(uint32, REQUIRED)* - priority applied to the interface #### Example ```json "network": { "classID": 1048577, "priorities": [ { "name": "eth0", "priority": 500 }, { "name": "eth1", "priority": 1000 } ] } ``` ### PIDs **`pids`** (object, OPTIONAL) represents the cgroup subsystem `pids`. For more information, see the kernel cgroups documentation about [pids][cgroup-v1-pids]. The following parameters can be specified to set up the controller: * **`limit`** *(int64, REQUIRED)* - specifies the maximum number of tasks in the cgroup #### Example ```json "pids": { "limit": 32771 } ``` ## IntelRdt **`intelRdt`** (object, OPTIONAL) represents the [Intel Resource Director Technology][intel-rdt-cat-kernel-interface]. If `intelRdt` is set, the runtime MUST write the container process ID to the `/tasks` file in a mounted `resctrl` pseudo-filesystem, using the container ID from [`start`](runtime.md#start) and creating the `` directory if necessary. If no mounted `resctrl` pseudo-filesystem is available in the [runtime mount namespace](glossary.md#runtime-namespace), the runtime MUST [generate an error](runtime.md#errors). If `intelRdt` is not set, the runtime MUST NOT manipulate any `resctrl` pseudo-filesystems. The following parameters can be specified for the container: * **`l3CacheSchema`** *(string, OPTIONAL)* - specifies the schema for L3 cache id and capacity bitmask (CBM). If `l3CacheSchema` is set, runtimes MUST write the value to the `schemata` file in the `` directory discussed in `intelRdt`. If `l3CacheSchema` is not set, runtimes MUST NOT write to `schemata` files in any `resctrl` pseudo-filesystems. ### Example Consider a two-socket machine with two L3 caches where the default CBM is 0xfffff and the max CBM length is 20 bits. Tasks inside the container only have access to the "upper" 80% of L3 cache id 0 and the "lower" 50% L3 cache id 1: ```json "linux": { "intelRdt": { "l3CacheSchema": "L3:0=ffff0;1=3ff" } } ``` ## Sysctl **`sysctl`** (object, OPTIONAL) allows kernel parameters to be modified at runtime for the container. For more information, see the [sysctl(8)][sysctl.8] man page. ### Example ```json "sysctl": { "net.ipv4.ip_forward": "1", "net.core.somaxconn": "256" } ``` ## 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][seccomp] kernel documentation. The actions, architectures, and operators are strings that match the definitions in seccomp.h from [libseccomp][] and are translated to corresponding values. **`seccomp`** (object, OPTIONAL) The following parameters can be specified to set up seccomp: * **`defaultAction`** *(string, REQUIRED)* - the default action for seccomp. Allowed values are the same as `syscalls[].action`. * **`architectures`** *(array of strings, OPTIONAL)* - the architecture used for system calls. A valid list of constants as of libseccomp v2.3.2 is shown below. * `SCMP_ARCH_X86` * `SCMP_ARCH_X86_64` * `SCMP_ARCH_X32` * `SCMP_ARCH_ARM` * `SCMP_ARCH_AARCH64` * `SCMP_ARCH_MIPS` * `SCMP_ARCH_MIPS64` * `SCMP_ARCH_MIPS64N32` * `SCMP_ARCH_MIPSEL` * `SCMP_ARCH_MIPSEL64` * `SCMP_ARCH_MIPSEL64N32` * `SCMP_ARCH_PPC` * `SCMP_ARCH_PPC64` * `SCMP_ARCH_PPC64LE` * `SCMP_ARCH_S390` * `SCMP_ARCH_S390X` * `SCMP_ARCH_PARISC` * `SCMP_ARCH_PARISC64` * **`syscalls`** *(array of objects, OPTIONAL)* - match a syscall in seccomp. While this property is OPTIONAL, some values of `defaultAction` are not useful without `syscalls` entries. For example, if `defaultAction` is `SCMP_ACT_KILL` and `syscalls` is empty or unset, the kernel will kill the container process on its first syscall. Each entry has the following structure: * **`names`** *(array of strings, REQUIRED)* - the names of the syscalls. `names` MUST contain at least one entry. * **`action`** *(string, REQUIRED)* - the action for seccomp rules. A valid list of constants as of libseccomp v2.3.2 is shown below. * `SCMP_ACT_KILL` * `SCMP_ACT_TRAP` * `SCMP_ACT_ERRNO` * `SCMP_ACT_TRACE` * `SCMP_ACT_ALLOW` * **`args`** *(array of objects, OPTIONAL)* - the specific syscall in seccomp. Each entry has the following structure: * **`index`** *(uint, REQUIRED)* - the index for syscall arguments in seccomp. * **`value`** *(uint64, REQUIRED)* - the value for syscall arguments in seccomp. * **`valueTwo`** *(uint64, OPTIONAL)* - the value for syscall arguments in seccomp. * **`op`** *(string, REQUIRED)* - the operator for syscall arguments in seccomp. A valid list of constants as of libseccomp v2.3.2 is shown below. * `SCMP_CMP_NE` * `SCMP_CMP_LT` * `SCMP_CMP_LE` * `SCMP_CMP_EQ` * `SCMP_CMP_GE` * `SCMP_CMP_GT` * `SCMP_CMP_MASKED_EQ` ### Example ```json "seccomp": { "defaultAction": "SCMP_ACT_ALLOW", "architectures": [ "SCMP_ARCH_X86", "SCMP_ARCH_X32" ], "syscalls": [ { "names": [ "getcwd", "chmod" ], "action": "SCMP_ACT_ERRNO" } ] } ``` ## Rootfs Mount Propagation **`rootfsPropagation`** (string, OPTIONAL) sets the rootfs's mount propagation. Its value is either slave, private, shared or unbindable. The [Shared Subtrees][sharedsubtree] article in the kernel documentation has more information about mount propagation. ### Example ```json "rootfsPropagation": "slave", ``` ## Masked Paths **`maskedPaths`** (array of strings, OPTIONAL) will mask over the provided paths inside the container so that they cannot be read. The values MUST be absolute paths in the [container namespace](glossary.md#container_namespace). ### Example ```json "maskedPaths": [ "/proc/kcore" ] ``` ## Readonly Paths **`readonlyPaths`** (array of strings, OPTIONAL) will set the provided paths as readonly inside the container. The values MUST be absolute paths in the [container namespace](glossary.md#container-namespace). ### Example ```json "readonlyPaths": [ "/proc/sys" ] ``` ## Mount Label **`mountLabel`** (string, OPTIONAL) will set the Selinux context for the mounts in the container. ### Example ```json "mountLabel": "system_u:object_r:svirt_sandbox_file_t:s0:c715,c811" ``` [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 [cgroup-v1-devices]: https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt [cgroup-v1-hugetlb]: https://www.kernel.org/doc/Documentation/cgroup-v1/hugetlb.txt [cgroup-v1-memory]: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt [cgroup-v1-net-cls]: https://www.kernel.org/doc/Documentation/cgroup-v1/net_cls.txt [cgroup-v1-net-prio]: https://www.kernel.org/doc/Documentation/cgroup-v1/net_prio.txt [cgroup-v1-pids]: https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt [cgroup-v2]: https://www.kernel.org/doc/Documentation/cgroup-v2.txt [devices]: https://www.kernel.org/doc/Documentation/admin-guide/devices.txt [devpts]: https://www.kernel.org/doc/Documentation/filesystems/devpts.txt [file]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_164 [libseccomp]: https://github.com/seccomp/libseccomp [proc]: 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 [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 [intel-rdt-cat-kernel-interface]: https://www.kernel.org/doc/Documentation/x86/intel_rdt_ui.txt runtime-spec-1.0.1/config-solaris.md000066400000000000000000000137441317561611500174040ustar00rootroot00000000000000# 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(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. **`milestone`** *(string, OPTIONAL)* ### Example ```json "milestone": "svc:/milestone/container:default" ``` ## 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)][priv-str-to-set.3c] man page for the respective release of Solaris. **`limitpriv`** *(string, OPTIONAL)* ### Example ```json "limitpriv": "default" ``` ## 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(1M)][zonecfg.1m_2] man page. **`maxShmMemory`** *(string, OPTIONAL)* ### Example ```json "maxShmMemory": "512m" ``` ## cappedCPU 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(1M)][zonecfg.1m_2] man page. * **`ncpus`** *(string, OPTIONAL)* ### Example ```json "cappedCPU": { "ncpus": "8" } ``` ## 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(1M)][zonecfg.1m_2] man page. * **`physical`** *(string, OPTIONAL)* * **`swap`** *(string, OPTIONAL)* ### Example ```json "cappedMemory": { "physical": "512m", "swap": "512m" } ``` ## Network ### Automatic Network (anet) anet is specified as an array that is used to set up 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 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 set up automatic networks. For additional information on properties, check the [zonecfg(1M)][zonecfg.1m_2] 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(1M)][zonecfg.1m_2] 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(1M)][zonecfg.1m_2] 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(1M)][zonecfg.1m_2] 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. If not a keyword, it is interpreted as a unicast MAC address. For a list of the supported keywords please refer to the [zonecfg(1M)][zonecfg.1m_2] man page of the respective Solaris release. Mapped to `mac-address` in the [zonecfg(1M)][zonecfg.1m_2] 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(1M)][zonecfg.1m_2] man page. #### Example ```json "anet": [ { "allowedAddress": "172.17.0.2/16", "configureAllowedAddress": "true", "defrouter": "172.17.0.1/16", "linkProtection": "mac-nospoof, ip-nospoof", "linkname": "net0", "lowerLink": "net2", "macAddress": "02:42:f8:52:c7:16" } ] ``` [priv-str-to-set.3c]: http://docs.oracle.com/cd/E86824_01/html/E54766/priv-str-to-set-3c.html [zoneadmd.1m]: http://docs.oracle.com/cd/E86824_01/html/E54764/zoneadmd-1m.html [zonecfg.1m_2]: http://docs.oracle.com/cd/E86824_01/html/E54764/zonecfg-1m.html runtime-spec-1.0.1/config-windows.md000066400000000000000000000134131317561611500174130ustar00rootroot00000000000000# Windows-specific Container Configuration This document describes the schema for the [Windows-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md). The Windows container specification uses APIs provided by the Windows Host Compute Service (HCS) to fulfill the spec. ## LayerFolders **`layerFolders`** (array of strings, REQUIRED) specifies a list of layer folders the container image relies on. The list is ordered from topmost layer to base layer. `layerFolders` MUST contain at least one entry. ### Example ```json "windows": { "layerFolders": [ "C:\\Layers\\layer1", "C:\\Layers\\layer2" ] } ``` ## Resources You can configure a container's resource limits via the OPTIONAL `resources` field of the Windows configuration. ### Memory `memory` is an OPTIONAL configuration for the container's memory usage. The following parameters can be specified: * **`limit`** *(uint64, OPTIONAL)* - sets limit of memory usage in bytes. #### Example ```json "windows": { "resources": { "memory": { "limit": 2097152 } } } ``` ### CPU `cpu` is an OPTIONAL configuration for the container's CPU usage. The following parameters can be specified: * **`count`** *(uint64, OPTIONAL)* - specifies the number of CPUs available to the container. * **`shares`** *(uint16, OPTIONAL)* - specifies the relative weight to other containers with CPU shares. * **`maximum`** *(uint16, OPTIONAL)* - specifies the portion of processor cycles that this container can use as a percentage times 100. #### Example ```json "windows": { "resources": { "cpu": { "maximum": 5000 } } } ``` ### Storage `storage` is an OPTIONAL configuration for the container's storage usage. The following parameters can be specified: * **`iops`** *(uint64, OPTIONAL)* - specifies the maximum IO operations per second for the system drive of the container. * **`bps`** *(uint64, OPTIONAL)* - specifies the maximum bytes per second for the system drive of the container. * **`sandboxSize`** *(uint64, OPTIONAL)* - specifies the minimum size of the system drive in bytes. #### Example ```json "windows": { "resources": { "storage": { "iops": 50 } } } ``` ## Network You can configure a container's networking options via the OPTIONAL `network` field of the Windows configuration. The following parameters can be specified: * **`endpointList`** *(array of strings, OPTIONAL)* - list of HNS (Host Network Service) endpoints that the container should connect to. * **`allowUnqualifiedDNSQuery`** *(bool, OPTIONAL)* - specifies if unqualified DNS name resolution is allowed. * **`DNSSearchList`** *(array of strings, OPTIONAL)* - comma separated list of DNS suffixes to use for name resolution. * **`networkSharedContainerName`** *(string, OPTIONAL)* - name (ID) of the container that we will share with the network stack. ### Example ```json "windows": { "network": { "endpointList": [ "7a010682-17e0-4455-a838-02e5d9655fe6" ], "allowUnqualifiedDNSQuery": true, "DNSSearchList": [ "a.com", "b.com" ], "networkSharedContainerName": "containerName" } } ``` ## Credential Spec You can configure a container's group Managed Service Account (gMSA) via the OPTIONAL `credentialSpec` field of the Windows configuration. The `credentialSpec` is a JSON object whose properties are implementation-defined. For more information about gMSAs, see [Active Directory Service Accounts for Windows Containers][gMSAOverview]. For more information about tooling to generate a gMSA, see [Deployment Overview][gMSATooling]. [gMSAOverview]: https://aka.ms/windowscontainers/manage-serviceaccounts [gMSATooling]: https://aka.ms/windowscontainers/credentialspec-tools ## Servicing When a container terminates, the Host Compute Service indicates if a Windows update servicing operation is pending. You can indicate that a container should be started in a mode to apply pending servicing operations via the OPTIONAL `servicing` field of the Windows configuration. ### Example ```json "windows": { "servicing": true } ``` ## IgnoreFlushesDuringBoot You can indicate that a container should be started in an a mode where disk flushes are not performed during container boot via the OPTIONAL `ignoreFlushesDuringBoot` field of the Windows configuration. ### Example ```json "windows": { "ignoreFlushesDuringBoot": true } ``` ## HyperV `hyperv` is an OPTIONAL field of the Windows configuration. If present, the container MUST be run with Hyper-V isolation. If omitted, the container MUST be run as a Windows Server container. The following parameters can be specified: * **`utilityVMPath`** *(string, OPTIONAL)* - specifies the path to the image used for the utility VM. This would be specified if using a base image which does not contain a utility VM image. If not supplied, the runtime will search the container filesystem layers from the bottom-most layer upwards, until it locates "UtilityVM", and default to that path. ### Example ```json "windows": { "hyperv": { "utilityVMPath": "C:\\path\\to\\utilityvm" } } ``` runtime-spec-1.0.1/config.md000066400000000000000000000746551317561611500157420ustar00rootroot00000000000000# Configuration This configuration file contains metadata necessary to implement [standard operations](runtime.md#operations) against the container. This includes the process to run, environment variables to inject, sandboxing features to use, etc. The canonical schema is defined in this document, but there is a JSON Schema in [`schema/config-schema.json`](schema/config-schema.json) and Go bindings in [`specs-go/config.go`](specs-go/config.go). [Platform](spec.md#platforms)-specific configuration schema are defined in the [platform-specific documents](#platform-specific-configuration) linked below. For properties that are only defined for some [platforms](spec.md#platforms), the Go property has a `platform` tag listing those protocols (e.g. `platform:"linux,solaris"`). Below is a detailed description of each field defined in the configuration format and valid values are specified. Platform-specific fields are identified as such. For all platform-specific configuration values, the scope defined below in the [Platform-specific configuration](#platform-specific-configuration) section applies. ## Specification version * **`ociVersion`** (string, REQUIRED) MUST be in [SemVer v2.0.0][semver-v2.0.0] format and specifies the version of the Open Container Initiative Runtime Specification with which the bundle complies. The Open Container Initiative 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. ### Example ```json "ociVersion": "0.1.0" ``` ## Root **`root`** (object, OPTIONAL) specifies the container's root filesystem. On Windows, for Windows Server Containers, this field is REQUIRED. For [Hyper-V Containers](config-windows.md#hyperv), this field MUST NOT be set. On all other platforms, this field is REQUIRED. * **`path`** (string, REQUIRED) Specifies the path to the root filesystem for the container. * On Windows, `path` MUST be a [volume GUID path][naming-a-volume]. * On POSIX platforms, `path` is either an absolute path or a relative path to the bundle. For example, 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`. The value SHOULD be the conventional `rootfs`. A directory MUST exist at the path declared by the field. * **`readonly`** (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container, defaults to false. * On Windows, this field MUST be omitted or false. ### Example (POSIX platforms) ```json "root": { "path": "rootfs", "readonly": true } ``` ### Example (Windows) ```json "root": { "path": "\\\\?\\Volume{ec84d99e-3f02-11e7-ac6c-00155d7682cf}\\" } ``` ## Mounts **`mounts`** (array of objects, OPTIONAL) specifies additional mounts beyond [`root`](#root). The runtime MUST mount entries in the listed order. 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. * **`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(1M)][zonecfg.1m]. * **`source`** (string, OPTIONAL) A device name, but can also be a directory name or a dummy. Path values are either absolute or relative to the bundle. * Windows: a local directory on the filesystem of the container host. UNC paths and mapped drives are not supported. * Solaris: corresponds to "special" of the fs resource in [zonecfg(1M)][zonecfg.1m]. * **`options`** (array of strings, OPTIONAL) Mount options of the filesystem to be used. * 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]. * Windows: runtimes MUST support `ro`, mounting the filesystem read-only when `ro` is given. ### Example (Windows) ```json "mounts": [ { "destination": "C:\\folder-inside-container", "source": "C:\\folder-on-host", "options": ["ro"] } ] ``` ### POSIX-platform Mounts For POSIX platforms the `mounts` structure has the following fields: * **`type`** (string, OPTIONAL) The type of the filesystem to be mounted. * Linux: filesystem types supported by the kernel as listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660"). * Solaris: corresponds to "type" of the fs resource in [zonecfg(1M)][zonecfg.1m]. ### Example (Linux) ```json "mounts": [ { "destination": "/tmp", "type": "tmpfs", "source": "tmpfs", "options": ["nosuid","strictatime","mode=755","size=65536k"] }, { "destination": "/data", "type": "bind", "source": "/volumes/testing", "options": ["rbind","rw"] } ] ``` ### Example (Solaris) ```json "mounts": [ { "destination": "/opt/local", "type": "lofs", "source": "/usr/local", "options": ["ro","nodevices"] }, { "destination": "/opt/sfw", "type": "lofs", "source": "/opt/sfw" } ] ``` ## Process **`process`** (object, OPTIONAL) specifies the container process. This property is REQUIRED when [`start`](runtime.md#start) is called. * **`terminal`** (bool, OPTIONAL) specifies whether a terminal is attached to the process, defaults to false. As an example, if set to true on Linux a pseudoterminal pair is allocated for the process and the pseudoterminal slave is duplicated on the process's [standard streams][stdin.3]. * **`consoleSize`** (object, OPTIONAL) specifies the console size in characters of the terminal. Runtimes MUST ignore `consoleSize` if `terminal` is `false` or unset. * **`height`** (uint, REQUIRED) * **`width`** (uint, REQUIRED) * **`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) with the same semantics as [IEEE Std 1003.1-2008's `environ`][ieee-1003.1-2008-xbd-c8.1]. * **`args`** (array of strings, REQUIRED) with similar semantics to [IEEE Std 1003.1-2008 `execvp`'s *argv*][ieee-1003.1-2008-functions-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*. ### POSIX process For systems that support POSIX rlimits (for example Linux and Solaris), the `process` object supports the following process-specific properties: * **`rlimits`** (array of objects, OPTIONAL) allows setting resource limits for the process. Each entry has the following structure: * **`type`** (string, REQUIRED) the platform resource being limited. * Linux: valid values are defined in the [`getrlimit(2)`][getrlimit.2] man page, such as `RLIMIT_MSGQUEUE`. * Solaris: valid values are defined in the [`getrlimit(3)`][getrlimit.3] man page, such as `RLIMIT_CORE`. The runtime MUST [generate an error](runtime.md#errors) for any values which cannot be mapped to a relevant kernel interface. For each entry in `rlimits`, a [`getrlimit(3)`][getrlimit.3] on `type` MUST succeed. For the following properties, `rlim` refers to the status returned by the `getrlimit(3)` call. * **`soft`** (uint64, REQUIRED) the value of the limit enforced for the corresponding resource. `rlim.rlim_cur` MUST match the configured value. * **`hard`** (uint64, REQUIRED) the ceiling for the soft limit that could be set by an unprivileged process. `rlim.rlim_max` MUST match the configured value. Only a privileged process (e.g. one with the `CAP_SYS_RESOURCE` capability) can raise a hard limit. If `rlimits` contains duplicated entries with same `type`, the runtime MUST [generate an error](runtime.md#errors). ### Linux Process For Linux-based systems, the `process` object supports the following process-specific properties. * **`apparmorProfile`** (string, OPTIONAL) specifies the name of the AppArmor profile for the process. For more information about AppArmor, see [AppArmor documentation][apparmor]. * **`capabilities`** (object, OPTIONAL) is an object containing arrays that specifies the sets of capabilities for the process. Valid values are defined in the [capabilities(7)][capabilities.7] man page, such as `CAP_CHOWN`. Any value which cannot be mapped to a relevant kernel interface MUST cause an error. `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. * **`inheritable`** (array of strings, OPTIONAL) the `inheritable` field is an array of inheritable capabilities that are kept for the process. * **`permitted`** (array of strings, OPTIONAL) the `permitted` field is an array of permitted capabilities that are kept for the process. * **`ambient`** (array of strings, OPTIONAL) the `ambient` field is an array of ambient capabilities that are kept for the process. * **`noNewPrivileges`** (bool, OPTIONAL) setting `noNewPrivileges` to true prevents the process from gaining additional privileges. As an example, the [`no_new_privs`][no-new-privs] article in the kernel documentation has information on how this is achieved using a `prctl` system call on Linux. * **`oomScoreAdj`** *(int, OPTIONAL)* adjusts the oom-killer score in `[pid]/oom_score_adj` for the process's `[pid]` in a [proc pseudo-filesystem][proc_2]. If `oomScoreAdj` is set, the runtime MUST set `oom_score_adj` to the given value. If `oomScoreAdj` is not set, the runtime MUST NOT change the value of `oom_score_adj`. This is a per-process setting, where as [`disableOOMKiller`](config-linux.md#memory) 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_2]. * **`selinuxLabel`** (string, OPTIONAL) specifies the SELinux label for the process. For more information about SELinux, see [SELinux documentation][selinux]. ### User The user for the process is a platform-specific structure that allows specific control over which user the process runs as. #### POSIX-platform User For POSIX platforms the `user` structure has the following fields: * **`uid`** (int, REQUIRED) specifies the user ID in the [container namespace](glossary.md#container-namespace). * **`gid`** (int, REQUIRED) specifies the group ID in the [container namespace](glossary.md#container-namespace). * **`additionalGids`** (array of ints, OPTIONAL) specifies additional group IDs in the [container namespace](glossary.md#container-namespace) to be added to the process. _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)_ ### Example (Linux) ```json "process": { "terminal": true, "consoleSize": { "height": 25, "width": 80 }, "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" ], "apparmorProfile": "acme_secure_profile", "selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675", "noNewPrivileges": true, "capabilities": { "bounding": [ "CAP_AUDIT_WRITE", "CAP_KILL", "CAP_NET_BIND_SERVICE" ], "permitted": [ "CAP_AUDIT_WRITE", "CAP_KILL", "CAP_NET_BIND_SERVICE" ], "inheritable": [ "CAP_AUDIT_WRITE", "CAP_KILL", "CAP_NET_BIND_SERVICE" ], "effective": [ "CAP_AUDIT_WRITE", "CAP_KILL" ], "ambient": [ "CAP_NET_BIND_SERVICE" ] }, "rlimits": [ { "type": "RLIMIT_NOFILE", "hard": 1024, "soft": 1024 } ] } ``` ### Example (Solaris) ```json "process": { "terminal": true, "consoleSize": { "height": 25, "width": 80 }, "user": { "uid": 1, "gid": 1, "additionalGids": [2, 8] }, "env": [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", "TERM=xterm" ], "cwd": "/root", "args": [ "/usr/bin/bash" ] } ``` #### Windows User For Windows based systems the user structure has the following fields: * **`username`** (string, OPTIONAL) specifies the user name for the process. ### Example (Windows) ```json "process": { "terminal": true, "user": { "username": "containeradministrator" }, "env": [ "VARIABLE=1" ], "cwd": "c:\\foo", "args": [ "someapp.exe", ] } ``` ## 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](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](glossary.md#runtime-namespace) [UTS namespace][uts-namespace.7]. ### Example ```json "hostname": "mrsdalloway" ``` ## Platform-specific configuration * **`linux`** (object, OPTIONAL) [Linux-specific configuration](config-linux.md). This MAY be set if the target platform of this spec is `linux`. * **`windows`** (object, OPTIONAL) [Windows-specific configuration](config-windows.md). This MUST be set if the target platform of this spec is `windows`. * **`solaris`** (object, OPTIONAL) [Solaris-specific configuration](config-solaris.md). This MAY be set if the target platform of this spec is `solaris`. ### Example (Linux) ```json { "linux": { "namespaces": [ { "type": "pid" } ] } } ``` ## POSIX-platform Hooks For POSIX platforms, the configuration structure supports `hooks` for configuring custom actions related to the [lifecycle](runtime.md#lifecycle) of the container. * **`hooks`** (object, OPTIONAL) MAY contain any of the following properties: * **`prestart`** (array of objects, OPTIONAL) is an array of [pre-start hooks](#prestart). Entries in the array contain the following properties: * **`path`** (string, REQUIRED) with similar semantics to [IEEE Std 1003.1-2008 `execv`'s *path*][ieee-1003.1-2008-functions-exec]. This specification extends the IEEE standard in that **`path`** MUST be absolute. * **`args`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008 `execv`'s *argv*][ieee-1003.1-2008-functions-exec]. * **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008's `environ`][ieee-1003.1-2008-xbd-c8.1]. * **`timeout`** (int, OPTIONAL) is the number of seconds before aborting the hook. If set, `timeout` MUST be greater than zero. * **`poststart`** (array of objects, OPTIONAL) is an array of [post-start hooks](#poststart). Entries in the array have the same schema as pre-start entries. * **`poststop`** (array of objects, OPTIONAL) is an array of [post-stop hooks](#poststop). Entries in the array have the same schema as pre-start entries. Hooks allow users to specify programs to run before or after various lifecycle events. Hooks MUST be called in the listed order. The [state](runtime.md#state) of the container MUST be passed to hooks over stdin so that they may do work appropriate to the current state of the container. ### Prestart The pre-start hooks MUST be called after the [`start`](runtime.md#start) operation is called but [before the user-specified program command is executed](runtime.md#lifecycle). On Linux, for example, they are called after the container namespaces are created, so they provide an opportunity to customize the container (e.g. the network namespace could be specified in this hook). ### Poststart The post-start hooks MUST be called [after the user-specified process is executed](runtime.md#lifecycle) but before the [`start`](runtime.md#start) operation returns. For example, this hook can notify the user that the container process is spawned. ### Poststop The post-stop hooks MUST be called [after the container is deleted](runtime.md#lifecycle) but before the [`delete`](runtime.md#delete) operation returns. Cleanup or debugging functions are examples of such a hook. ### Example ```json "hooks": { "prestart": [ { "path": "/usr/bin/fix-mounts", "args": ["fix-mounts", "arg1", "arg2"], "env": [ "key1=value1"] }, { "path": "/usr/bin/setup-network" } ], "poststart": [ { "path": "/usr/bin/notify-start", "timeout": 5 } ], "poststop": [ { "path": "/usr/sbin/cleanup.sh", "args": ["cleanup.sh", "-f"] } ] } ``` ## Annotations **`annotations`** (object, OPTIONAL) contains arbitrary metadata for the container. This information MAY be structured or unstructured. Annotations MUST be a key-value map. If there are no annotations then this property MAY either be absent or an empty map. Keys MUST be strings. Keys MUST NOT be an empty string. Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`. Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by subsequent specifications. Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown annotation key. Values MUST be strings. Values MAY be an empty string. ```json "annotations": { "com.example.gpu-cores": "2" } ``` ## Extensibility Runtimes that are reading or processing this configuration file MUST NOT generate an error if they encounter an unknown property. Instead they MUST ignore unknown properties. ## Valid values Runtimes that are reading or processing this configuration file MUST generate an error when invalid or unsupported values are encountered. Unless support for a valid value is explicitly required, runtimes MAY choose which subset of the valid values it will support. ## Configuration Schema Example Here is a full example `config.json` for reference. ```json { "ociVersion": "0.5.0-dev", "process": { "terminal": true, "user": { "uid": 1, "gid": 1, "additionalGids": [ 5, 6 ] }, "args": [ "sh" ], "env": [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", "TERM=xterm" ], "cwd": "/", "capabilities": { "bounding": [ "CAP_AUDIT_WRITE", "CAP_KILL", "CAP_NET_BIND_SERVICE" ], "permitted": [ "CAP_AUDIT_WRITE", "CAP_KILL", "CAP_NET_BIND_SERVICE" ], "inheritable": [ "CAP_AUDIT_WRITE", "CAP_KILL", "CAP_NET_BIND_SERVICE" ], "effective": [ "CAP_AUDIT_WRITE", "CAP_KILL" ], "ambient": [ "CAP_NET_BIND_SERVICE" ] }, "rlimits": [ { "type": "RLIMIT_CORE", "hard": 1024, "soft": 1024 }, { "type": "RLIMIT_NOFILE", "hard": 1024, "soft": 1024 } ], "apparmorProfile": "acme_secure_profile", "oomScoreAdj": 100, "selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675", "noNewPrivileges": true }, "root": { "path": "rootfs", "readonly": true }, "hostname": "slartibartfast", "mounts": [ { "destination": "/proc", "type": "proc", "source": "proc" }, { "destination": "/dev", "type": "tmpfs", "source": "tmpfs", "options": [ "nosuid", "strictatime", "mode=755", "size=65536k" ] }, { "destination": "/dev/pts", "type": "devpts", "source": "devpts", "options": [ "nosuid", "noexec", "newinstance", "ptmxmode=0666", "mode=0620", "gid=5" ] }, { "destination": "/dev/shm", "type": "tmpfs", "source": "shm", "options": [ "nosuid", "noexec", "nodev", "mode=1777", "size=65536k" ] }, { "destination": "/dev/mqueue", "type": "mqueue", "source": "mqueue", "options": [ "nosuid", "noexec", "nodev" ] }, { "destination": "/sys", "type": "sysfs", "source": "sysfs", "options": [ "nosuid", "noexec", "nodev" ] }, { "destination": "/sys/fs/cgroup", "type": "cgroup", "source": "cgroup", "options": [ "nosuid", "noexec", "nodev", "relatime", "ro" ] } ], "hooks": { "prestart": [ { "path": "/usr/bin/fix-mounts", "args": [ "fix-mounts", "arg1", "arg2" ], "env": [ "key1=value1" ] }, { "path": "/usr/bin/setup-network" } ], "poststart": [ { "path": "/usr/bin/notify-start", "timeout": 5 } ], "poststop": [ { "path": "/usr/sbin/cleanup.sh", "args": [ "cleanup.sh", "-f" ] } ] }, "linux": { "devices": [ { "path": "/dev/fuse", "type": "c", "major": 10, "minor": 229, "fileMode": 438, "uid": 0, "gid": 0 }, { "path": "/dev/sda", "type": "b", "major": 8, "minor": 0, "fileMode": 432, "uid": 0, "gid": 0 } ], "uidMappings": [ { "hostID": 1000, "containerID": 0, "size": 32000 } ], "gidMappings": [ { "hostID": 1000, "containerID": 0, "size": 32000 } ], "sysctl": { "net.ipv4.ip_forward": "1", "net.core.somaxconn": "256" }, "cgroupsPath": "/myRuntime/myContainer", "resources": { "network": { "classID": 1048577, "priorities": [ { "name": "eth0", "priority": 500 }, { "name": "eth1", "priority": 1000 } ] }, "pids": { "limit": 32771 }, "hugepageLimits": [ { "pageSize": "2MB", "limit": 9223372036854772000 } ], "memory": { "limit": 536870912, "reservation": 536870912, "swap": 536870912, "kernel": -1, "kernelTCP": -1, "swappiness": 0, "disableOOMKiller": false }, "cpu": { "shares": 1024, "quota": 1000000, "period": 500000, "realtimeRuntime": 950000, "realtimePeriod": 1000000, "cpus": "2-3", "mems": "0-7" }, "devices": [ { "allow": false, "access": "rwm" }, { "allow": true, "type": "c", "major": 10, "minor": 229, "access": "rw" }, { "allow": true, "type": "b", "major": 8, "minor": 0, "access": "r" } ], "blockIO": { "weight": 10, "leafWeight": 10, "weightDevice": [ { "major": 8, "minor": 0, "weight": 500, "leafWeight": 300 }, { "major": 8, "minor": 16, "weight": 500 } ], "throttleReadBpsDevice": [ { "major": 8, "minor": 0, "rate": 600 } ], "throttleWriteIOPSDevice": [ { "major": 8, "minor": 16, "rate": 300 } ] } }, "rootfsPropagation": "slave", "seccomp": { "defaultAction": "SCMP_ACT_ALLOW", "architectures": [ "SCMP_ARCH_X86", "SCMP_ARCH_X32" ], "syscalls": [ { "names": [ "getcwd", "chmod" ], "action": "SCMP_ACT_ERRNO" } ] }, "namespaces": [ { "type": "pid" }, { "type": "network" }, { "type": "ipc" }, { "type": "uts" }, { "type": "mount" }, { "type": "user" }, { "type": "cgroup" } ], "maskedPaths": [ "/proc/kcore", "/proc/latency_stats", "/proc/timer_stats", "/proc/sched_debug" ], "readonlyPaths": [ "/proc/asound", "/proc/bus", "/proc/fs", "/proc/irq", "/proc/sys", "/proc/sysrq-trigger" ], "mountLabel": "system_u:object_r:svirt_sandbox_file_t:s0:c715,c811" }, "annotations": { "com.example.key1": "value1", "com.example.key2": "value2" } } ``` [apparmor]: https://wiki.ubuntu.com/AppArmor [cgroup-v1-memory_2]: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt [selinux]:http://selinuxproject.org/page/Main_Page [no-new-privs]: https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt [proc_2]: https://www.kernel.org/doc/Documentation/filesystems/proc.txt [semver-v2.0.0]: http://semver.org/spec/v2.0.0.html [ieee-1003.1-2008-xbd-c8.1]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_01 [ieee-1003.1-2008-functions-exec]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html [naming-a-volume]: https://aka.ms/nb3hqb [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 [getrlimit.2]: http://man7.org/linux/man-pages/man2/getrlimit.2.html [getrlimit.3]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/getrlimit.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/E86824_01/html/E54764/zonecfg-1m.html runtime-spec-1.0.1/glossary.md000066400000000000000000000033511317561611500163210ustar00rootroot00000000000000# Glossary ## Bundle A [directory structure](bundle.md) that is written ahead of time, distributed, and used to seed the runtime for creating a [container](#container) and launching a process within it. ## Configuration The [`config.json`](config.md) file in a [bundle](#bundle) which defines the intended [container](#container) and container process. ## Container An environment for executing processes with configurable isolation and resource limitations. For example, namespaces, resource limits, and mounts are all part of the container environment. ## Container namespace On Linux,the [namespaces][namespaces.7] in which the [configured process](config.md#process) executes. ## JSON All configuration [JSON][] MUST be encoded in [UTF-8][]. JSON objects MUST NOT include duplicate names. The order of entries in JSON objects is not significant. ## Runtime An implementation of this specification. It reads the [configuration files](#configuration) from a [bundle](#bundle), uses that information to create a [container](#container), launches a process inside the container, and performs other [lifecycle actions](runtime.md). ## Runtime namespace On Linux, the namespaces from which new [container namespaces](#container-namespace) are [created](config-linux.md#namespaces) and from which some configured resources are accessed. [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 runtime-spec-1.0.1/implementations.md000066400000000000000000000033261317561611500176700ustar00rootroot00000000000000# 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][runc] - Reference implementation of OCI runtime * [projectatomic/bwrap-oci][bwrap-oci] - Convert the OCI spec file to a command line for [bubblewrap][bubblewrap] * [giuseppe/crun][crun] - Runtime implementation in C ## Runtime (Virtual Machine) * [hyperhq/runv][runv] - Hypervisor-based runtime for OCI * [clearcontainers/runtime][cc-runtime] - Hypervisor-based OCI runtime utilising [virtcontainers][virtcontainers] by Intel®. ## Testing & Tools * [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-runtime]: https://github.com/clearcontainers/runtime [virtcontainers]: https://github.com/containers/virtcontainers [octool]: https://github.com/kunalkushwaha/octool [oct]: https://github.com/huawei-openlab/oct [runtime-tools]: https://github.com/opencontainers/runtime-tools [bwrap-oci]: https://github.com/projectatomic/bwrap-oci [bubblewrap]: https://github.com/projectatomic/bubblewrap [crun]: https://github.com/giuseppe/crun runtime-spec-1.0.1/meeting.ics000066400000000000000000000021451317561611500162640ustar00rootroot00000000000000BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Open Containers Initiative//Developer Meeting//EN BEGIN:VTIMEZONE TZID:America/Los_Angeles LAST-MODIFIED:20050809T050000Z BEGIN:STANDARD DTSTART:20071104T020000 RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU TZOFFSETFROM:-0700 TZOFFSETTO:-0800 TZNAME:PST END:STANDARD BEGIN:DAYLIGHT DTSTART:20070311T020000 RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU TZOFFSETFROM:-0800 TZOFFSETTO:-0700 TZNAME:PDT END:DAYLIGHT END:VTIMEZONE BEGIN:VEVENT UID:tdc-meeting@opencontainers.org DTSTAMP:20170821T200000Z DTSTART;TZID=America/Los_Angeles:20170906T140000 RRULE:FREQ=MONTHLY;INTERVAL=1;BYDAY=1WE DURATION:PT1H SUMMARY:OCI TDC Meeting DESCRIPTION;ALTREP="https://github.com/opencontainers/runtime-spec# meetings":Open Containers Initiative Developer Meeting\n https://github.com/opencontainers/runtime-spec#meetings\n Web: https://www.uberconference.com/opencontainers\n Audio-only: +1 415 968 0849 (no PIN needed) LOCATION:https://www.uberconference.com/opencontainers URL:https://github.com/opencontainers/runtime-spec/blob/master/meeting.ics END:VEVENT END:VCALENDAR runtime-spec-1.0.1/principles.md000066400000000000000000000071361317561611500166330ustar00rootroot00000000000000# 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 defines: 1. configuration file formats 2. a set of standard operations 3. an execution environment. A great analogy for this is the physical shipping container used by the transportation industry. Shipping containers are a fundamental unit of delivery, they can be lifted, stacked, locked, loaded, unloaded and labelled. Irrespective of their contents, by standardizing the container itself it allowed for a consistent, more streamlined and efficient set of processes to be defined. For software Standard Containers offer similar functionality by being the fundamental, standardized, unit of delivery for a software package. ## 1. Standard operations Standard Containers define a set of STANDARD OPERATIONS. They can be created, started, and stopped using standard container tools; copied and snapshotted using standard filesystem tools; and downloaded and uploaded using standard network tools. ## 2. Content-agnostic Standard Containers are CONTENT-AGNOSTIC: all standard operations have the same effect regardless of the contents. They are started 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 Standard Containers are INFRASTRUCTURE-AGNOSTIC: they can be run in any OCI supported infrastructure. For example, a standard container can be bundled on a laptop, uploaded to cloud storage, downloaded, run and snapshotted by a build server at a fiber hotel in Virginia, uploaded to 10 staging servers in a home-made private cloud cluster, then sent to 30 production instances across 3 public cloud regions. ## 4. Designed for automation Standard Containers are DESIGNED FOR AUTOMATION: because they offer the same standard operations regardless of content and infrastructure, Standard Containers, 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 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 Standard Containers make INDUSTRIAL-GRADE DELIVERY of software a reality. Leveraging all of the properties listed above, Standard Containers are enabling large and small enterprises to streamline and automate their software delivery pipelines. Whether it is in-house devOps flows, or external customer-based software delivery mechanisms, Standard Containers are changing the way the community thinks about software packaging and delivery. runtime-spec-1.0.1/project.md000066400000000000000000000006771317561611500161340ustar00rootroot00000000000000# Project docs ## Release Process * Increment version in [`specs-go/version.go`](specs-go/version.go) * `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][releases] for the version. Attach the produced docs. [releases]: https://github.com/opencontainers/runtime-spec/releases runtime-spec-1.0.1/runtime-linux.md000066400000000000000000000020001317561611500172640ustar00rootroot00000000000000# Linux Runtime ## 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][socket-activated-containers]. Some of the file descriptors MAY be redirected to `/dev/null` even though they are open. ## Dev symbolic links While creating the container (step 2 in the [lifecycle](runtime.md#lifecycle)), runtimes MUST create the following symlinks if the source file exists after processing [`mounts`](config.md#mounts): | Source | Destination | | --------------- | ----------- | | /proc/self/fd | /dev/fd | | /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 runtime-spec-1.0.1/runtime.md000066400000000000000000000215301317561611500161400ustar00rootroot00000000000000# Runtime and Lifecycle ## Scope of a Container The entity using a runtime to create a container MUST be able to use the operations defined in this specification against that same container. Whether other entities using the same, or other, instance of the runtime can see that container is out of scope of this specification. ## State The state of a container includes the following properties: * **`ociVersion`** (string, REQUIRED) is the OCI specification version used when creating the container. * **`id`** (string, REQUIRED) is the container's ID. This MUST be unique across all containers on this host. There is no requirement that it be unique across hosts. * **`status`** (string, REQUIRED) is the runtime state of the container. The value MAY be one of: * `creating`: the container is being created (step 2 in the [lifecycle](#lifecycle)) * `created`: the runtime has finished the [create operation](#create) (after step 2 in the [lifecycle](#lifecycle)), and the container process has neither exited nor executed the user-specified program * `running`: the container process has executed the user-specified program but has not exited (after step 5 in the [lifecycle](#lifecycle)) * `stopped`: the container process has exited (step 7 in the [lifecycle](#lifecycle)) Additional values MAY be defined by the runtime, however, they MUST be used to represent new runtime states not defined above. * **`pid`** (int, REQUIRED when `status` is `created` or `running` on Linux, OPTIONAL on other platforms) is the ID of the container process, as seen by the host. * **`bundle`** (string, REQUIRED) is the absolute path to the container's bundle directory. This is provided so that consumers can find the container's configuration and root filesystem on the host. * **`annotations`** (map, OPTIONAL) contains the list of annotations associated with the container. If no annotations were provided then this property MAY either be absent or an empty map. The state MAY include additional properties. When serialized in JSON, the format MUST adhere to the following pattern: ```json { "ociVersion": "0.2.0", "id": "oci-container1", "status": "running", "pid": 4422, "bundle": "/containers/redis", "annotations": { "myKey": "myValue" } } ``` See [Query State](#query-state) for information on retrieving the state of a container. ## Lifecycle The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist. 1. OCI compliant runtime's [`create`](runtime.md#create) command is invoked with a reference to the location of the bundle and a unique identifier. 2. The container's runtime environment MUST be created according to the configuration in [`config.json`](config.md). If the runtime is unable to create the environment specified in the [`config.json`](config.md), it MUST [generate an error](#errors). While the resources requested in the [`config.json`](config.md) MUST be created, the user-specified program (from [`process`](config.md#process)) MUST NOT be run at this time. Any updates to [`config.json`](config.md) after this step MUST NOT affect the container. 3. Runtime's [`start`](runtime.md#start) command is invoked with the unique identifier of the container. 4. The [prestart hooks](config.md#prestart) MUST be invoked by the runtime. If any prestart hook fails, the runtime MUST [generate an error](#errors), stop the container, and continue the lifecycle at step 9. 5. The runtime MUST run the user-specified program, as specified by [`process`](config.md#process). 6. The [poststart hooks](config.md#poststart) MUST be invoked by the runtime. If any poststart hook fails, the runtime MUST [log a warning](#warnings), but the remaining hooks and lifecycle continue as if the hook had succeeded. 7. The container process exits. This MAY happen due to erroring out, exiting, crashing or the runtime's [`kill`](runtime.md#kill) operation being invoked. 8. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container. 9. The container MUST be destroyed by undoing the steps performed during create phase (step 2). 10. The [poststop hooks](config.md#poststop) MUST be invoked by the runtime. If any poststop hook fails, the runtime MUST [log a warning](#warnings), but the remaining hooks and lifecycle continue as if the hook had succeeded. ## Errors In cases where the specified operation generates an error, this specification does not mandate how, or even if, that error is returned or exposed to the user of an implementation. Unless otherwise stated, generating an error MUST leave the state of the environment as if the operation were never attempted - modulo any possible trivial ancillary changes such as logging. ## Warnings In cases where the specified operation logs a warning, this specification does not mandate how, or even if, that warning is returned or exposed to the user of an implementation. Unless otherwise stated, logging a warning does not change the flow of the operation; it MUST continue as if the warning had not been logged. ## Operations Unless otherwise stated, runtimes MUST support the following operations. Note: these operations are not specifying any command-line APIs, and the parameters are inputs for general operations. ### Query State `state ` This operation MUST [generate an error](#errors) if it is not provided the ID of a container. Attempting to query a container that does not exist MUST [generate an error](#errors). This operation MUST return the state of a container as specified in the [State](#state) section. ### Create `create ` This operation MUST [generate an error](#errors) if it is not provided a path to the bundle and the container ID to associate with the container. If the ID provided is not unique across all containers within the scope of the runtime, or is not valid in any other way, the implementation MUST [generate an error](#errors) and a new container MUST NOT be created. This operation MUST create a new container. All of the properties configured in [`config.json`](config.md) except for [`process`](config.md#process) MUST be applied. [`process.args`](config.md#process) MUST NOT be applied until triggered by the [`start`](#start) operation. The remaining `process` properties MAY be applied by this operation. If the runtime cannot apply a property as specified in the [configuration](config.md), it MUST [generate an error](#errors) and a new container MUST NOT be created. The runtime MAY validate `config.json` against this spec, either generically or with respect to the local system capabilities, before creating the container ([step 2](#lifecycle)). Runtime callers who are interested in pre-create validation can run [bundle-validation tools](implementations.md#testing--tools) before invoking the create operation. Any changes made to the [`config.json`](config.md) file after this operation will not have an effect on the container. ### Start `start ` This operation MUST [generate an error](#errors) if it is not provided the container ID. Attempting to `start` a container that is not [`created`](#state) MUST have no effect on the container and MUST [generate an error](#errors). This operation MUST run the user-specified program as specified by [`process`](config.md#process). This operation MUST generate an error if `process` was not set. ### Kill `kill ` This operation MUST [generate an error](#errors) if it is not provided the container ID. Attempting to send a signal to a container that is neither [`created` nor `running`](#state) MUST have no effect on the container and MUST [generate an error](#errors). This operation MUST send the specified signal to the container process. ### Delete `delete ` This operation MUST [generate an error](#errors) if it is not provided the container ID. Attempting to `delete` a container that is not [`stopped`](#state) MUST have no effect on the container and MUST [generate an error](#errors). Deleting a container MUST delete the resources that were created during the `create` step. Note that resources associated with the container, but not created by this container, MUST NOT be deleted. Once a container is deleted its ID MAY be used by a subsequent container. ## Hooks Many of the operations specified in this specification have "hooks" that allow for additional actions to be taken before or after each operation. See [runtime configuration for hooks](./config.md#hooks) for more information. runtime-spec-1.0.1/schema/000077500000000000000000000000001317561611500153725ustar00rootroot00000000000000runtime-spec-1.0.1/schema/Makefile000066400000000000000000000024211317561611500170310ustar00rootroot00000000000000GOOD_TESTS = $(wildcard test/good/*.json) BAD_TESTS = $(wildcard test/bad/*.json) default: validate help: @echo "Usage: make [target]" @echo @echo " * 'fmt' - format the json with indentation" @echo " * 'help' - show this help information" @echo " * 'validate' - build the validation tool" fmt: find . -name '*.json' -exec bash -c 'jq --indent 4 -M . {} > xx && mv xx {} || echo "skipping invalid {}"' \; .PHONY: validate validate: validate.go go get -d ./... go build ./validate.go test: validate $(TESTS) for TYPE in $$(ls test); \ do \ echo "testing $${TYPE}"; \ for FILE in $$(ls "test/$${TYPE}/good"); \ do \ echo " testing test/$${TYPE}/good/$${FILE}"; \ if ./validate "$${TYPE}-schema.json" "test/$${TYPE}/good/$${FILE}" ; \ then \ echo " received expected validation success" ; \ else \ echo " received unexpected validation failure" ; \ exit 1; \ fi \ done; \ for FILE in $$(ls "test/$${TYPE}/bad"); \ do \ echo " testing test/$${TYPE}/bad/$${FILE}"; \ if ./validate "$${TYPE}-schema.json" "test/$${TYPE}/good/$${FILE}" ; \ then \ echo " received unexpected validation success" ; \ exit 1; \ else \ echo " received expected validation failure" ; \ fi \ done; \ done clean: rm -f validate runtime-spec-1.0.1/schema/README.md000066400000000000000000000026711317561611500166570ustar00rootroot00000000000000# JSON schema ## Overview This directory contains the [JSON Schema](http://json-schema.org/) for validating JSON covered by this specification. The layout of the files is as follows: * [config-schema.json](config-schema.json) - the primary entrypoint for the [configuration](../config.md) schema * [config-linux.json](config-linux.json) - the [Linux-specific configuration sub-structure](../config-linux.md) * [config-solaris.json](config-solaris.json) - the [Solaris-specific configuration sub-structure](../config-solaris.md) * [config-windows.json](config-windows.json) - the [Windows-specific configuration sub-structure](../config-windows.md) * [state-schema.json](state-schema.json) - the primary entrypoint for the [state JSON](../runtime.md#state) schema * [defs.json](defs.json) - definitions for general types * [defs-linux.json](defs-linux.json) - definitions for Linux-specific types * [validate.go](validate.go) - validation utility source code ## Utility There is also included a simple utility for facilitating validation. To build it: ```bash export GOPATH=`mktemp -d` go get -d ./... go build ./validate.go rm -rf $GOPATH ``` Or you can just use make command to create the utility: ```bash make validate ``` Then use it like: ```bash ./validate config-schema.json /config.json ``` Or like: ```bash ./validate https://raw.githubusercontent.com/opencontainers/runtime-spec/v1.0.0/schema/schema.json /config.json ``` runtime-spec-1.0.1/schema/config-linux.json000066400000000000000000000333141317561611500206730ustar00rootroot00000000000000{ "linux": { "description": "Linux platform-specific configurations", "id": "https://opencontainers.org/schema/bundle/linux", "type": "object", "properties": { "devices": { "id": "https://opencontainers.org/schema/bundle/linux/devices", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/Device" } }, "uidMappings": { "id": "https://opencontainers.org/schema/bundle/linux/uidMappings", "type": "array", "items": { "$ref": "defs.json#/definitions/IDMapping" } }, "gidMappings": { "id": "https://opencontainers.org/schema/bundle/linux/gidMappings", "type": "array", "items": { "$ref": "defs.json#/definitions/IDMapping" } }, "namespaces": { "id": "https://opencontainers.org/schema/bundle/linux/namespaces", "type": "array", "items": { "anyOf": [ { "$ref": "defs-linux.json#/definitions/NamespaceReference" } ] } }, "resources": { "id": "https://opencontainers.org/schema/bundle/linux/resources", "type": "object", "properties": { "devices": { "id": "https://opencontainers.org/schema/bundle/linux/resources/devices", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/DeviceCgroup" } }, "pids": { "id": "https://opencontainers.org/schema/bundle/linux/resources/pids", "type": "object", "properties": { "limit": { "id": "https://opencontainers.org/schema/bundle/linux/resources/pids/limit", "$ref": "defs.json#/definitions/int64" } }, "required": [ "limit" ] }, "blockIO": { "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO", "type": "object", "properties": { "weight": { "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/weight", "$ref": "defs-linux.json#/definitions/weight" }, "leafWeight": { "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/leafWeight", "$ref": "defs-linux.json#/definitions/weight" }, "throttleReadBpsDevice": { "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/throttleReadBpsDevice", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/blockIODeviceThrottle" } }, "throttleWriteBpsDevice": { "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/throttleWriteBpsDevice", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/blockIODeviceThrottle" } }, "throttleReadIOPSDevice": { "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/throttleReadIOPSDevice", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/blockIODeviceThrottle" } }, "throttleWriteIOPSDevice": { "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/throttleWriteIOPSDevice", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/blockIODeviceThrottle" } }, "weightDevice": { "id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/weightDevice", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/blockIODeviceWeight" } } } }, "cpu": { "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu", "type": "object", "properties": { "cpus": { "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/cpus", "type": "string" }, "mems": { "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/mems", "type": "string" }, "period": { "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/period", "$ref": "defs.json#/definitions/uint64" }, "quota": { "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/quota", "$ref": "defs.json#/definitions/int64" }, "realtimePeriod": { "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/realtimePeriod", "$ref": "defs.json#/definitions/uint64" }, "realtimeRuntime": { "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/realtimeRuntime", "$ref": "defs.json#/definitions/int64" }, "shares": { "id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/shares", "$ref": "defs.json#/definitions/uint64" } } }, "hugepageLimits": { "id": "https://opencontainers.org/schema/bundle/linux/resources/hugepageLimits", "type": "array", "items": { "type": "object", "properties": { "pageSize": { "type": "string" }, "limit": { "$ref": "defs.json#/definitions/uint64" } }, "required": [ "pageSize", "limit" ] } }, "memory": { "id": "https://opencontainers.org/schema/bundle/linux/resources/memory", "type": "object", "properties": { "kernel": { "id": "https://opencontainers.org/schema/bundle/linux/resources/memory/kernel", "$ref": "defs.json#/definitions/int64" }, "kernelTCP": { "id": "https://opencontainers.org/schema/bundle/linux/resources/memory/kernelTCP", "$ref": "defs.json#/definitions/int64" }, "limit": { "id": "https://opencontainers.org/schema/bundle/linux/resources/memory/limit", "$ref": "defs.json#/definitions/int64" }, "reservation": { "id": "https://opencontainers.org/schema/bundle/linux/resources/memory/reservation", "$ref": "defs.json#/definitions/int64" }, "swap": { "id": "https://opencontainers.org/schema/bundle/linux/resources/memory/swap", "$ref": "defs.json#/definitions/int64" }, "swappiness": { "id": "https://opencontainers.org/schema/bundle/linux/resources/memory/swappiness", "$ref": "defs.json#/definitions/uint64" }, "disableOOMKiller": { "id": "https://opencontainers.org/schema/bundle/linux/resources/memory/disableOOMKiller", "type": "boolean" } } }, "network": { "id": "https://opencontainers.org/schema/bundle/linux/resources/network", "type": "object", "properties": { "classID": { "id": "https://opencontainers.org/schema/bundle/linux/resources/network/classId", "$ref": "defs.json#/definitions/uint32" }, "priorities": { "id": "https://opencontainers.org/schema/bundle/linux/resources/network/priorities", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/NetworkInterfacePriority" } } } } } }, "cgroupsPath": { "id": "https://opencontainers.org/schema/bundle/linux/cgroupsPath", "type": "string" }, "rootfsPropagation": { "id": "https://opencontainers.org/schema/bundle/linux/rootfsPropagation", "$ref": "defs-linux.json#/definitions/RootfsPropagation" }, "seccomp": { "id": "https://opencontainers.org/schema/bundle/linux/seccomp", "type": "object", "properties": { "defaultAction": { "id": "https://opencontainers.org/schema/bundle/linux/seccomp/defaultAction", "type": "string" }, "architectures": { "id": "https://opencontainers.org/schema/bundle/linux/seccomp/architectures", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/SeccompArch" } }, "syscalls": { "id": "https://opencontainers.org/schema/bundle/linux/seccomp/syscalls", "type": "array", "items": { "$ref": "defs-linux.json#/definitions/Syscall" } } }, "required": [ "defaultAction" ] }, "sysctl": { "id": "https://opencontainers.org/schema/bundle/linux/sysctl", "$ref": "defs.json#/definitions/mapStringString" }, "maskedPaths": { "id": "https://opencontainers.org/schema/bundle/linux/maskedPaths", "$ref": "defs.json#/definitions/ArrayOfStrings" }, "readonlyPaths": { "id": "https://opencontainers.org/schema/bundle/linux/readonlyPaths", "$ref": "defs.json#/definitions/ArrayOfStrings" }, "mountLabel": { "id": "https://opencontainers.org/schema/bundle/linux/mountLabel", "type": "string" }, "intelRdt": { "id": "https://opencontainers.org/schema/bundle/linux/intelRdt", "type": "object", "properties": { "l3CacheSchema": { "id": "https://opencontainers.org/schema/bundle/linux/intelRdt/l3CacheSchema", "type": "string" } } } } } } runtime-spec-1.0.1/schema/config-schema.json000066400000000000000000000213311317561611500207700ustar00rootroot00000000000000{ "description": "Open Container Initiative Runtime Specification Container Configuration Schema", "$schema": "http://json-schema.org/draft-04/schema#", "id": "https://opencontainers.org/schema/bundle", "type": "object", "properties": { "ociVersion": { "id": "https://opencontainers.org/schema/bundle/ociVersion", "$ref": "defs.json#/definitions/ociVersion" }, "hooks": { "id": "https://opencontainers.org/schema/bundle/hooks", "type": "object", "properties": { "prestart": { "$ref": "defs.json#/definitions/ArrayOfHooks" }, "poststart": { "$ref": "defs.json#/definitions/ArrayOfHooks" }, "poststop": { "$ref": "defs.json#/definitions/ArrayOfHooks" } } }, "annotations": { "$ref": "defs.json#/definitions/annotations" }, "hostname": { "id": "https://opencontainers.org/schema/bundle/hostname", "type": "string" }, "mounts": { "id": "https://opencontainers.org/schema/bundle/mounts", "type": "array", "items": { "$ref": "defs.json#/definitions/Mount" } }, "root": { "description": "Configures the container's root filesystem.", "id": "https://opencontainers.org/schema/bundle/root", "type": "object", "required": [ "path" ], "properties": { "path": { "id": "https://opencontainers.org/schema/bundle/root/path", "$ref": "defs.json#/definitions/FilePath" }, "readonly": { "id": "https://opencontainers.org/schema/bundle/root/readonly", "type": "boolean" } } }, "process": { "id": "https://opencontainers.org/schema/bundle/process", "type": "object", "required": [ "cwd", "args" ], "properties": { "args": { "id": "https://opencontainers.org/schema/bundle/process/args", "$ref": "defs.json#/definitions/ArrayOfStrings" }, "consoleSize": { "id": "https://opencontainers.org/schema/bundle/process/consoleSize", "type": "object", "required": [ "height", "width" ], "properties": { "height": { "id": "https://opencontainers.org/schema/bundle/process/consoleSize/height", "$ref": "defs.json#/definitions/uint64" }, "width": { "id": "https://opencontainers.org/schema/bundle/process/consoleSize/width", "$ref": "defs.json#/definitions/uint64" } } }, "cwd": { "id": "https://opencontainers.org/schema/bundle/process/cwd", "type": "string" }, "env": { "id": "https://opencontainers.org/schema/bundle/process/env", "$ref": "defs.json#/definitions/Env" }, "terminal": { "id": "https://opencontainers.org/schema/bundle/process/terminal", "type": "boolean" }, "user": { "id": "https://opencontainers.org/schema/bundle/process/user", "type": "object", "properties": { "uid": { "id": "https://opencontainers.org/schema/bundle/process/user/uid", "$ref": "defs.json#/definitions/UID" }, "gid": { "id": "https://opencontainers.org/schema/bundle/process/user/gid", "$ref": "defs.json#/definitions/GID" }, "additionalGids": { "id": "https://opencontainers.org/schema/bundle/process/user/additionalGids", "$ref": "defs.json#/definitions/ArrayOfGIDs" }, "username": { "id": "https://opencontainers.org/schema/bundle/process/user/username", "type": "string" } } }, "capabilities": { "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities", "type": "object", "properties": { "bounding": { "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/bounding", "$ref": "defs.json#/definitions/ArrayOfStrings" }, "permitted": { "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/permitted", "$ref": "defs.json#/definitions/ArrayOfStrings" }, "effective": { "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/effective", "$ref": "defs.json#/definitions/ArrayOfStrings" }, "inheritable": { "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/inheritable", "$ref": "defs.json#/definitions/ArrayOfStrings" }, "ambient": { "id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/ambient", "$ref": "defs.json#/definitions/ArrayOfStrings" } } }, "apparmorProfile": { "id": "https://opencontainers.org/schema/bundle/process/linux/apparmorProfile", "type": "string" }, "oomScoreAdj": { "id": "https://opencontainers.org/schema/bundle/process/linux/oomScoreAdj", "type": "integer" }, "selinuxLabel": { "id": "https://opencontainers.org/schema/bundle/process/linux/selinuxLabel", "type": "string" }, "noNewPrivileges": { "id": "https://opencontainers.org/schema/bundle/process/linux/noNewPrivileges", "type": "boolean" }, "rlimits": { "id": "https://opencontainers.org/schema/bundle/linux/rlimits", "type": "array", "items": { "id": "https://opencontainers.org/schema/bundle/linux/rlimits/0", "type": "object", "required": [ "type", "soft", "hard" ], "properties": { "hard": { "id": "https://opencontainers.org/schema/bundle/linux/rlimits/0/hard", "$ref": "defs.json#/definitions/uint64" }, "soft": { "id": "https://opencontainers.org/schema/bundle/linux/rlimits/0/soft", "$ref": "defs.json#/definitions/uint64" }, "type": { "id": "https://opencontainers.org/schema/bundle/linux/rlimits/0/type", "type": "string", "pattern": "^RLIMIT_[A-Z]+$" } } } } } }, "linux": { "$ref": "config-linux.json#/linux" }, "solaris": { "$ref": "config-solaris.json#/solaris" }, "windows": { "$ref": "config-windows.json#/windows" } }, "required": [ "ociVersion" ] } runtime-spec-1.0.1/schema/config-solaris.json000066400000000000000000000053651317561611500212150ustar00rootroot00000000000000{ "solaris": { "description": "Solaris platform-specific configurations", "id": "https://opencontainers.org/schema/bundle/solaris", "type": "object", "properties": { "milestone": { "id": "https://opencontainers.org/schema/bundle/solaris/milestone", "type": "string" }, "limitpriv": { "id": "https://opencontainers.org/schema/bundle/solaris/limitpriv", "type": "string" }, "maxShmMemory": { "id": "https://opencontainers.org/schema/bundle/solaris/maxShmMemory", "type": "string" }, "cappedCPU": { "id": "https://opencontainers.org/schema/bundle/solaris/cappedCPU", "type": "object", "properties": { "ncpus": { "id": "https://opencontainers.org/schema/bundle/solaris/cappedCPU/ncpus", "type": "string" } } }, "cappedMemory": { "id": "https://opencontainers.org/schema/bundle/solaris/cappedMemory", "type": "object", "properties": { "physical": { "id": "https://opencontainers.org/schema/bundle/solaris/cappedMemory/physical", "type": "string" }, "swap": { "id": "https://opencontainers.org/schema/bundle/solaris/cappedMemory/swap", "type": "string" } } }, "anet": { "id": "https://opencontainers.org/schema/bundle/solaris/anet", "type": "array", "items": { "type": "object", "properties": { "linkname": { "type": "string" }, "lowerLink": { "type": "string" }, "allowedAddress": { "type": "string" }, "configureAllowedAddress": { "type": "string" }, "defrouter": { "type": "string" }, "macAddress": { "type": "string" }, "linkProtection": { "type": "string" } } } } } } } runtime-spec-1.0.1/schema/config-windows.json000066400000000000000000000124651317561611500212320ustar00rootroot00000000000000{ "windows": { "description": "Windows platform-specific configurations", "id": "https://opencontainers.org/schema/bundle/windows", "type": "object", "properties": { "layerFolders": { "id": "https://opencontainers.org/schema/bundle/windows/layerFolders", "type": "array", "items": { "$ref": "defs.json#/definitions/FilePath" }, "minItems": 1 }, "resources": { "id": "https://opencontainers.org/schema/bundle/windows/resources", "type": "object", "properties": { "memory": { "id": "https://opencontainers.org/schema/bundle/windows/resources/memory", "type": "object", "properties": { "limit": { "id": "https://opencontainers.org/schema/bundle/windows/resources/memory/limit", "$ref": "defs.json#/definitions/uint64" } } }, "cpu": { "id": "https://opencontainers.org/schema/bundle/windows/resources/cpu", "type": "object", "properties": { "count": { "id": "https://opencontainers.org/schema/bundle/windows/resources/cpu/count", "$ref": "defs.json#/definitions/uint64" }, "shares": { "id": "https://opencontainers.org/schema/bundle/windows/resources/cpu/shares", "$ref": "defs.json#/definitions/uint16" }, "maximum": { "id": "https://opencontainers.org/schema/bundle/windows/resources/cpu/maximum", "$ref": "defs.json#/definitions/uint16" } } }, "storage": { "id": "https://opencontainers.org/schema/bundle/windows/resources/storage", "type": "object", "properties": { "iops": { "id": "https://opencontainers.org/schema/bundle/windows/resources/storage/iops", "$ref": "defs.json#/definitions/uint64" }, "bps": { "id": "https://opencontainers.org/schema/bundle/windows/resources/storage/bps", "$ref": "defs.json#/definitions/uint64" }, "sandboxSize": { "id": "https://opencontainers.org/schema/bundle/windows/resources/storage/sandboxSize", "$ref": "defs.json#/definitions/uint64" } } } } }, "network": { "id": "https://opencontainers.org/schema/bundle/windows/network", "type": "object", "properties": { "endpointList": { "id": "https://opencontainers.org/schema/bundle/windows/network/endpointList", "$ref": "defs.json#/definitions/ArrayOfStrings" }, "allowUnqualifiedDNSQuery": { "id": "https://opencontainers.org/schema/bundle/windows/network/allowUnqualifiedDNSQuery", "type": "boolean" }, "DNSSearchList": { "id": "https://opencontainers.org/schema/bundle/windows/network/DNSSearchList", "$ref": "defs.json#/definitions/ArrayOfStrings" }, "networkSharedContainerName": { "id": "https://opencontainers.org/schema/bundle/windows/network/networkSharedContainerName", "type": "string" } } }, "credentialSpec": { "id": "https://opencontainers.org/schema/bundle/windows/credentialSpec", "type": "object" }, "servicing": { "id": "https://opencontainers.org/schema/bundle/windows/servicing", "type": "boolean" }, "ignoreFlushesDuringBoot": { "id": "https://opencontainers.org/schema/bundle/windows/ignoreFlushesDuringBoot", "type": "boolean" }, "hyperv": { "id": "https://opencontainers.org/schema/bundle/windows/hyperv", "type": "object", "properties": { "utilityVMPath": { "id": "https://opencontainers.org/schema/bundle/windows/hyperv/utilityVMPath", "type": "string" } } } }, "required": [ "layerFolders" ] } } runtime-spec-1.0.1/schema/defs-linux.json000066400000000000000000000166761317561611500203630ustar00rootroot00000000000000{ "definitions": { "RootfsPropagation": { "type": "string", "enum": [ "private", "shared", "slave", "unbindable" ] }, "SeccompArch": { "type": "string", "enum": [ "SCMP_ARCH_X86", "SCMP_ARCH_X86_64", "SCMP_ARCH_X32", "SCMP_ARCH_ARM", "SCMP_ARCH_AARCH64", "SCMP_ARCH_MIPS", "SCMP_ARCH_MIPS64", "SCMP_ARCH_MIPS64N32", "SCMP_ARCH_MIPSEL", "SCMP_ARCH_MIPSEL64", "SCMP_ARCH_MIPSEL64N32", "SCMP_ARCH_PPC", "SCMP_ARCH_PPC64", "SCMP_ARCH_PPC64LE", "SCMP_ARCH_S390", "SCMP_ARCH_S390X", "SCMP_ARCH_PARISC", "SCMP_ARCH_PARISC64" ] }, "SeccompAction": { "type": "string", "enum": [ "SCMP_ACT_KILL", "SCMP_ACT_TRAP", "SCMP_ACT_ERRNO", "SCMP_ACT_TRACE", "SCMP_ACT_ALLOW" ] }, "SeccompOperators": { "type": "string", "enum": [ "SCMP_CMP_NE", "SCMP_CMP_LT", "SCMP_CMP_LE", "SCMP_CMP_EQ", "SCMP_CMP_GE", "SCMP_CMP_GT", "SCMP_CMP_MASKED_EQ" ] }, "SyscallArg": { "type": "object", "properties": { "index": { "$ref": "defs.json#/definitions/uint32" }, "value": { "$ref": "defs.json#/definitions/uint64" }, "valueTwo": { "$ref": "defs.json#/definitions/uint64" }, "op": { "$ref": "#/definitions/SeccompOperators" } }, "required": [ "index", "value", "op" ] }, "Syscall": { "type": "object", "properties": { "names": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "action": { "$ref": "#/definitions/SeccompAction" }, "args": { "type": "array", "items": { "$ref": "#/definitions/SyscallArg" } } }, "required": [ "names", "action" ] }, "Major": { "description": "major device number", "$ref": "defs.json#/definitions/int64" }, "Minor": { "description": "minor device number", "$ref": "defs.json#/definitions/int64" }, "FileMode": { "description": "File permissions mode (typically an octal value)", "type": "integer", "minimum": 0, "maximum": 512 }, "FileType": { "description": "Type of a block or special character device", "type": "string", "pattern": "^[cbup]$" }, "Device": { "type": "object", "required": [ "type", "path" ], "properties": { "type": { "$ref": "#/definitions/FileType" }, "path": { "$ref": "defs.json#/definitions/FilePath" }, "fileMode": { "$ref": "#/definitions/FileMode" }, "major": { "$ref": "#/definitions/Major" }, "minor": { "$ref": "#/definitions/Minor" }, "uid": { "$ref": "defs.json#/definitions/UID" }, "gid": { "$ref": "defs.json#/definitions/GID" } } }, "weight": { "type": "integer" }, "blockIODevice": { "type": "object", "properties": { "major": { "$ref": "#/definitions/Major" }, "minor": { "$ref": "#/definitions/Minor" } }, "required": [ "major", "minor" ] }, "blockIODeviceWeight": { "type": "object", "allOf": [ { "$ref": "#/definitions/blockIODevice" }, { "type": "object", "properties": { "weight": { "$ref": "#/definitions/weight" }, "leafWeight": { "$ref": "#/definitions/weight" } } } ] }, "blockIODeviceThrottle": { "allOf": [ { "$ref": "#/definitions/blockIODevice" }, { "type": "object", "properties": { "rate": { "$ref": "defs.json#/definitions/uint64" } } } ] }, "DeviceCgroup": { "type": "object", "properties": { "allow": { "type": "boolean" }, "type": { "type": "string" }, "major": { "$ref": "#/definitions/Major" }, "minor": { "$ref": "#/definitions/Minor" }, "access": { "type": "string" } }, "required": [ "allow" ] }, "NetworkInterfacePriority": { "type": "object", "properties": { "name": { "type": "string" }, "priority": { "$ref": "defs.json#/definitions/uint32" } }, "required": [ "name", "priority" ] }, "NamespaceType": { "type": "string", "enum": [ "mount", "pid", "network", "uts", "ipc", "user", "cgroup" ] }, "NamespaceReference": { "type": "object", "properties": { "type": { "$ref": "#/definitions/NamespaceType" }, "path": { "$ref": "defs.json#/definitions/FilePath" } }, "required": [ "type" ] } } } runtime-spec-1.0.1/schema/defs.json000066400000000000000000000100161317561611500172040ustar00rootroot00000000000000{ "description": "Definitions used throughout the Open Container Initiative Runtime Specification", "definitions": { "int8": { "type": "integer", "minimum": -128, "maximum": 127 }, "int16": { "type": "integer", "minimum": -32768, "maximum": 32767 }, "int32": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "int64": { "type": "integer", "minimum": -9223372036854776000, "maximum": 9223372036854776000 }, "uint8": { "type": "integer", "minimum": 0, "maximum": 255 }, "uint16": { "type": "integer", "minimum": 0, "maximum": 65535 }, "uint32": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "uint64": { "type": "integer", "minimum": 0, "maximum": 18446744073709552000 }, "percent": { "type": "integer", "minimum": 0, "maximum": 100 }, "mapStringString": { "type": "object", "patternProperties": { ".{1,}": { "type": "string" } } }, "UID": { "$ref": "#/definitions/uint32" }, "GID": { "$ref": "#/definitions/uint32" }, "ArrayOfGIDs": { "type": "array", "items": { "$ref": "#/definitions/GID" } }, "ArrayOfStrings": { "type": "array", "items": { "type": "string" } }, "FilePath": { "type": "string" }, "Env": { "$ref": "#/definitions/ArrayOfStrings" }, "Hook": { "type": "object", "properties": { "path": { "$ref": "#/definitions/FilePath" }, "args": { "$ref": "#/definitions/ArrayOfStrings" }, "env": { "$ref": "#/definitions/Env" }, "timeout": { "type": "integer", "minimum": 1 } }, "required": [ "path" ] }, "ArrayOfHooks": { "type": "array", "items": { "$ref": "#/definitions/Hook" } }, "IDMapping": { "type": "object", "properties": { "hostID": { "$ref": "#/definitions/uint32" }, "containerID": { "$ref": "#/definitions/uint32" }, "size": { "$ref": "#/definitions/uint32" } }, "required": [ "hostID", "containerID", "size" ] }, "Mount": { "type": "object", "properties": { "source": { "$ref": "#/definitions/FilePath" }, "destination": { "$ref": "#/definitions/FilePath" }, "options": { "$ref": "#/definitions/ArrayOfStrings" }, "type": { "type": "string" } }, "required": [ "destination" ] }, "ociVersion": { "description": "The version of Open Container Initiative Runtime Specification that the document complies with", "type": "string" }, "annotations": { "$ref": "#/definitions/mapStringString" } } } runtime-spec-1.0.1/schema/state-schema.json000066400000000000000000000024631317561611500206500ustar00rootroot00000000000000{ "description": "Open Container Runtime State Schema", "$schema": "http://json-schema.org/draft-04/schema#", "id": "https://opencontainers.org/schema/state", "type": "object", "properties": { "ociVersion": { "id": "https://opencontainers.org/schema/runtime/state/ociVersion", "$ref": "defs.json#/definitions/ociVersion" }, "id": { "id": "https://opencontainers.org/schema/runtime/state/id", "description": "the container's ID", "type": "string" }, "status": { "id": "https://opencontainers.org/schema/runtime/state/status", "type": "string", "enum": [ "creating", "created", "running", "stopped" ] }, "pid": { "id": "https://opencontainers.org/schema/runtime/state/pid", "type": "integer", "minimum": 0 }, "bundle": { "id": "https://opencontainers.org/schema/runtime/state/bundle", "type": "string" }, "annotations": { "$ref": "defs.json#/definitions/annotations" } }, "required": [ "ociVersion", "id", "status", "bundle" ] } runtime-spec-1.0.1/schema/test/000077500000000000000000000000001317561611500163515ustar00rootroot00000000000000runtime-spec-1.0.1/schema/test/config/000077500000000000000000000000001317561611500176165ustar00rootroot00000000000000runtime-spec-1.0.1/schema/test/config/bad/000077500000000000000000000000001317561611500203445ustar00rootroot00000000000000runtime-spec-1.0.1/schema/test/config/bad/invalid-json.json000066400000000000000000000000031317561611500236250ustar00rootroot00000000000000{] runtime-spec-1.0.1/schema/test/config/good/000077500000000000000000000000001317561611500205465ustar00rootroot00000000000000runtime-spec-1.0.1/schema/test/config/good/minimal-for-start.json000066400000000000000000000003551317561611500250110ustar00rootroot00000000000000{ "ociVersion": "1.0.0", "root": { "path": "rootfs" }, "process": { "cwd": "/", "args": [ "sh" ], "user": { "uid": 0, "gid": 0 } } } runtime-spec-1.0.1/schema/test/config/good/minimal.json000066400000000000000000000001141317561611500230630ustar00rootroot00000000000000{ "ociVersion": "1.0.0", "root": { "path": "rootfs" } } runtime-spec-1.0.1/schema/test/config/good/spec-example.json000066400000000000000000000223251317561611500240300ustar00rootroot00000000000000{ "ociVersion": "0.5.0-dev", "process": { "terminal": true, "user": { "uid": 1, "gid": 1, "additionalGids": [ 5, 6 ] }, "args": [ "sh" ], "env": [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", "TERM=xterm" ], "cwd": "/", "capabilities": { "bounding": [ "CAP_AUDIT_WRITE", "CAP_KILL", "CAP_NET_BIND_SERVICE" ], "permitted": [ "CAP_AUDIT_WRITE", "CAP_KILL", "CAP_NET_BIND_SERVICE" ], "inheritable": [ "CAP_AUDIT_WRITE", "CAP_KILL", "CAP_NET_BIND_SERVICE" ], "effective": [ "CAP_AUDIT_WRITE", "CAP_KILL" ], "ambient": [ "CAP_NET_BIND_SERVICE" ] }, "rlimits": [ { "type": "RLIMIT_CORE", "hard": 1024, "soft": 1024 }, { "type": "RLIMIT_NOFILE", "hard": 1024, "soft": 1024 } ], "apparmorProfile": "acme_secure_profile", "selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675", "noNewPrivileges": true }, "root": { "path": "rootfs", "readonly": true }, "hostname": "slartibartfast", "mounts": [ { "destination": "/proc", "type": "proc", "source": "proc" }, { "destination": "/dev", "type": "tmpfs", "source": "tmpfs", "options": [ "nosuid", "strictatime", "mode=755", "size=65536k" ] }, { "destination": "/dev/pts", "type": "devpts", "source": "devpts", "options": [ "nosuid", "noexec", "newinstance", "ptmxmode=0666", "mode=0620", "gid=5" ] }, { "destination": "/dev/shm", "type": "tmpfs", "source": "shm", "options": [ "nosuid", "noexec", "nodev", "mode=1777", "size=65536k" ] }, { "destination": "/dev/mqueue", "type": "mqueue", "source": "mqueue", "options": [ "nosuid", "noexec", "nodev" ] }, { "destination": "/sys", "type": "sysfs", "source": "sysfs", "options": [ "nosuid", "noexec", "nodev" ] }, { "destination": "/sys/fs/cgroup", "type": "cgroup", "source": "cgroup", "options": [ "nosuid", "noexec", "nodev", "relatime", "ro" ] } ], "hooks": { "prestart": [ { "path": "/usr/bin/fix-mounts", "args": [ "fix-mounts", "arg1", "arg2" ], "env": [ "key1=value1" ] }, { "path": "/usr/bin/setup-network" } ], "poststart": [ { "path": "/usr/bin/notify-start", "timeout": 5 } ], "poststop": [ { "path": "/usr/sbin/cleanup.sh", "args": [ "cleanup.sh", "-f" ] } ] }, "linux": { "devices": [ { "path": "/dev/fuse", "type": "c", "major": 10, "minor": 229, "fileMode": 438, "uid": 0, "gid": 0 }, { "path": "/dev/sda", "type": "b", "major": 8, "minor": 0, "fileMode": 432, "uid": 0, "gid": 0 } ], "uidMappings": [ { "hostID": 1000, "containerID": 0, "size": 32000 } ], "gidMappings": [ { "hostID": 1000, "containerID": 0, "size": 32000 } ], "sysctl": { "net.ipv4.ip_forward": "1", "net.core.somaxconn": "256" }, "cgroupsPath": "/myRuntime/myContainer", "resources": { "network": { "classID": 1048577, "priorities": [ { "name": "eth0", "priority": 500 }, { "name": "eth1", "priority": 1000 } ] }, "pids": { "limit": 32771 }, "hugepageLimits": [ { "pageSize": "2MB", "limit": 9223372036854772000 } ], "oomScoreAdj": 100, "memory": { "limit": 536870912, "reservation": 536870912, "swap": 536870912, "kernel": -1, "kernelTCP": -1, "swappiness": 0, "disableOOMKiller": false }, "cpu": { "shares": 1024, "quota": 1000000, "period": 500000, "realtimeRuntime": 950000, "realtimePeriod": 1000000, "cpus": "2-3", "mems": "0-7" }, "devices": [ { "allow": false, "access": "rwm" }, { "allow": true, "type": "c", "major": 10, "minor": 229, "access": "rw" }, { "allow": true, "type": "b", "major": 8, "minor": 0, "access": "r" } ], "blockIO": { "weight": 10, "leafWeight": 10, "weightDevice": [ { "major": 8, "minor": 0, "weight": 500, "leafWeight": 300 }, { "major": 8, "minor": 16, "weight": 500 } ], "throttleReadBpsDevice": [ { "major": 8, "minor": 0, "rate": 600 } ], "throttleWriteIOPSDevice": [ { "major": 8, "minor": 16, "rate": 300 } ] } }, "rootfsPropagation": "slave", "seccomp": { "defaultAction": "SCMP_ACT_ALLOW", "architectures": [ "SCMP_ARCH_X86", "SCMP_ARCH_X32" ], "syscalls": [ { "names": [ "getcwd", "chmod" ], "action": "SCMP_ACT_ERRNO" } ] }, "namespaces": [ { "type": "pid" }, { "type": "network" }, { "type": "ipc" }, { "type": "uts" }, { "type": "mount" }, { "type": "user" }, { "type": "cgroup" } ], "maskedPaths": [ "/proc/kcore", "/proc/latency_stats", "/proc/timer_stats", "/proc/sched_debug" ], "readonlyPaths": [ "/proc/asound", "/proc/bus", "/proc/fs", "/proc/irq", "/proc/sys", "/proc/sysrq-trigger" ], "mountLabel": "system_u:object_r:svirt_sandbox_file_t:s0:c715,c811" }, "annotations": { "com.example.key1": "value1", "com.example.key2": "value2" } } runtime-spec-1.0.1/schema/test/state/000077500000000000000000000000001317561611500174715ustar00rootroot00000000000000runtime-spec-1.0.1/schema/test/state/bad/000077500000000000000000000000001317561611500202175ustar00rootroot00000000000000runtime-spec-1.0.1/schema/test/state/bad/invalid-json.json000066400000000000000000000000031317561611500235000ustar00rootroot00000000000000{] runtime-spec-1.0.1/schema/test/state/good/000077500000000000000000000000001317561611500204215ustar00rootroot00000000000000runtime-spec-1.0.1/schema/test/state/good/spec-example.json000066400000000000000000000002761317561611500237040ustar00rootroot00000000000000{ "ociVersion": "0.2.0", "id": "oci-container1", "status": "running", "pid": 4422, "bundle": "/containers/redis", "annotations": { "myKey": "myValue" } } runtime-spec-1.0.1/schema/validate.go000066400000000000000000000042771317561611500175240ustar00rootroot00000000000000package main import ( "fmt" "io/ioutil" "os" "path/filepath" "strings" "github.com/xeipuuv/gojsonschema" ) const usage = `Validate is used to check document with specified schema. You can use validate in following ways: 1.specify document file as an argument validate 2.pass document content through a pipe cat | validate 3.input document content manually, ended with ctrl+d(or your self-defined EOF keys) validate [INPUT DOCUMENT CONTENT HERE] ` func main() { nargs := len(os.Args[1:]) if nargs == 0 || nargs > 2 { fmt.Printf("ERROR: invalid arguments number\n\n%s\n", usage) os.Exit(1) } if os.Args[1] == "help" || os.Args[1] == "--help" || os.Args[1] == "-h" { fmt.Printf("%s\n", usage) os.Exit(1) } schemaPath := os.Args[1] if !strings.Contains(schemaPath, "://") { var err error schemaPath, err = formatFilePath(schemaPath) if err != nil { fmt.Printf("ERROR: invalid schema-file path: %s\n", err) os.Exit(1) } schemaPath = "file://" + schemaPath } schemaLoader := gojsonschema.NewReferenceLoader(schemaPath) var documentLoader gojsonschema.JSONLoader if nargs > 1 { documentPath, err := formatFilePath(os.Args[2]) if err != nil { fmt.Printf("ERROR: invalid document-file path: %s\n", err) os.Exit(1) } documentLoader = gojsonschema.NewReferenceLoader("file://" + documentPath) } else { documentBytes, err := ioutil.ReadAll(os.Stdin) if err != nil { fmt.Println(err) os.Exit(1) } documentString := string(documentBytes) documentLoader = gojsonschema.NewStringLoader(documentString) } result, err := gojsonschema.Validate(schemaLoader, documentLoader) if err != nil { fmt.Println(err) os.Exit(1) } if result.Valid() { fmt.Printf("The document is valid\n") } else { fmt.Printf("The document is not valid. see errors :\n") for _, desc := range result.Errors() { fmt.Printf("- %s\n", desc) } os.Exit(1) } } func formatFilePath(path string) (string, error) { if _, err := os.Stat(path); err != nil { return "", err } absPath, err := filepath.Abs(path) if err != nil { return "", err } return absPath, nil } runtime-spec-1.0.1/spec.md000066400000000000000000000053071317561611500154130ustar00rootroot00000000000000# Open Container Initiative Runtime Specification The [Open Container Initiative][oci] develops specifications for standards on Operating System process and application containers. # Abstract The Open Container Initiative Runtime Specification aims to specify the configuration, execution environment, and lifecycle of a container. A container's configuration is specified as the `config.json` for the supported platforms and details the fields that enable the creation of a container. The execution environment is specified to ensure that applications running inside a container have a consistent environment between runtimes along with common actions defined for the container's lifecycle. # Platforms Platforms defined by this specification are: * `linux`: [runtime.md](runtime.md), [config.md](config.md), [config-linux.md](config-linux.md), and [runtime-linux.md](runtime-linux.md). * `solaris`: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md). * `windows`: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md). # Table of Contents - [Introduction](spec.md) - [Notational Conventions](#notational-conventions) - [Container Principles](principles.md) - [Filesystem Bundle](bundle.md) - [Runtime and Lifecycle](runtime.md) - [Linux-specific Runtime and Lifecycle](runtime-linux.md) - [Configuration](config.md) - [Linux-specific Configuration](config-linux.md) - [Solaris-specific Configuration](config-solaris.md) - [Windows-specific Configuration](config-windows.md) - [Glossary](glossary.md) # Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119][rfc2119]. The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified]. 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 runtime-spec-1.0.1/specs-go/000077500000000000000000000000001317561611500156525ustar00rootroot00000000000000runtime-spec-1.0.1/specs-go/config.go000066400000000000000000000601461317561611500174550ustar00rootroot00000000000000package specs import "os" // Spec is the base configuration for the container. type Spec struct { // Version of the Open Container Initiative Runtime Specification with which the bundle complies. Version string `json:"ociVersion"` // Process configures the container process. Process *Process `json:"process,omitempty"` // Root configures the container's root filesystem. Root *Root `json:"root,omitempty"` // Hostname configures the container's hostname. Hostname string `json:"hostname,omitempty"` // Mounts configures additional mounts (on top of Root). Mounts []Mount `json:"mounts,omitempty"` // Hooks configures callbacks for container lifecycle events. Hooks *Hooks `json:"hooks,omitempty" platform:"linux,solaris"` // Annotations contains arbitrary metadata for the container. Annotations map[string]string `json:"annotations,omitempty"` // Linux is platform-specific configuration for Linux based containers. Linux *Linux `json:"linux,omitempty" platform:"linux"` // Solaris is platform-specific configuration for Solaris based containers. Solaris *Solaris `json:"solaris,omitempty" platform:"solaris"` // Windows is platform-specific configuration for Windows based containers. Windows *Windows `json:"windows,omitempty" platform:"windows"` } // 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,omitempty"` // ConsoleSize specifies the size of the console. ConsoleSize *Box `json:"consoleSize,omitempty"` // 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,omitempty"` // Cwd is the current working directory for the process and must be // relative to the container's root. Cwd string `json:"cwd"` // Capabilities are Linux capabilities that are kept for the process. Capabilities *LinuxCapabilities `json:"capabilities,omitempty" platform:"linux"` // Rlimits specifies rlimit options to apply to the process. Rlimits []POSIXRlimit `json:"rlimits,omitempty" platform:"linux,solaris"` // NoNewPrivileges controls whether additional privileges could be gained by processes in the container. NoNewPrivileges bool `json:"noNewPrivileges,omitempty" platform:"linux"` // ApparmorProfile specifies the apparmor profile for the container. ApparmorProfile string `json:"apparmorProfile,omitempty" platform:"linux"` // Specify an oom_score_adj for the container. OOMScoreAdj *int `json:"oomScoreAdj,omitempty" platform:"linux"` // SelinuxLabel specifies the selinux context that the container process is run as. SelinuxLabel string `json:"selinuxLabel,omitempty" platform:"linux"` } // LinuxCapabilities specifies the whitelist of capabilities that are kept for a process. // http://man7.org/linux/man-pages/man7/capabilities.7.html type LinuxCapabilities struct { // Bounding is the set of capabilities checked by the kernel. Bounding []string `json:"bounding,omitempty" platform:"linux"` // Effective is the set of capabilities checked by the kernel. Effective []string `json:"effective,omitempty" platform:"linux"` // Inheritable is the capabilities preserved across execve. Inheritable []string `json:"inheritable,omitempty" platform:"linux"` // Permitted is the limiting superset for effective capabilities. Permitted []string `json:"permitted,omitempty" platform:"linux"` // Ambient is the ambient set of capabilities that are kept. Ambient []string `json:"ambient,omitempty" platform:"linux"` } // Box specifies dimensions of a rectangle. Used for specifying the size of a console. type Box struct { // Height is the vertical dimension of a box. Height uint `json:"height"` // Width is the horizontal dimension of a box. Width uint `json:"width"` } // User specifies specific user (and group) information for the container process. type User struct { // UID is the user id. UID uint32 `json:"uid" platform:"linux,solaris"` // GID is the group id. GID uint32 `json:"gid" platform:"linux,solaris"` // AdditionalGids are additional group ids set for the container's process. AdditionalGids []uint32 `json:"additionalGids,omitempty" platform:"linux,solaris"` // Username is the user name. Username string `json:"username,omitempty" platform:"windows"` } // 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,omitempty"` } // Mount specifies a mount for a container. type Mount struct { // Destination is the absolute path where the mount will be placed in the container. Destination string `json:"destination"` // Type specifies the mount kind. Type string `json:"type,omitempty" platform:"linux,solaris"` // Source specifies the source path of the mount. Source string `json:"source,omitempty"` // Options are fstab style mount options. Options []string `json:"options,omitempty"` } // 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,omitempty"` Env []string `json:"env,omitempty"` Timeout *int `json:"timeout,omitempty"` } // Hooks for container setup and teardown type Hooks struct { // Prestart is a list of hooks to be run before the container process is executed. Prestart []Hook `json:"prestart,omitempty"` // Poststart is a list of hooks to be run after the container process is started. Poststart []Hook `json:"poststart,omitempty"` // Poststop is a list of hooks to be run after the container process exits. Poststop []Hook `json:"poststop,omitempty"` } // Linux contains platform-specific configuration for Linux based containers. type Linux struct { // UIDMapping specifies user mappings for supporting user namespaces. UIDMappings []LinuxIDMapping `json:"uidMappings,omitempty"` // GIDMapping specifies group mappings for supporting user namespaces. GIDMappings []LinuxIDMapping `json:"gidMappings,omitempty"` // Sysctl are a set of key value pairs that are set for the container on start Sysctl map[string]string `json:"sysctl,omitempty"` // Resources contain cgroup information for handling resource constraints // for the container Resources *LinuxResources `json:"resources,omitempty"` // CgroupsPath specifies the path to cgroups that are created and/or joined by the container. // The path is expected to be relative to the cgroups mountpoint. // If resources are specified, the cgroups at CgroupsPath will be updated based on resources. CgroupsPath string `json:"cgroupsPath,omitempty"` // Namespaces contains the namespaces that are created and/or joined by the container Namespaces []LinuxNamespace `json:"namespaces,omitempty"` // Devices are a list of device nodes that are created for the container Devices []LinuxDevice `json:"devices,omitempty"` // Seccomp specifies the seccomp security settings for the container. Seccomp *LinuxSeccomp `json:"seccomp,omitempty"` // RootfsPropagation is the rootfs mount propagation mode for the container. RootfsPropagation string `json:"rootfsPropagation,omitempty"` // MaskedPaths masks over the provided paths inside the container. MaskedPaths []string `json:"maskedPaths,omitempty"` // ReadonlyPaths sets the provided paths as RO inside the container. ReadonlyPaths []string `json:"readonlyPaths,omitempty"` // MountLabel specifies the selinux context for the mounts in the container. MountLabel string `json:"mountLabel,omitempty"` // IntelRdt contains Intel Resource Director Technology (RDT) information // for handling resource constraints (e.g., L3 cache) for the container IntelRdt *LinuxIntelRdt `json:"intelRdt,omitempty"` } // LinuxNamespace is the configuration for a Linux namespace type LinuxNamespace struct { // Type is the type of namespace Type LinuxNamespaceType `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,omitempty"` } // LinuxNamespaceType is one of the Linux namespaces type LinuxNamespaceType string const ( // PIDNamespace for isolating process IDs PIDNamespace LinuxNamespaceType = "pid" // NetworkNamespace for isolating network devices, stacks, ports, etc NetworkNamespace = "network" // MountNamespace for isolating mount points MountNamespace = "mount" // IPCNamespace for isolating System V IPC, POSIX message queues IPCNamespace = "ipc" // UTSNamespace for isolating hostname and NIS domain name UTSNamespace = "uts" // UserNamespace for isolating user and group IDs UserNamespace = "user" // CgroupNamespace for isolating cgroup hierarchies CgroupNamespace = "cgroup" ) // LinuxIDMapping specifies UID/GID mappings type LinuxIDMapping struct { // HostID is the starting UID/GID on the host to be mapped to 'ContainerID' HostID uint32 `json:"hostID"` // ContainerID is the starting UID/GID in the container ContainerID uint32 `json:"containerID"` // Size is the number of IDs to be mapped Size uint32 `json:"size"` } // POSIXRlimit type and restrictions type POSIXRlimit struct { // Type of the rlimit to set Type string `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"` } // LinuxHugepageLimit structure corresponds to limiting kernel hugepages type LinuxHugepageLimit struct { // Pagesize is the hugepage size Pagesize string `json:"pageSize"` // Limit is the limit of "hugepagesize" hugetlb usage Limit uint64 `json:"limit"` } // LinuxInterfacePriority for network interfaces type LinuxInterfacePriority struct { // Name is the name of the network interface Name string `json:"name"` // Priority for the interface Priority uint32 `json:"priority"` } // linuxBlockIODevice holds major:minor format supported in blkio cgroup type linuxBlockIODevice struct { // Major is the device's major number. Major int64 `json:"major"` // Minor is the device's minor number. Minor int64 `json:"minor"` } // LinuxWeightDevice struct holds a `major:minor weight` pair for weightDevice type LinuxWeightDevice struct { linuxBlockIODevice // Weight is the bandwidth rate for the device. Weight *uint16 `json:"weight,omitempty"` // LeafWeight is the bandwidth rate for the device while competing with the cgroup's child cgroups, CFQ scheduler only LeafWeight *uint16 `json:"leafWeight,omitempty"` } // LinuxThrottleDevice struct holds a `major:minor rate_per_second` pair type LinuxThrottleDevice struct { linuxBlockIODevice // Rate is the IO rate limit per cgroup per device Rate uint64 `json:"rate"` } // LinuxBlockIO for Linux cgroup 'blkio' resource management type LinuxBlockIO struct { // Specifies per cgroup weight Weight *uint16 `json:"weight,omitempty"` // Specifies tasks' weight in the given cgroup while competing with the cgroup's child cgroups, CFQ scheduler only LeafWeight *uint16 `json:"leafWeight,omitempty"` // Weight per cgroup per device, can override BlkioWeight WeightDevice []LinuxWeightDevice `json:"weightDevice,omitempty"` // IO read rate limit per cgroup per device, bytes per second ThrottleReadBpsDevice []LinuxThrottleDevice `json:"throttleReadBpsDevice,omitempty"` // IO write rate limit per cgroup per device, bytes per second ThrottleWriteBpsDevice []LinuxThrottleDevice `json:"throttleWriteBpsDevice,omitempty"` // IO read rate limit per cgroup per device, IO per second ThrottleReadIOPSDevice []LinuxThrottleDevice `json:"throttleReadIOPSDevice,omitempty"` // IO write rate limit per cgroup per device, IO per second ThrottleWriteIOPSDevice []LinuxThrottleDevice `json:"throttleWriteIOPSDevice,omitempty"` } // LinuxMemory for Linux cgroup 'memory' resource management type LinuxMemory struct { // Memory limit (in bytes). Limit *int64 `json:"limit,omitempty"` // Memory reservation or soft_limit (in bytes). Reservation *int64 `json:"reservation,omitempty"` // Total memory limit (memory + swap). Swap *int64 `json:"swap,omitempty"` // Kernel memory limit (in bytes). Kernel *int64 `json:"kernel,omitempty"` // Kernel memory limit for tcp (in bytes) KernelTCP *int64 `json:"kernelTCP,omitempty"` // How aggressive the kernel will swap memory pages. Swappiness *uint64 `json:"swappiness,omitempty"` // DisableOOMKiller disables the OOM killer for out of memory conditions DisableOOMKiller *bool `json:"disableOOMKiller,omitempty"` } // LinuxCPU for Linux cgroup 'cpu' resource management type LinuxCPU struct { // CPU shares (relative weight (ratio) vs. other cgroups with cpu shares). Shares *uint64 `json:"shares,omitempty"` // CPU hardcap limit (in usecs). Allowed cpu time in a given period. Quota *int64 `json:"quota,omitempty"` // CPU period to be used for hardcapping (in usecs). Period *uint64 `json:"period,omitempty"` // How much time realtime scheduling may use (in usecs). RealtimeRuntime *int64 `json:"realtimeRuntime,omitempty"` // CPU period to be used for realtime scheduling (in usecs). RealtimePeriod *uint64 `json:"realtimePeriod,omitempty"` // CPUs to use within the cpuset. Default is to use any CPU available. Cpus string `json:"cpus,omitempty"` // List of memory nodes in the cpuset. Default is to use any available memory node. Mems string `json:"mems,omitempty"` } // LinuxPids for Linux cgroup 'pids' resource management (Linux 4.3) type LinuxPids struct { // Maximum number of PIDs. Default is "no limit". Limit int64 `json:"limit"` } // LinuxNetwork identification and priority configuration type LinuxNetwork struct { // Set class identifier for container's network packets ClassID *uint32 `json:"classID,omitempty"` // Set priority of network traffic for container Priorities []LinuxInterfacePriority `json:"priorities,omitempty"` } // LinuxResources has container runtime resource constraints type LinuxResources struct { // Devices configures the device whitelist. Devices []LinuxDeviceCgroup `json:"devices,omitempty"` // Memory restriction configuration Memory *LinuxMemory `json:"memory,omitempty"` // CPU resource restriction configuration CPU *LinuxCPU `json:"cpu,omitempty"` // Task resource restriction configuration. Pids *LinuxPids `json:"pids,omitempty"` // BlockIO restriction configuration BlockIO *LinuxBlockIO `json:"blockIO,omitempty"` // Hugetlb limit (in bytes) HugepageLimits []LinuxHugepageLimit `json:"hugepageLimits,omitempty"` // Network restriction configuration Network *LinuxNetwork `json:"network,omitempty"` } // LinuxDevice represents the mknod information for a Linux special device file type LinuxDevice struct { // Path to the device. Path string `json:"path"` // Device type, block, char, etc. Type string `json:"type"` // Major is the device's major number. Major int64 `json:"major"` // Minor is the device's minor number. Minor int64 `json:"minor"` // FileMode permission bits for the device. FileMode *os.FileMode `json:"fileMode,omitempty"` // UID of the device. UID *uint32 `json:"uid,omitempty"` // Gid of the device. GID *uint32 `json:"gid,omitempty"` } // LinuxDeviceCgroup represents a device rule for the whitelist controller type LinuxDeviceCgroup struct { // Allow or deny Allow bool `json:"allow"` // Device type, block, char, etc. Type string `json:"type,omitempty"` // Major is the device's major number. Major *int64 `json:"major,omitempty"` // Minor is the device's minor number. Minor *int64 `json:"minor,omitempty"` // Cgroup access permissions format, rwm. Access string `json:"access,omitempty"` } // Solaris contains platform-specific configuration for Solaris application containers. type Solaris struct { // SMF FMRI which should go "online" before we start the container process. Milestone string `json:"milestone,omitempty"` // Maximum set of privileges any process in this container can obtain. LimitPriv string `json:"limitpriv,omitempty"` // The maximum amount of shared memory allowed for this container. MaxShmMemory string `json:"maxShmMemory,omitempty"` // Specification for automatic creation of network resources for this container. Anet []SolarisAnet `json:"anet,omitempty"` // Set limit on the amount of CPU time that can be used by container. CappedCPU *SolarisCappedCPU `json:"cappedCPU,omitempty"` // The physical and swap caps on the memory that can be used by this container. CappedMemory *SolarisCappedMemory `json:"cappedMemory,omitempty"` } // SolarisCappedCPU allows users to set limit on the amount of CPU time that can be used by container. type SolarisCappedCPU struct { Ncpus string `json:"ncpus,omitempty"` } // SolarisCappedMemory allows users to set the physical and swap caps on the memory that can be used by this container. type SolarisCappedMemory struct { Physical string `json:"physical,omitempty"` Swap string `json:"swap,omitempty"` } // SolarisAnet provides the specification for automatic creation of network resources for this container. type SolarisAnet struct { // Specify a name for the automatically created VNIC datalink. Linkname string `json:"linkname,omitempty"` // Specify the link over which the VNIC will be created. Lowerlink string `json:"lowerLink,omitempty"` // The set of IP addresses that the container can use. Allowedaddr string `json:"allowedAddress,omitempty"` // Specifies whether allowedAddress limitation is to be applied to the VNIC. Configallowedaddr string `json:"configureAllowedAddress,omitempty"` // The value of the optional default router. Defrouter string `json:"defrouter,omitempty"` // Enable one or more types of link protection. Linkprotection string `json:"linkProtection,omitempty"` // Set the VNIC's macAddress Macaddress string `json:"macAddress,omitempty"` } // Windows defines the runtime configuration for Windows based containers, including Hyper-V containers. type Windows struct { // LayerFolders contains a list of absolute paths to directories containing image layers. LayerFolders []string `json:"layerFolders"` // Resources contains information for handling resource constraints for the container. Resources *WindowsResources `json:"resources,omitempty"` // CredentialSpec contains a JSON object describing a group Managed Service Account (gMSA) specification. CredentialSpec interface{} `json:"credentialSpec,omitempty"` // Servicing indicates if the container is being started in a mode to apply a Windows Update servicing operation. Servicing bool `json:"servicing,omitempty"` // IgnoreFlushesDuringBoot indicates if the container is being started in a mode where disk writes are not flushed during its boot process. IgnoreFlushesDuringBoot bool `json:"ignoreFlushesDuringBoot,omitempty"` // HyperV contains information for running a container with Hyper-V isolation. HyperV *WindowsHyperV `json:"hyperv,omitempty"` // Network restriction configuration. Network *WindowsNetwork `json:"network,omitempty"` } // WindowsResources has container runtime resource constraints for containers running on Windows. type WindowsResources struct { // Memory restriction configuration. Memory *WindowsMemoryResources `json:"memory,omitempty"` // CPU resource restriction configuration. CPU *WindowsCPUResources `json:"cpu,omitempty"` // Storage restriction configuration. Storage *WindowsStorageResources `json:"storage,omitempty"` } // WindowsMemoryResources contains memory resource management settings. type WindowsMemoryResources struct { // Memory limit in bytes. Limit *uint64 `json:"limit,omitempty"` } // WindowsCPUResources contains CPU resource management settings. type WindowsCPUResources struct { // Number of CPUs available to the container. Count *uint64 `json:"count,omitempty"` // CPU shares (relative weight to other containers with cpu shares). Shares *uint16 `json:"shares,omitempty"` // Specifies the portion of processor cycles that this container can use as a percentage times 100. Maximum *uint16 `json:"maximum,omitempty"` } // WindowsStorageResources contains storage resource management settings. type WindowsStorageResources struct { // Specifies maximum Iops for the system drive. Iops *uint64 `json:"iops,omitempty"` // Specifies maximum bytes per second for the system drive. Bps *uint64 `json:"bps,omitempty"` // Sandbox size specifies the minimum size of the system drive in bytes. SandboxSize *uint64 `json:"sandboxSize,omitempty"` } // WindowsNetwork contains network settings for Windows containers. type WindowsNetwork struct { // List of HNS endpoints that the container should connect to. EndpointList []string `json:"endpointList,omitempty"` // Specifies if unqualified DNS name resolution is allowed. AllowUnqualifiedDNSQuery bool `json:"allowUnqualifiedDNSQuery,omitempty"` // Comma separated list of DNS suffixes to use for name resolution. DNSSearchList []string `json:"DNSSearchList,omitempty"` // Name (ID) of the container that we will share with the network stack. NetworkSharedContainerName string `json:"networkSharedContainerName,omitempty"` } // WindowsHyperV contains information for configuring a container to run with Hyper-V isolation. type WindowsHyperV struct { // UtilityVMPath is an optional path to the image used for the Utility VM. UtilityVMPath string `json:"utilityVMPath,omitempty"` } // LinuxSeccomp represents syscall restrictions type LinuxSeccomp struct { DefaultAction LinuxSeccompAction `json:"defaultAction"` Architectures []Arch `json:"architectures,omitempty"` Syscalls []LinuxSyscall `json:"syscalls,omitempty"` } // Arch used for additional architectures type Arch string // Additional architectures permitted to be used for system calls // By default only the native architecture of the kernel is permitted const ( ArchX86 Arch = "SCMP_ARCH_X86" ArchX86_64 Arch = "SCMP_ARCH_X86_64" ArchX32 Arch = "SCMP_ARCH_X32" ArchARM Arch = "SCMP_ARCH_ARM" ArchAARCH64 Arch = "SCMP_ARCH_AARCH64" ArchMIPS Arch = "SCMP_ARCH_MIPS" ArchMIPS64 Arch = "SCMP_ARCH_MIPS64" ArchMIPS64N32 Arch = "SCMP_ARCH_MIPS64N32" ArchMIPSEL Arch = "SCMP_ARCH_MIPSEL" ArchMIPSEL64 Arch = "SCMP_ARCH_MIPSEL64" ArchMIPSEL64N32 Arch = "SCMP_ARCH_MIPSEL64N32" ArchPPC Arch = "SCMP_ARCH_PPC" ArchPPC64 Arch = "SCMP_ARCH_PPC64" ArchPPC64LE Arch = "SCMP_ARCH_PPC64LE" ArchS390 Arch = "SCMP_ARCH_S390" ArchS390X Arch = "SCMP_ARCH_S390X" ArchPARISC Arch = "SCMP_ARCH_PARISC" ArchPARISC64 Arch = "SCMP_ARCH_PARISC64" ) // LinuxSeccompAction taken upon Seccomp rule match type LinuxSeccompAction string // Define actions for Seccomp rules const ( ActKill LinuxSeccompAction = "SCMP_ACT_KILL" ActTrap LinuxSeccompAction = "SCMP_ACT_TRAP" ActErrno LinuxSeccompAction = "SCMP_ACT_ERRNO" ActTrace LinuxSeccompAction = "SCMP_ACT_TRACE" ActAllow LinuxSeccompAction = "SCMP_ACT_ALLOW" ) // LinuxSeccompOperator used to match syscall arguments in Seccomp type LinuxSeccompOperator string // Define operators for syscall arguments in Seccomp const ( OpNotEqual LinuxSeccompOperator = "SCMP_CMP_NE" OpLessThan LinuxSeccompOperator = "SCMP_CMP_LT" OpLessEqual LinuxSeccompOperator = "SCMP_CMP_LE" OpEqualTo LinuxSeccompOperator = "SCMP_CMP_EQ" OpGreaterEqual LinuxSeccompOperator = "SCMP_CMP_GE" OpGreaterThan LinuxSeccompOperator = "SCMP_CMP_GT" OpMaskedEqual LinuxSeccompOperator = "SCMP_CMP_MASKED_EQ" ) // LinuxSeccompArg used for matching specific syscall arguments in Seccomp type LinuxSeccompArg struct { Index uint `json:"index"` Value uint64 `json:"value"` ValueTwo uint64 `json:"valueTwo,omitempty"` Op LinuxSeccompOperator `json:"op"` } // LinuxSyscall is used to match a syscall in Seccomp type LinuxSyscall struct { Names []string `json:"names"` Action LinuxSeccompAction `json:"action"` Args []LinuxSeccompArg `json:"args,omitempty"` } // LinuxIntelRdt has container runtime resource constraints // for Intel RDT/CAT which introduced in Linux 4.10 kernel type LinuxIntelRdt struct { // The schema for L3 cache id and capacity bitmask (CBM) // Format: "L3:=;=;..." L3CacheSchema string `json:"l3CacheSchema,omitempty"` } runtime-spec-1.0.1/specs-go/state.go000066400000000000000000000012011317561611500173130ustar00rootroot00000000000000package specs // State holds information about the runtime state of the container. type State struct { // Version is the version of the specification that is supported. Version string `json:"ociVersion"` // ID is the container ID ID string `json:"id"` // Status is the runtime status of the container. Status string `json:"status"` // Pid is the process ID for the container process. Pid int `json:"pid,omitempty"` // Bundle is the path to the container's bundle directory. Bundle string `json:"bundle"` // Annotations are key values associated with the container. Annotations map[string]string `json:"annotations,omitempty"` } runtime-spec-1.0.1/specs-go/version.go000066400000000000000000000010241317561611500176630ustar00rootroot00000000000000package specs import "fmt" const ( // VersionMajor is for an API incompatible changes VersionMajor = 1 // VersionMinor is for functionality in a backwards-compatible manner VersionMinor = 0 // VersionPatch is for backwards-compatible bug fixes VersionPatch = 1 // VersionDev indicates development branch. Releases will be empty string. VersionDev = "" ) // Version is the specification version that the package types support. var Version = fmt.Sprintf("%d.%d.%d%s", VersionMajor, VersionMinor, VersionPatch, VersionDev) runtime-spec-1.0.1/style.md000066400000000000000000000124171317561611500156210ustar00rootroot00000000000000# Style and conventions ## One sentence per line 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. ## Traditionally hex settings should use JSON integers, not JSON strings For example, [`"classID": 1048577`](config-linux.md#network) instead of `"classID": "0x100001"`. The config JSON isn't enough of a UI to be worth jumping through string <-> integer hoops to support an 0x… form ([source][integer-over-hex]). ## Constant names should keep redundant prefixes For example, `CAP_KILL` instead of `KILL` in [**`process.capabilities`**](config.md#process). The redundancy reduction from removing the namespacing prefix is not useful enough to be worth trimming the upstream identifier ([source][keep-prefix]). ## Optional settings should not have pointer Go types 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 For any given section that provides a notable example, it is ideal to have it denoted with [markdown headers][markdown-headers]. The level of header should be such that it is a subheader of the header it is an example of. #### Example ```markdown ## Some Topic ### Some Subheader #### Further Subheader ##### Example To use Further Subheader, ... ### Example To use Some Topic, ... ``` ### Content Where necessary, the values in the example can be empty or unset, but accommodate with comments regarding this intention. Where feasible, the content and values used in an example should convey the fullest use of the data structures concerned. Most commonly onlookers will intend to copy-and-paste a "working example". If the intention of the example is to be a fully utilized example, rather than a copy-and-paste example, perhaps add a comment as such. ```markdown ### Example ``` ```json { "foo": null, "bar": "" } ``` **vs.** ```markdown ### Example Following is a fully populated example (not necessarily for copy/paste use) ``` ```json { "foo": [ 1, 2, 3 ], "bar": "waffles", "bif": { "baz": "potatoes" } } ``` ### 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 ``` [integer-over-hex]: https://github.com/opencontainers/runtime-spec/pull/267#r48360013 [keep-prefix]: https://github.com/opencontainers/runtime-spec/pull/159#issuecomment-138728337 [no-pointer-for-boolean]: https://github.com/opencontainers/runtime-spec/pull/290#r50296396 [no-pointer-for-slices]: https://github.com/opencontainers/runtime-spec/pull/316#r50782982 [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