Commit 60068e98fd1631cc8808f524cc8c777bbaf94b5f - golang-github-opencontainers-specs

New upstream version 1.0.0 Balint Reczey 6 years ago

44 changed file(s) with 2525 addition(s) and 1476 deletion(s). Raw diff Collapse all Expand all

-0

.gitattributes less more

	0	# https://tools.ietf.org/html/rfc5545#section-3.1
	1	*.ics text eol=crlf

-0

.gitignore less more

	0	output
	1	schema/validate
	2	version.md

+20

-0

.mailmap less more

	0	Aleksa Sarai <cyphar@cyphar.com> <asarai@suse.de>
	1	Alexander Morozov <lk4d4math@gmail.com> <lk4d4@docker.com>
	2	Amit Saha <amitsaha.in@gmail.com> <amitsaha@users.noreply.github.com>
	3	Antonio Murdaca <runcom@linux.com> <runcom@redhat.com>
	4	Brandon Philips <brandon@ifup.org> <brandon.philips@coreos.com>
	5	Brandon Philips <brandon@ifup.org> <brandon@ifup.co>
	6	ChengTiesheng <chengtiesheng@huawei.com>
	7	Daniel, Dao Quang Minh <dqminh89@gmail.com>
	8	Doug Davis <dug@us.ibm.com> <duglin@users.noreply.github.com>
	9	John Howard <jhoward@microsoft.com> <John.Howard@microsoft.com>
	10	LinZhinan(Zen Lin) <linzhinan@huawei.com>
	11	Mrunal Patel <mrunalp@gmail.com> <mrunal@Mrunals-iMac.local>
	12	Mrunal Patel <mrunalp@gmail.com> <mrunal@dhcp-16-185.sjc.redhat.com>
	13	Mrunal Patel <mrunalp@gmail.com> <mrunal@me.com>
	14	Vincent Batts <vbatts@hashbangbash.com> <vbatts@hashbangbash.com>
	15	Vincent Batts <vbatts@hashbangbash.com> <vbatts@redhat.com>
	16	Vishnu Kannan <vishnuk@google.com>
	17	Vishnu Kannan <vishnuk@google.com> <vishh@users.noreply.github.com>
	18	Zefan Li <lizefan@huawei.com> <lizf1984@hotmail.com>
	19	梁辰晔 (Liang Chenye) <liangchenye@huawei.com>

-1

.travis.yml less more

15	15	install: true
16	16
17	17	script:
	18	- env \| grep TRAVIS_
18	19	- make .govet
19	20	- make .golint
20		- make .gitvalidation
	21	- echo "${TRAVIS_COMMIT_RANGE} -> ${TRAVIS_COMMIT_RANGE/.../..} (travis-ci/travis-ci#4596)"
	22	- TRAVIS_COMMIT_RANGE="${TRAVIS_COMMIT_RANGE/.../..}" make .gitvalidation
21	23	- make docs
	24	- make -C schema test

+266

-0

ChangeLog less more

0	0	OpenContainers Specifications
	1
	2	Changes with v1.0.0:
	3
	4	Breaking changes:
	5
	6	* config: Shift disableOOMKiller from linux.resources to
	7	linux.resources.memory (#896)
	8
	9	Decreased restrictions:
	10
	11	* runtime: Make the state JSON's pid optional on non-Linux platforms
	12	(#897)
	13
	14	Minor fixes and documentation:
	15
	16	* schema/defs-linux: Require Syscall.action (#885)
	17	* specs-go/config: Fix 'omiempty' -> 'omitempty' typo for
	18	LinuxSeccompArg.ValueTwo (#884)
	19	* ROAMAP: remove the pre-v1.0.0 roadmap (#890)
	20
	21	Changes with v1.0.0-rc6:
	22
	23	Breaking changes:
	24
	25	* config: Shift oomScoreAdj to process and add RFC 2119 requirements
	26	for the runtime (#781, #789, #836)
	27	* config: Forbid 'root' on Hyper-V (#820, #838).
	28	* config: process.capabilities and process.noNewPrivileges are
	29	Linux-only again (#880). This partially reverses #673, which had
	30	landed in v1.0.0-rc5.
	31	* config: Remove process.rlimits from Windows (#880). It is now
	32	POSIX-only, while in v1.0.0-rc5 it was cross-platform (because of
	33	#673). Before #673 (in v1.0.0-rc4 and earlier), it was
	34	Linux-only.
	35	* config-linux: Drop redundant 'blkio' prefix from blockIO
	36	properties (#860)
	37	* config-linux: Make memory limits int64 instead of uint64 (#876).
	38	This partially reverses #704, which had landed in v1.0.0-rc5.
	39	* config-windows: Change CPU 'percent' to 'maximum' (#777)
	40	* config-windows: Remove memory 'reservation' (#788)
	41	* config-windows: Remove 'resources.network' and add 'network' (#801)
	42
	43	Additions:
	44
	45	* config: Windows runtimes MUST support the 'ro' mount option (#868)
	46	* config-linux: Add Intel RDT/CAT Linux support (#630, #787)
	47	* config-linux: Add Markdown specification for syscalls (#706)
	48	* config-linux: Add 'unbindable' rootfsPropagation value (#770, #775)
	49	* config-windows: Add 'credentialSpec' (#814, #859)
	50	* config-windows: Add 'servicing' (#815)
	51	* config-windows: Add 'ignoreFlushesDuringBoot' (#816, #859)
	52	* config-windows: Add 'hyperv' (#818, #849, #859)
	53	* config-windows: Add 'layerFolders' (#828)
	54
	55	Removals and increased restrictions:
	56
	57	* config: Remove 'platform' (#850)
	58	* config: Require strictly-postitive 'timeout' values (#764)
	59	* config: Strengthen punt to kernel for valid capabilities strings
	60	(#766, #790)
	61	* config: Require volume GUID paths for root.path (#849)
	62	* config: Forbid setting 'readonly' true on Windows (#819)
	63	* config: Forbid setting mount 'type' entirely on Windows and forbid
	64	UNC paths and mapped drives in 'source' on Windows (#821)
	65	* config: Remove 'hooks' from Windows spec (#855, #869, #870)
	66	* config-linux: Clearly require absolute path for namespace (#720)
	67	* config-linux: RFC 2119 tightening for namespaces (#767)
	68	* config-linux: Require at least one entry in
	69	linux.seccomp.syscalls[].names (#769)
	70	* config-linux: Remove syscall.comment (#714)
	71	* config-linux: Use MUST and MAY for weight and leafWeight (#751)
	72	* config-linux: Remove explicit 'null' from device cgroup values
	73	(#804)
	74	* runtime: Remove "features the runtime chooses to support" (#732)
	75	* runtime: Drop "not supported by the base OS" loophole (#733)
	76	* runtime-linux: Condition /proc/self/fd symlinks on source
	77	existence (#736)
	78
	79	Decreased restrictions:
	80
	81	* config: Make 'process' optional (#701, #805)
	82	* config-linux: Make linux.seccomp.syscalls optional (#768)
	83	* config-linux: valueTwo is now optional in
	84	`linux.seccomp.syscalls[].args` entries (#877)
	85	* config-linux: Remove local range restrictions for blkioWeight,
	86	blkioLeafWeight, weight, leafWeight, and shares (#780)
	87	* config-linux: Explicitly allow symlinks for providing devices (#873)
	88
	89	Minor fixes and documentation:
	90
	91	* config: Remove "MAY support any valid values" sentence (#851)
	92	* config: Remove the previously-forbidden mounts[].type from the
	93	Windows spec (#854)
	94	* config: Clarify mounts[].source relative path anchor (#735)
	95	* config: Explicitly make consoleSize ignored if terminal is false or
	96	unset (#863)
	97	* config: Specify height/width units (characters) for consoleSize (#761)
	98	* config: Use "POSIX platforms" instead of "Linux and Solaris" (#838)
	99	* config-linux: Explicit namespace for interface names (#713)
	100	* config-linux: Explicitly list cgroupsPath as optional (#823)
	101	* runtime: Clarify valid container states for 'start', 'kill', and
	102	'delete' (#875)
	103	* runtime: Explicitly make process.* timing implementation-defined (#700)
	104	* specs-go/config: Remove range restrictions from Windows comments (#783)
	105	* specs-go/config: Add omitempty to LinuxSyscall.Args (#763)
	106	* specs-go/config: Use a pointer for Process.ConsoleSize (#792)
	107	* schema/README: Use v1.0.0 URL in examples to prepare for the 1.0.0
	108	release (#881)
	109	* schema/Makefile: Make 'validate' the default target (#750)
	110	* schema/Makefile: Add 'clean' target (#774)
	111	* schema: Add 'test' target to the Makefile (#785)
	112	* *: Remove unnecessary .PHONY entries (#750, #778, #802)
	113	* *: Typo fixes and polishing (#681, #708, #702, #703, #709, #711,
	114	#712, #721, #722, #723, #724, #730, #737, #738, #741, #744, #749,
	115	#753, #756, #765, #773, #776, #784, #786, #793, #794, #796, #798,
	116	#799, #800, #803, #807, #809, #811, #812, #822, #824, #826, #827,
	117	#832, #839, #840, #846, #847, #848, #852, #856, #858, #862, #865,
	118	#871, #874)
	119
	120	Changes with v1.0.0-rc5:
	121
	122	Breaking changes:
	123
	124	* config: Explicitly require `platform` (#695).
	125	* config: The platform-specific sections (`linux`, `solaris`, and
	126	`windows`) MUST NOT be set unless they match `platform.os` (#673).
	127	* config: `process.capabilities` is now an object instead of an
	128	array of strings (#675).
	129	* config-linux: No longer allow negative values for some resources,
	130	partially reversing #648 from v1.0.0-rc4 (#704).
	131	* config-linux: `linux.seccomp.syscalls` entries have `names`
	132	instead of `name` (#657).
	133	* runtime: Rename the state `bundlePath` property to `bundle`
	134	(#674).
	135
	136	Additions:
	137
	138	* config: `process.capabilities` is no longer Linux-only (#673).
	139	* config-linux: `linux.seccomp.syscalls` entries have a new
	140	`comment` property (#657).
	141	* config-linux: Add new architectures from libseccomp 2.3.2 (#705)
	142	* runtime: Add a `creating` state `status` (#507, #694).
	143
	144	Removals and increased restrictions:
	145
	146	* runtime: Document hook timing and exit code handling (#532).
	147	* schema/config-linux: Explicit `null` values are no longer
	148	compliant (#662).
	149
	150	Decreased restrictions:
	151
	152	* config: `type` and `source` properties are now optional for
	153	`mounts` entries (#699).
	154	* config: `args` property is now optional for hooks (#685).
	155	* config-linux: Runtimes no longer need to provide `/proc` and
	156	other filesystems unless they are explicitly requested in the
	157	configuration JSON (#666).
	158
	159	Minor fixes and documentation:
	160
	161	* spec: Add OCI Runtime Abstract (#691).
	162	* config: Document the Go `platform` tag (#570).
	163	* config-linux: Remove local uid/gid mapping limit and punt to the
	164	kernel (#693).
	165	* schema: Fix broken `string` and similar `$ref`s (#684).
	166	* schema: Remove `mounts` from required properties (#696).
	167	* schema: Remove `major` and `minor` from `linux.devices` entries
	168	(#688).
	169	* schema: Check for the required `type`, `hard`, and `soft` in
	170	`process.rlimits` entries (#696).
	171	* schema/validate: Gained usage documentation and fixed
	172	`schemaPath` logic when the argument did not contain `://` (#552).
	173	* *: Add anchor tags to a number of spec locations (#707).
	174	* *: Consistent link syntax (#687).
	175	* *: Minor cleanup and rewording (#697).
	176
	177	Changes with v1.0.0-rc4:
	178	Additions:
	179
	180	* config-linux: Allow negative values for some resources (#648)
	181	* config-linux: Lift no-tweaking namespace restriction (#649)
	182
	183	Removals and increased restrictions:
	184
	185	* config: Rlimit types must be unique (#607)
	186	* config: Forbid empty-string keys in 'annotations' (#645, #654)
	187	* config-linux: Require runtime errors for pre-existing devices
	188	(#647)
	189	* runtime: Only require 'pid' in the state for created/running
	190	statuses (#664)
	191	* schema: Add 'consoleSize' and update requirements (#646)
	192	* schema: Remove string pointers (#656)
	193	* schema/config-linux: Remove blockIODeviceThrottle and other
	194	pointers (#545)
	195
	196	Breaking Go changes:
	197
	198	* specs-go/config: Remove string pointers (#653)
	199	* specs-go/config: Make Spec.Hooks a pointer (#427)
	200	* specs-go/config: Convert some resources from unsigned integers
	201	to signed integers (#648)
	202
	203	Minor fixes and documentation:
	204
	205	* config: Explicitly list 'hooks' as optional and cite POSIX for
	206	'env' and 'args' (#427)
	207	* runtime: Replace "process is stopped" with "process exits"
	208	(#465)
	209	* schema/config-linux: Add missing kernelTCP (#655)
	210	* schema/validate: Allow schema identifiers to contain a URL
	211	scheme (#490)
	212	* .travis: Fix git-validation commit ranges (#216)
	213	* *: Add anchor tags to a number of spec locations (#612, #636,
	214	#637, #638, #639, #640)
	215	* *: Typo fixes and polishing (#643, #650, #652, #656, #660, #665)
	216
	217	Changes with v1.0.0-rc3:
	218	Additions:
	219
	220	* config: Add support for Windows-based containers (#565, #573)
	221	* config: Add process.consoleSize (#563)
	222	* config: Explicitly allow unknown extensions and document
	223	annotations key conventions (#510)
	224	* config: Define mounts entries for Solaris (#588)
	225
	226	Removals and increased restrictions:
	227
	228	* config: Require absolute paths for mount destinations (#609)
	229	* config-linux: Require absolute path for maskedPaths and
	230	readonlyPaths (#587)
	231	* config-linux: Only require /dev/console when process.terminal is
	232	true. Also require /dev/console to be provided by a bind mount
	233	(#518)
	234	* runtime: Require runtimes to generate errors when the container
	235	specified in config.json cannot be created (#559)
	236
	237	Breaking Go changes:
	238
	239	* specs-go/config: Aggressive namespacing (#567)
	240	* specs-go/config: Remove pointers from LinuxHugepageLimit,
	241	LinuxInterfacePriority, and LinuxPids properties (#586)
	242	* specs-go/state: Rename version to ociVersion (#633)
	243	LinuxInterfacePriority, and LinuxPids properties (#586)
	244
	245	Minor fixes and documentation:
	246
	247	* spec: Separate the spec from project scaffolding (#626)
	248	* README: Define "unspecified", "undefined", and
	249	"implementation-defined" (#575)
	250	* config: Clarify absolue and relative values for root.path (#558)
	251	* config: Clarify ociVersion covering the configuration <->
	252	runtime API (#523)
	253	* config-linux: Forbid duplicated namespaces with same `type`
	254	(#597)
	255	* glossary: Make objects explicitly unordered and forbid duplicate
	256	names (#584)
	257	* specs-go/config: Add platform tags to Rlimits and
	258	NoNewPRivileges (#564)
	259	* schema/defs-linux: Use int64 for major/minor types (#610)
	260	* Makefile: Add support for Go 1.7 (#547)
	261	* Makefile: Require Go >= 1.6 for golint (#589)
	262	* Makefile: Use a POSIX-compatible test ('==' -> '=') (#542)
	263	* implementations: Rename ocitools -> runtime-tools (#585)
	264	* *: Typo fixes and polishing (#556, #566, #568, #569, #571, #572,
	265	#574, #595, #596, #599, #600, #601, #603, #605, #608, #613, #617,
	266	#619, #621, #622, #623, #624, #625, #627, #629)
1	267
2	268	Changes with v1.0.0-rc2:
3	269	Additions:

-2

GOVERNANCE.md less more

13	13
14	14	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.
15	15	Maintainers MAY also explicitly not vote by posting ABSTAIN (which is useful to revert a previous vote).
16		Maintainers MAY post multiple times (e.g. as they revise their position based on feeback), but only their final post counts in the tally.
	16	Maintainers MAY post multiple times (e.g. as they revise their position based on feedback), but only their final post counts in the tally.
17	17	A proposed motion is adopted if two-thirds of votes cast, a quorum having voted, are in favor of the release.
18	18
19	19	Voting SHOULD remain open for a week to collect feedback from the wider community and allow the maintainers to digest the proposed motion.

39	39
40	40	## Amendments
41	41
42		The [project governance](#project-governance) rules and procedures MAY be ammended or replaced using the procedures themselves.
	42	The [project governance](#project-governance) rules and procedures MAY be amended or replaced using the procedures themselves.
43	43	The MAINTAINERS of this project governance document is the total set of MAINTAINERS from all Open Containers projects (runC, runtime-spec, and image-spec).
44	44
45	45	## Subject templates

-1

MAINTAINERS less more

0	0	Michael Crosby <michael@docker.com> (@crosbymichael)
1		Alexander Morozov <lk4d4@docker.com> (@LK4D4)
2	1	Vishnu Kannan <vishnuk@google.com> (@vishh)
3	2	Mrunal Patel <mpatel@redhat.com> (@mrunalp)
4	3	Vincent Batts <vbatts@redhat.com> (@vbatts)

-22

Makefile less more

0	0
1	1	EPOCH_TEST_COMMIT := 78e6667ae2d67aad100b28ee9580b41b7a24e667
2		OUTPUT_DIRNAME ?= output/
	2	OUTPUT_DIRNAME ?= output
3	3	DOC_FILENAME ?= oci-runtime-spec
4	4	DOCKER ?= $(shell command -v docker 2>/dev/null)
5	5	PANDOC ?= $(shell command -v pandoc 2>/dev/null)

20	20	# These docs are in an order that determines how they show up in the PDF/HTML docs.
21	21	DOC_FILES := \
22	22	version.md \
23		README.md \
24		code-of-conduct.md \
	23	spec.md \
25	24	principles.md \
26		style.md \
27		ROADMAP.md \
28		implementations.md \
29		project.md \
30	25	bundle.md \
31	26	runtime.md \
32	27	runtime-linux.md \

37	32
38	33	default: docs
39	34
40		.PHONY: docs
41	35	docs: $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html
42	36
43	37	ifeq "$(strip $(PANDOC))" ''

53	47	$(PANDOC) -f markdown_github -t html5 -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES))
54	48	endif
55	49
56		code-of-conduct.md:
57		curl -o $@ https://raw.githubusercontent.com/opencontainers/tob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md
58
59	50	version.md: ./specs-go/version.go
60	51	go run ./.tool/version-doc.go > $@
61	52
62	53	HOST_GOLANG_VERSION = $(shell go version \| cut -d ' ' -f3 \| cut -c 3-)
63	54	# this variable is used like a function. First arg is the minimum version, Second arg is the version to be checked.
64	55	ALLOWED_GO_VERSION = $(shell test '$(shell /bin/echo -e "$(1)\n$(2)" \| sort -V \| head -n1)' = '$(1)' && echo 'true')
65
66		.PHONY: test .govet .golint .gitvalidation
67	56
68	57	test: .govet .golint .gitvalidation
69	58

72	61
73	62	# `go get github.com/golang/lint/golint`
74	63	.golint:
75		ifeq ($(call ALLOWED_GO_VERSION,1.5,$(HOST_GOLANG_VERSION)),true)
	64	ifeq ($(call ALLOWED_GO_VERSION,1.6,$(HOST_GOLANG_VERSION)),true)
76	65	@which golint > /dev/null 2>/dev/null \|\| (echo "ERROR: golint not found. Consider 'make install.tools' target" && false)
77	66	golint ./...
78	67	endif

81	70	# When this is running in travis, it will only check the travis commit range
82	71	.gitvalidation:
83	72	@which git-validation > /dev/null 2>/dev/null \|\| (echo "ERROR: git-validation not found. Consider 'make install.tools' target" && false)
84		ifeq ($(TRAVIS),true)
	73	ifdef TRAVIS_COMMIT_RANGE
85	74	git-validation -q -run DCO,short-subject,dangling-whitespace
86	75	else
87	76	git-validation -v -run DCO,short-subject,dangling-whitespace -range $(EPOCH_TEST_COMMIT)..HEAD
88	77	endif
89	78
90
91		.PHONY: install.tools
92	79	install.tools: .install.golint .install.gitvalidation
93	80
94		# golint does not even build for <go1.5
	81	# golint does not even build for <go1.6
95	82	.install.golint:
96		ifeq ($(call ALLOWED_GO_VERSION,1.5,$(HOST_GOLANG_VERSION)),true)
	83	ifeq ($(call ALLOWED_GO_VERSION,1.6,$(HOST_GOLANG_VERSION)),true)
97	84	go get -u github.com/golang/lint/golint
98	85	endif
99	86
100	87	.install.gitvalidation:
101	88	go get -u github.com/vbatts/git-validation
102	89
103
104		.PHONY: clean
105	90	clean:
106	91	rm -rf $(OUTPUT_DIRNAME) *~
107		rm -f code-of-conduct.md version.md
	92	rm -f version.md
108	93

+50

-62

README.md less more

0	0	# Open Container Initiative Runtime Specification
1	1
2		The [Open Container Initiative](http://www.opencontainers.org/) develops specifications for standards on Operating System process and application containers.
	2	The [Open Container Initiative][oci] develops specifications for standards on Operating System process and application containers.
3	3
	4	The specification can be found [here](spec.md).
4	5
5		Table of Contents
	6	## Table of Contents
6	7
7		- [Introduction](README.md)
8		- [Code of Conduct](#code-of-conduct)
9		- [Container Principles](principles.md)
10		- [Style and Conventions](style.md)
11		- [Roadmap](ROADMAP.md)
12		- [Implementations](implementations.md)
13		- [project](project.md)
14		- [Filesystem Bundle](bundle.md)
15		- Runtime and Lifecycle
16		- [General Runtime and Lifecycle](runtime.md)
17		- [Linux-specific Runtime and Lifecycle](runtime-linux.md)
18		- Configuration
19		- [General Configuration](config.md)
20		- [Linux-specific Configuration](config-linux.md)
21		- [Solaris-specific Configuration](config-solaris.md)
22		- [Windows-specific Configuration](config-windows.md)
23		- [Glossary](glossary.md)
	8	Additional documentation about how this group operates:
24	9
25		In the specifications in the above table of contents, the keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997).
	10	- [Code of Conduct][code-of-conduct]
	11	- [Style and Conventions](style.md)
	12	- [Implementations](implementations.md)
	13	- [Releases](RELEASES.md)
	14	- [project](project.md)
	15	- [charter][charter]
26	16
27		The keywords "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified].
28
29		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 protocols it implements.
30		An implementation is compliant for a given CPU architecture if it satisfies all the MUST, REQUIRED, and SHALL requirements for the protocols it implements.
31
32		Protocols defined by this specification are:
33		* Linux containers: [runtime.md](runtime.md), [config.md](config.md), [config-linux.md](config-linux.md), and [runtime-linux.md](runtime-linux.md).
34		* Solaris containers: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md).
35		* Windows containers: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md).
36
37		# Use Cases
	17	## Use Cases
38	18
39	19	To provide context for users the following section gives example use cases for each part of the spec.
40	20
41		#### Application Bundle Builders
	21	### Application Bundle Builders
42	22
43	23	Application bundle builders can create a [bundle](bundle.md) directory that includes all of the files required for launching an application as a container.
44		The bundle contains an OCI [configuration file](config.md) where the builder can specify host-independent details such as [which executable to launch](config.md#process-configuration) and host-specific settings such as [mount](config.md#mounts) locations, [hook](config.md#hooks) paths, Linux [namespaces](config-linux.md#namespaces) and [cgroups](config-linux.md#control-groups).
	24	The bundle contains an OCI [configuration file](config.md) where the builder can specify host-independent details such as [which executable to launch](config.md#process) and host-specific settings such as [mount](config.md#mounts) locations, [hook](config.md#hooks) paths, Linux [namespaces](config-linux.md#namespaces) and [cgroups](config-linux.md#control-groups).
45	25	Because the configuration includes host-specific settings, application bundle directories copied between two hosts may require configuration adjustments.
46	26
47		#### Hook Developers
	27	### Hook Developers
48	28
49	29	[Hook](config.md#hooks) developers can extend the functionality of an OCI-compliant runtime by hooking into a container's lifecycle with an external application.
50	30	Example use cases include sophisticated network configuration, volume garbage collection, etc.
51	31
52		#### Runtime Developers
	32	### Runtime Developers
53	33
54		Runtime developers can build runtime implementations that run OCI-compliant bundles and container configuration, containing low-level OS and host specific details, on a particular platform.
	34	Runtime developers can build runtime implementations that run OCI-compliant bundles and container configuration, containing low-level OS and host-specific details, on a particular platform.
55	35
56		# Releases
57
58		There is a loose [Road Map](./ROADMAP.md).
59		During the `0.x` series of OCI releases we make no backwards compatibility guarantees and intend to break the schema during this series.
60
61		# Contributing
	36	## Contributing
62	37
63	38	Development happens on GitHub for the spec.
64	39	Issues are used for bugs and actionable items and longer discussions can happen on the [mailing list](#mailing-list).
65	40
66	41	The specification and code is licensed under the Apache 2.0 license found in the [LICENSE](./LICENSE) file.
67	42
68		## Code of Conduct
69
70		Participation in the OpenContainers community is governed by [OpenContainer's Code of Conduct](https://github.com/opencontainers/tob/blob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md).
71
72		## Discuss your design
	43	### Discuss your design
73	44
74	45	The project welcomes submissions, but please let everyone know what you are working on.
75	46

80	51	Typos and grammatical errors can go straight to a pull-request.
81	52	When in doubt, start on the [mailing-list](#mailing-list).
82	53
83		## Weekly Call
	54	### Weekly Call
84	55
85		The contributors and maintainers of all OCI projects have a weekly meeting Wednesdays at 2:00 PM (USA Pacific).
86		Everyone is welcome to participate via [UberConference web][UberConference] or audio-only: 415-968-0849 (no PIN needed.)
	56	The contributors and maintainers of all OCI projects have a weekly meeting on Wednesdays at:
	57
	58	* 8:00 AM (USA Pacific), during [odd weeks][iso-week].
	59	* 2:00 PM (USA Pacific), during [even weeks][iso-week].
	60
	61	There is an [iCalendar][rfc5545] format for the meetings [here](meeting.ics).
	62
	63	Everyone is welcome to participate via [UberConference web][uberconference] or audio-only: +1 415 968 0849 (no PIN needed).
87	64	An initial agenda will be posted to the [mailing list](#mailing-list) earlier in the week, and everyone is welcome to propose additional topics or suggest other agenda alterations there.
88		Minutes are posted to the [mailing list](#mailing-list) and minutes from past calls are archived to the [wiki](https://github.com/opencontainers/runtime-spec/wiki) for those who are unable to join the call.
	65	Minutes are posted to the [mailing list](#mailing-list) and minutes from past calls are archived [here][minutes], with minutes from especially old meetings (September 2015 and earlier) archived [here][runtime-wiki].
89	66
90		## Mailing List
	67	### Mailing List
91	68
92		You can subscribe and join the mailing list on [Google Groups](https://groups.google.com/a/opencontainers.org/forum/#!forum/dev).
	69	You can subscribe and join the mailing list on [Google Groups][dev-list].
93	70
94		## IRC
	71	### IRC
95	72
96	73	OCI discussion happens on #opencontainers on Freenode ([logs][irc-logs]).
97	74
98		## Git commit
	75	### Git commit
99	76
100		### Sign your work
	77	#### Sign your work
101	78
102	79	The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch.
103		The rules are pretty simple: if you can certify the below (from [developercertificate.org](http://developercertificate.org/)):
	80	The rules are pretty simple: if you can certify the below (from http://developercertificate.org):
104	81
105	82	```
106	83	Developer Certificate of Origin

149	126
150	127	You can add the sign off when creating the git commit via `git commit -s`.
151	128
152		### Commit Style
	129	#### Commit Style
153	130
154	131	Simple house-keeping for clean git history.
155		Read more on [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/) or the Discussion section of [`git-commit(1)`](http://git-scm.com/docs/git-commit).
	132	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].
156	133
157	134	1. Separate the subject from body with a blank line
158	135	2. Limit the subject line to 50 characters

161	138	5. Use the imperative mood in the subject line
162	139	6. Wrap the body at 72 characters
163	140	7. Use the body to explain what and why vs. how
164		* If there was important/useful/essential conversation or information, copy or include a reference
	141	* If there was important/useful/essential conversation or information, copy or include a reference
165	142	8. When possible, one keyword to scope the change in the subject (i.e. "README: ...", "runtime: ...")
166	143
167		[c99-unspecified]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18
168		[UberConference]: https://www.uberconference.com/opencontainers
	144
	145	[charter]: https://www.opencontainers.org/about/governance
	146	[code-of-conduct]: https://github.com/opencontainers/tob/blob/master/code-of-conduct.md
	147	[dev-list]: https://groups.google.com/a/opencontainers.org/forum/#!forum/dev
	148	[how-to-git-commit]: http://chris.beams.io/posts/git-commit
169	149	[irc-logs]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/
	150	[iso-week]: https://en.wikipedia.org/wiki/ISO_week_date#Calculating_the_week_number_of_a_given_date
	151	[minutes]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/
	152	[oci]: https://www.opencontainers.org
	153	[rfc5545]: https://tools.ietf.org/html/rfc5545
	154	[runtime-wiki]: https://github.com/opencontainers/runtime-spec/wiki
	155	[uberconference]: https://www.uberconference.com/opencontainers
	156
	157	[git-commit.1]: http://git-scm.com/docs/git-commit

-3

RELEASES.md less more

42	42
43	43	* Pre-v1.0.0 specifications SHOULD release on a monthly cadence to garner feedback.
44	44	* Major specification releases MUST release at least three release candidates spaced a minimum of one week apart.
45		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.
46		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.
47		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.
	45	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.
	46	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.
	47	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.
48	48	- Minor and patch releases SHOULD be made on an as-needed basis.
49	49
50	50	[charter]: https://www.opencontainers.org/about/governance

-55

~~ROADMAP.md~~ less more

0		# OCI Specs Roadmap
1
2		This document serves to provide a long term roadmap on our quest to a 1.0 version of the OCI container specification.
3		Its goal is to help both maintainers and contributors find meaningful tasks to focus on and create a low noise environment.
4		The items in the 1.0 roadmap can be broken down into smaller milestones that are easy to accomplish.
5		The topics below are broad and small working groups will be needed for each to define scope and requirements or if the feature is required at all for the OCI level.
6		Topics listed in the roadmap do not mean that they will be implemented or added but are areas that need discussion to see if they fit in to the goals of the OCI.
7
8		Listed topics may defer to the [project wiki](https://github.com/opencontainers/runtime-spec/wiki/RoadMap:) for collaboration.
9
10		## 1.0
11
12		### Container Definition
13
14		Define what a software container is and its attributes in a cross platform way.
15
16		Could be solved by lifecycle/ops and create/start split discussions
17
18		Owner: vishh & duglin
19
20		### Live Container Updates
21
22		Should we allow dynamic container updates to runtime options?
23
24		Proposal: make it an optional feature
25
26		Owner: hqhq (was vishh) robdolinms, bcorrie
27
28		### Version Schema
29
30		Decide on a robust versioning schema for the spec as it evolves.
31
32		Resolved but release process could evolve. Resolved for v0.2.0, expect to revisit near v1.0.0
33
34		Owner: vbatts
35
36		### Base Config Compatibility
37
38		Ensure that the base configuration format is viable for various platforms.
39
40		Systems:
41
42		* Solaris
43		* Windows
44		* Linux
45
46		Owner: robdolinms as lead coordinator
47
48		### Full Lifecycle Hooks
49
50		Ensure that we have lifecycle hooks in the correct places with full coverage over the container lifecycle.
51
52		Will probably go away with Vish's work on splitting create and start, and if we have exec.
53
54		Owner:

+11

-11

bundle.md less more

0		# Filesystem Bundle
	0	# <a name="filesystemBundle" />Filesystem Bundle
1	1
2		## Container Format
	2	## <a name="containerFormat" />Container Format
3	3
4	4	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.
5		See also [OS X application bundles](http://en.wikipedia.org/wiki/Bundle_%28OS_X%29) for a similar use of the term bundle.
	5	See also [MacOS application bundles][macos_bundle] for a similar use of the term bundle.
6	6
7	7	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.
8	8
9	9	A Standard Container bundle contains all the information needed to load and run a container.
10		This MUST include the following artifacts:
	10	This includes the following artifacts:
11	11
12		1. `config.json`: contains configuration data.
13		This REQUIRED file MUST reside in the root of the bundle directory and MUST be named `config.json`.
14		See [`config.json`](config.md) for more details.
	12	1. <a name="containerFormat01" />`config.json`: contains configuration data.
	13	This REQUIRED file MUST reside in the root of the bundle directory and MUST be named `config.json`.
	14	See [`config.json`](config.md) for more details.
15	15
16		2. A directory representing the root filesystem of the container.
17		While the name of this REQUIRED directory may be arbitrary, users should consider using a conventional name, such as `rootfs`.
18		This directory MUST be referenced from within the `config.json` file.
	16	2. <a name="containerFormat02" />container's root filesystem: the directory referenced by [`root.path`](config.md#root), if that property is set in `config.json`.
19	17
20		While these artifacts MUST all be present in a single directory on the local filesystem, that directory itself is not part of the bundle.
	18	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.
21	19	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.
	20
	21	[macos_bundle]: https://en.wikipedia.org/wiki/Bundle_%28macOS%29

+361

-306

config-linux.md less more

0		# Linux-specific Container Configuration
	0	# <a name="linuxContainerConfiguration" />Linux Container Configuration
1	1
2	2	This document describes the schema for the [Linux-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md).
3	3	The Linux container specification uses various kernel features like namespaces, cgroups, capabilities, LSM, and filesystem jails to fulfill the spec.
4	4
5		## Default Filesystems
	5	## <a name="configLinuxDefaultFilesystems" />Default Filesystems
6	6
7	7	The Linux ABI includes both syscalls and several special file paths.
8		Applications expecting a Linux environment will very likely expect these files paths to be setup correctly.
9
10		The following filesystems MUST be made available in each application's filesystem
11
12		\| Path \| Type \|
	8	Applications expecting a Linux environment will very likely expect these file paths to be set up correctly.
	9
	10	The following filesystems SHOULD be made available in each container's filesystem:
	11
	12	\| Path \| Type \|
13	13	\| -------- \| ------ \|
14		\| /proc \| [procfs](https://www.kernel.org/doc/Documentation/filesystems/proc.txt) \|
15		\| /sys \| [sysfs](https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt) \|
16		\| /dev/pts \| [devpts](https://www.kernel.org/doc/Documentation/filesystems/devpts.txt) \|
17		\| /dev/shm \| [tmpfs](https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt) \|
18
19		## Namespaces
	14	\| /proc \| [procfs][] \|
	15	\| /sys \| [sysfs][] \|
	16	\| /dev/pts \| [devpts][] \|
	17	\| /dev/shm \| [tmpfs][] \|
	18
	19	## <a name="configLinuxNamespaces" />Namespaces
20	20
21	21	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.
22	22	Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes.
23		For more information, see [the man page](http://man7.org/linux/man-pages/man7/namespaces.7.html).
	23	For more information, see the [namespaces(7)][namespaces.7_2] man page.
24	24
25	25	Namespaces are specified as an array of entries inside the `namespaces` root field.
26		The following parameters can be specified to setup namespaces:
27
28		* `type` (string, REQUIRED) - namespace type. The following namespaces types are supported:
	26	The following parameters can be specified to set up namespaces:
	27
	28	* `type` (string, REQUIRED) - namespace type. The following namespace types are supported:
29	29	* `pid` processes inside the container will only be able to see other processes inside the same container.
30	30	* `network` the container will have its own network stack.
31	31	* `mount` the container will have an isolated mount table.

34	34	* `user` the container will be able to remap user and group IDs from the host to local users and groups within the container.
35	35	* `cgroup` the container will have an isolated view of the cgroup hierarchy.
36	36
37		* `path` (string, OPTIONAL) - path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace)
38
39		If a path is specified, that particular file is used to join that type of namespace.
	37	* `path` (string, OPTIONAL) - an absolute path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace).
	38	The runtime MUST place the container process in the namespace associated with that `path`.
	39	The runtime MUST [generate an error](runtime.md#errors) if `path` is not associated with a namespace of type `type`.
	40
	41	If `path` is not specified, the runtime MUST create a new [container namespace](glossary.md#container-namespace) of type `type`.
	42
40	43	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.
41		If a new namespace is not created (because the namespace type is not listed, or because it is listed with a `path`), runtimes MUST assume that the setup for that namespace has already been done and error out if the config specifies anything else related to that namespace.
42
43		###### Example
	44	If a `namespaces` field contains duplicated namespaces with same `type`, the runtime MUST [generate an error](runtime.md#errors).
	45
	46	### Example
44	47
45	48	```json
46	49	"namespaces": [

70	73	]
71	74	```
72	75
73		## User namespace mappings
74
75		###### Example
	76	## <a name="configLinuxUserNamespaceMappings" />User namespace mappings
	77
	78	`uidMappings` (array of objects, OPTIONAL) describes the user namespace uid mappings from the host to the container.
	79	`gidMappings` (array of objects, OPTIONAL) describes the user namespace gid mappings from the host to the container.
	80
	81	Each entry has the following structure:
	82
	83	* `hostID` (uint32, REQUIRED) - is the starting uid/gid on the host to be mapped to containerID.
	84	* `containerID` (uint32, REQUIRED) - is the starting uid/gid in the container.
	85	* `size` (uint32, REQUIRED) - is the number of ids to be mapped.
	86
	87	The runtime SHOULD NOT modify the ownership of referenced filesystems to realize the mapping.
	88	Note that the number of mapping entries MAY be limited by the [kernel][user-namespaces].
	89
	90	### Example
76	91
77	92	```json
78	93	"uidMappings": [
79	94	{
80	95	"hostID": 1000,
81	96	"containerID": 0,
82		"size": 10
	97	"size": 32000
83	98	}
84	99	],
85	100	"gidMappings": [
86	101	{
87	102	"hostID": 1000,
88	103	"containerID": 0,
89		"size": 10
	104	"size": 32000
90	105	}
91	106	]
92	107	```
93	108
94		uid/gid mappings describe the user namespace mappings from the host to the container.
95		The runtime SHOULD NOT modify the ownership of referenced filesystems to realize the mapping.
96		hostID is the starting uid/gid on the host to be mapped to containerID which is the starting uid/gid in the container and size refers to the number of ids to be mapped.
97		There is a limit of 5 mappings which is the Linux kernel hard limit.
98
99		## Devices
100
101		`devices` (array, OPTIONAL) lists devices that MUST be available in the container.
102		The runtime may supply them however it likes (with [mknod][mknod.2], by bind mounting from the runtime mount namespace, etc.).
103
104		The following parameters can be specified:
	109	## <a name="configLinuxDevices" />Devices
	110
	111	`devices` (array of objects, OPTIONAL) lists devices that MUST be available in the container.
	112	The runtime MAY supply them however it likes (with [`mknod`][mknod.2], by bind mounting from the runtime mount namespace, using symlinks, etc.).
	113
	114	Each entry has the following structure:
105	115
106	116	* `type` (string, REQUIRED) - type of device: `c`, `b`, `u` or `p`.
107		More info in [mknod(1)][mknod.1].
	117	More info in [mknod(1)][mknod.1].
108	118	* `path` (string, REQUIRED) - full path to device inside container.
109		* `major, minor` (int64, REQUIRED unless `type`* is `p`)* - [major, minor numbers][devices] for the device.
	119	If a [file][] already exists at `path` that does not match the requested device, the runtime MUST generate an error.
	120	* `major, minor` (int64, REQUIRED unless `type` is `p`) - [major, minor numbers][devices] for the device.
110	121	* `fileMode` (uint32, OPTIONAL) - file mode for the device.
111		You can also control access to devices [with cgroups](#device-whitelist).
	122	You can also control access to devices [with cgroups](#device-whitelist).
112	123	* `uid` (uint32, OPTIONAL) - id of device owner.
113	124	* `gid` (uint32, OPTIONAL) - id of device group.
114	125
115		###### Example
116
117		```json
118		"devices": [
	126	The same `type`, `major` and `minor` SHOULD NOT be used for multiple devices.
	127
	128	### Example
	129
	130	```json
	131	"devices": [
119	132	{
120	133	"path": "/dev/fuse",
121	134	"type": "c",

137	150	]
138	151	```
139	152
140		###### Default Devices
	153	### <a name="configLinuxDefaultDevices" />Default Devices
141	154
142	155	In addition to any devices configured with this setting, the runtime MUST also supply:
143	156

147	160	* [`/dev/random`][random.4]
148	161	* [`/dev/urandom`][random.4]
149	162	* [`/dev/tty`][tty.4]
150		* [`/dev/console`][console.4]
	163	* [`/dev/console`][console.4] is set up if terminal is enabled in the config by bind mounting the pseudoterminal slave to /dev/console.
151	164	* [`/dev/ptmx`][pts.4].
152	165	A [bind-mount or symlink of the container's `/dev/pts/ptmx`][devpts].
153	166
154		## Control groups
	167	## <a name="configLinuxControlGroups" />Control groups
155	168
156	169	Also known as cgroups, they are used to restrict resource usage for a container and handle device access.
157	170	cgroups provide controls (through controllers) to restrict cpu, memory, IO, pids and network for the container.
158	171	For more information, see the [kernel cgroups documentation][cgroup-v1].
159	172
160		The path to the cgroups can be specified in the Spec via `cgroupsPath`.
161		`cgroupsPath` can be used to either control the cgroup hierarchy for containers or to run a new process in an existing container.
162		If `cgroupsPath` is:
163		* ... an absolute path (starting with `/`), the runtime MUST take the path to be relative to the cgroup mount point.
164		* ... a relative path (not starting with `/`), the runtime MAY interpret the path relative to a runtime-determined location in the cgroup hierarchy.
165		* ... not specified, the runtime MAY define the default cgroup path.
	173	### <a name="configLinuxCgroupsPath" />Cgroups Path
	174
	175	`cgroupsPath` (string, OPTIONAL) path to the cgroups.
	176	It can be used to either control the cgroups hierarchy for containers or to run a new process in an existing container.
	177
	178	The value of `cgroupsPath` MUST be either an absolute path or a relative path.
	179	* In the case of an absolute path (starting with `/`), the runtime MUST take the path to be relative to the cgroups mount point.
	180	* 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.
	181
	182	If the value is specified, the runtime MUST consistently attach to the same place in the cgroups hierarchy given the same value of `cgroupsPath`.
	183	If the value is not specified, the runtime MAY define the default cgroups path.
166	184	Runtimes MAY consider certain `cgroupsPath` values to be invalid, and MUST generate an error if this is the case.
167		If a `cgroupsPath` value is specified, the runtime MUST consistently attach to the same place in the cgroup hierarchy given the same value of `cgroupsPath`.
168	185
169	186	Implementations of the Spec can choose to name cgroups in any manner.
170	187	The Spec does not include naming schema for cgroups.

175	192	Do not specify `resources` unless limits have to be updated.
176	193	For example, to run a new process in an existing container without updating limits, `resources` need not be specified.
177	194
178		A runtime MUST at least use the minimum set of cgroup controllers required to fulfill the `resources` settings.
179		However, a runtime MAY attach the container process to additional cgroup controllers supported by the system.
180
181		###### Example
182
183		```json
184		"cgroupsPath": "/myRuntime/myContainer",
185		"resources": {
186		"memory": {
187		"limit": 100000,
188		"reservation": 200000
189		},
190		"devices": [
191		{
192		"allow": false,
193		"access": "rwm"
194		}
195		]
	195	Runtimes MAY attach the container process to additional cgroup controllers beyond those necessary to fulfill the `resources` settings.
	196
	197	### Example
	198
	199	```json
	200	"cgroupsPath": "/myRuntime/myContainer",
	201	"resources": {
	202	"memory": {
	203	"limit": 100000,
	204	"reservation": 200000
	205	},
	206	"devices": [
	207	{
	208	"allow": false,
	209	"access": "rwm"
	210	}
	211	]
196	212	}
197	213	```
198	214
199		#### Device whitelist
200
201		`devices` (array, OPTIONAL) configures the [device whitelist][cgroup-v1-devices].
	215	### <a name="configLinuxDeviceWhitelist" />Device whitelist
	216
	217	`devices` (array of objects, OPTIONAL) configures the [device whitelist][cgroup-v1-devices].
202	218	The runtime MUST apply entries in the listed order.
203	219
204		The following parameters can be specified:
	220	Each entry has the following structure:
205	221
206	222	* `allow` (boolean, REQUIRED) - whether the entry is allowed or denied.
207	223	* `type` (string, OPTIONAL) - type of device: `a` (all), `c` (char), or `b` (block).
208		`null` or unset values mean "all", mapping to `a`.
	224	Unset values mean "all", mapping to `a`.
209	225	* `major, minor` (int64, OPTIONAL) - [major, minor numbers][devices] for the device.
210		`null` or unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices].
	226	Unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices].
211	227	* `access` (string, OPTIONAL) - cgroup permissions for device.
212		A composition of `r` (read), `w` (write), and `m` (mknod).
213
214		###### Example
215
216		```json
217		"devices": [
	228	A composition of `r` (read), `w` (write), and `m` (mknod).
	229
	230	#### Example
	231
	232	```json
	233	"devices": [
218	234	{
219	235	"allow": false,
220	236	"access": "rwm"

236	252	]
237	253	```
238	254
239		#### Disable out-of-memory killer
240
241		`disableOOMKiller` contains a boolean (`true` or `false`) that enables or disables the Out of Memory killer for a cgroup.
242		If enabled (`false`), tasks that attempt to consume more memory than they are allowed are immediately killed by the OOM killer.
243		The OOM killer is enabled by default in every cgroup using the `memory` subsystem.
244		To disable it, specify a value of `true`.
245		For more information, see [the memory cgroup man page][cgroup-v1-memory].
246
247		* `disableOOMKiller` (bool, OPTIONAL) - enables or disables the OOM killer
248
249		###### Example
250
251		```json
252		"disableOOMKiller": false
253		```
254
255		#### Set oom_score_adj
256
257		`oomScoreAdj` sets heuristic regarding how the process is evaluated by the kernel during memory pressure.
258		For more information, see [the proc filesystem documentation section 3.1](https://www.kernel.org/doc/Documentation/filesystems/proc.txt).
259		This is a kernel/system level setting, where as `disableOOMKiller` is scoped for a memory cgroup.
260		For more information on how these two settings work together, see [the memory cgroup documentation section 10. OOM Contol][cgroup-v1-memory].
261
262		* `oomScoreAdj` (int, OPTIONAL) - adjust the oom-killer score
263
264		###### Example
265
266		```json
267		"oomScoreAdj": 100
268		```
269
270		#### Memory
271
272		`memory` represents the cgroup subsystem `memory` and it's used to set limits on the container's memory usage.
273		For more information, see [the memory cgroup man page][cgroup-v1-memory].
274
275		The following parameters can be specified to setup the controller:
276
277		* `limit` (uint64, OPTIONAL) - sets limit of memory usage in bytes
278
279		* `reservation` (uint64, OPTIONAL) - sets soft limit of memory usage in bytes
280
281		* `swap` (uint64, OPTIONAL) - sets limit of memory+Swap usage
282
283		* `kernel` (uint64, OPTIONAL) - sets hard limit for kernel memory
284
285		* `kernelTCP` (uint64, OPTIONAL) - sets hard limit in bytes for kernel TCP buffer memory
	255	### <a name="configLinuxMemory" />Memory
	256
	257	`memory` (object, OPTIONAL) represents the cgroup subsystem `memory` and it's used to set limits on the container's memory usage.
	258	For more information, see the kernel cgroups documentation about [memory][cgroup-v1-memory].
	259
	260	Values for memory specify the limit in bytes, or `-1` for unlimited memory.
	261
	262	* `limit` (int64, OPTIONAL) - sets limit of memory usage
	263	* `reservation` (int64, OPTIONAL) - sets soft limit of memory usage
	264	* `swap` (int64, OPTIONAL) - sets limit of memory+Swap usage
	265	* `kernel` (int64, OPTIONAL) - sets hard limit for kernel memory
	266	* `kernelTCP` (int64, OPTIONAL) - sets hard limit for kernel TCP buffer memory
	267
	268	The following properties do not specify memory limits, but are covered by the `memory` controller:
286	269
287	270	* `swappiness` (uint64, OPTIONAL) - sets swappiness parameter of vmscan (See sysctl's vm.swappiness)
288
289		###### Example
	271	The values are from 0 to 100. Higher means more swappy.
	272	* `disableOOMKiller` (bool, OPTIONAL) - enables or disables the OOM killer.
	273	If enabled (`false`), tasks that attempt to consume more memory than they are allowed are immediately killed by the OOM killer.
	274	The OOM killer is enabled by default in every cgroup using the `memory` subsystem.
	275	To disable it, specify a value of `true`.
	276
	277	#### Example
290	278
291	279	```json
292	280	"memory": {
293	281	"limit": 536870912,
294	282	"reservation": 536870912,
295	283	"swap": 536870912,
296		"kernel": 0,
297		"kernelTCP": 0,
298		"swappiness": 0
	284	"kernel": -1,
	285	"kernelTCP": -1,
	286	"swappiness": 0,
	287	"disableOOMKiller": false
299	288	}
300	289	```
301	290
302		#### CPU
303
304		`cpu` represents the cgroup subsystems `cpu` and `cpusets`.
305		For more information, see [the cpusets cgroup man page][cgroup-v1-cpusets].
306
307		The following parameters can be specified to setup the controller:
	291	### <a name="configLinuxCPU" />CPU
	292
	293	`cpu` (object, OPTIONAL) represents the cgroup subsystems `cpu` and `cpusets`.
	294	For more information, see the kernel cgroups documentation about [cpusets][cgroup-v1-cpusets].
	295
	296	The following parameters can be specified to set up the controller:
308	297
309	298	* `shares` (uint64, OPTIONAL) - specifies a relative share of CPU time available to the tasks in a cgroup
310
311		* `quota` (uint64, OPTIONAL) - specifies the total amount of time in microseconds for which all tasks in a cgroup can run during one period (as defined by `period` below)
312
	299	* `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)
313	300	* `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)
314
315		* `realtimeRuntime` (uint64, OPTIONAL) - specifies a period of time in microseconds for the longest continuous period in which the tasks in a cgroup have access to CPU resources
316
	301	* `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
317	302	* `realtimePeriod` (uint64, OPTIONAL) - same as `period` but applies to realtime scheduler only
318
319	303	* `cpus` (string, OPTIONAL) - list of CPUs the container will run in
320
321	304	* `mems` (string, OPTIONAL) - list of Memory Nodes the container will run in
322	305
323		###### Example
	306	#### Example
324	307
325	308	```json
326	309	"cpu": {

334	317	}
335	318	```
336	319
337		#### Block IO Controller
338
339		`blockIO` represents the cgroup subsystem `blkio` which implements the block io controller.
340		For more information, see [the kernel cgroups documentation about blkio][cgroup-v1-blkio].
341
342		The following parameters can be specified to setup the controller:
343
344		* `blkioWeight` (uint16, OPTIONAL) - specifies per-cgroup weight. This is default weight of the group on all devices until and unless overridden by per-device rules. The range is from 10 to 1000.
345
346		* `blkioLeafWeight` (uint16, OPTIONAL) - equivalents of `blkioWeight` for the purpose of deciding how much weight tasks in the given cgroup has while competing with the cgroup's child cgroups. The range is from 10 to 1000.
347
348		* `blkioWeightDevice` (array, OPTIONAL) - specifies the list of devices which will be bandwidth rate limited. The following parameters can be specified per-device:
349		* `major, minor` (int64, REQUIRED) - major, minor numbers for device. More info in `man mknod`.
350		* `weight` (uint16, OPTIONAL) - bandwidth rate for the device, range is from 10 to 1000
351		* `leafWeight` (uint16, OPTIONAL) - bandwidth rate for the device while competing with the cgroup's child cgroups, range is from 10 to 1000, CFQ scheduler only
352
353		You must specify at least one of `weight` or `leafWeight` in a given entry, and can specify both.
354
355		* `blkioThrottleReadBpsDevice`, `blkioThrottleWriteBpsDevice`, `blkioThrottleReadIOPSDevice`, `blkioThrottleWriteIOPSDevice` (array, OPTIONAL) - specify the list of devices which will be IO rate limited. The following parameters can be specified per-device:
356		* `major, minor` (int64, REQUIRED) - major, minor numbers for device. More info in `man mknod`.
	320	### <a name="configLinuxBlockIO" />Block IO
	321
	322	`blockIO` (object, OPTIONAL) represents the cgroup subsystem `blkio` which implements the block IO controller.
	323	For more information, see the kernel cgroups documentation about [blkio][cgroup-v1-blkio].
	324
	325	The following parameters can be specified to set up the controller:
	326
	327	* `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.
	328	* `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.
	329	* `weightDevice` (array of objects, OPTIONAL) - specifies the list of devices which will be bandwidth rate limited. The following parameters can be specified per-device:
	330	* `major, minor` (int64, REQUIRED) - major, minor numbers for device. More info in [mknod(1)][mknod.1] man page.
	331	* `weight` (uint16, OPTIONAL) - bandwidth rate for the device.
	332	* `leafWeight` (uint16, OPTIONAL) - bandwidth rate for the device while competing with the cgroup's child cgroups, CFQ scheduler only
	333
	334	You MUST specify at least one of `weight` or `leafWeight` in a given entry, and MAY specify both.
	335
	336	* `throttleReadBpsDevice`, `throttleWriteBpsDevice`, `throttleReadIOPSDevice`, `throttleWriteIOPSDevice` (array of objects, OPTIONAL) - specify the list of devices which will be IO rate limited.
	337	The following parameters can be specified per-device:
	338	* `major, minor` (int64, REQUIRED) - major, minor numbers for device. More info in [mknod(1)][mknod.1] man page.
357	339	* `rate` (uint64, REQUIRED) - IO rate limit for the device
358	340
359		###### Example
	341	#### Example
360	342
361	343	```json
362	344	"blockIO": {
363		"blkioWeight": 10,
364		"blkioLeafWeight": 10,
365		"blkioWeightDevice": [
	345	"weight": 10,
	346	"leafWeight": 10,
	347	"weightDevice": [
366	348	{
367	349	"major": 8,
368	350	"minor": 0,

375	357	"weight": 500
376	358	}
377	359	],
378		"blkioThrottleReadBpsDevice": [
	360	"throttleReadBpsDevice": [
379	361	{
380	362	"major": 8,
381	363	"minor": 0,
382	364	"rate": 600
383	365	}
384	366	],
385		"blkioThrottleWriteIOPSDevice": [
	367	"throttleWriteIOPSDevice": [
386	368	{
387	369	"major": 8,
388	370	"minor": 16,

392	374	}
393	375	```
394	376
395		#### Huge page limits
396
397		`hugepageLimits` represents the `hugetlb` controller which allows to limit the
	377	### <a name="configLinuxHugePageLimits" />Huge page limits
	378
	379	`hugepageLimits` (array of objects, OPTIONAL) represents the `hugetlb` controller which allows to limit the
398	380	HugeTLB usage per control group and enforces the controller limit during page fault.
399		For more information, see the [kernel cgroups documentation about HugeTLB][cgroup-v1-hugetlb].
400
401		`hugepageLimits` is an array of entries, each having the following structure:
	381	For more information, see the kernel cgroups documentation about [HugeTLB][cgroup-v1-hugetlb].
	382
	383	Each entry has the following structure:
402	384
403	385	* `pageSize` (string, REQUIRED) - hugepage size
404
405	386	* `limit` (uint64, REQUIRED) - limit in bytes of hugepagesize HugeTLB usage
406	387
407		###### Example
408
409		```json
410		"hugepageLimits": [
	388	#### Example
	389
	390	```json
	391	"hugepageLimits": [
411	392	{
412	393	"pageSize": "2MB",
413		"limit": 9223372036854771712
	394	"limit": 209715200
414	395	}
415	396	]
416	397	```
417	398
418		#### Network
419
420		`network` represents the cgroup subsystems `net_cls` and `net_prio`.
421		For more information, see [the net\_cls cgroup man page][cgroup-v1-net-cls] and [the net\_prio cgroup man page][cgroup-v1-net-prio].
422
423		The following parameters can be specified to setup these cgroup controllers:
	399	### <a name="configLinuxNetwork" />Network
	400
	401	`network` (object, OPTIONAL) represents the cgroup subsystems `net_cls` and `net_prio`.
	402	For more information, see the kernel cgroups documentations about [net\_cls cgroup][cgroup-v1-net-cls] and [net\_prio cgroup][cgroup-v1-net-prio].
	403
	404	The following parameters can be specified to set up the controller:
424	405
425	406	* `classID` (uint32, OPTIONAL) - is the network class identifier the cgroup's network packets will be tagged with
426
427		* `priorities` (array, OPTIONAL) - specifies a list of objects of the priorities assigned to traffic originating from
428		processes in the group and egressing the system on various interfaces. The following parameters can be specified per-priority:
429		* `name` (string, REQUIRED) - interface name
	407	* `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.
	408	The following parameters can be specified per-priority:
	409	* `name` (string, REQUIRED) - interface name in [runtime network namespace](glossary.md#runtime-namespace)
430	410	* `priority` (uint32, REQUIRED) - priority applied to the interface
431	411
432		###### Example
433
434		```json
435		"network": {
	412	#### Example
	413
	414	```json
	415	"network": {
436	416	"classID": 1048577,
437	417	"priorities": [
438	418	{

447	427	}
448	428	```
449	429
450		#### PIDs
451
452		`pids` represents the cgroup subsystem `pids`.
453		For more information, see [the pids cgroup man page][cgroup-v1-pids].
454
455		The following parameters can be specified to setup the controller:
	430	### <a name="configLinuxPIDS" />PIDs
	431
	432	`pids` (object, OPTIONAL) represents the cgroup subsystem `pids`.
	433	For more information, see the kernel cgroups documentation about [pids][cgroup-v1-pids].
	434
	435	The following parameters can be specified to set up the controller:
456	436
457	437	* `limit` (int64, REQUIRED) - specifies the maximum number of tasks in the cgroup
458	438
459		###### Example
460
461		```json
462		"pids": {
	439	#### Example
	440
	441	```json
	442	"pids": {
463	443	"limit": 32771
464	444	}
465	445	```
466	446
467		## Sysctl
468
469		`sysctl` allows kernel parameters to be modified at runtime for the container.
470		For more information, see [the man page](http://man7.org/linux/man-pages/man8/sysctl.8.html)
471
472		###### Example
473
474		```json
475		"sysctl": {
	447	## <a name="configLinuxIntelRdt" />IntelRdt
	448
	449	`intelRdt` (object, OPTIONAL) represents the [Intel Resource Director Technology][intel-rdt-cat-kernel-interface].
	450	If `intelRdt` is set, the runtime MUST write the container process ID to the `<container-id>/tasks` file in a mounted `resctrl` pseudo-filesystem, using the container ID from [`start`](runtime.md#start) and creating the `<container-id>` directory if necessary.
	451	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).
	452
	453	If `intelRdt` is not set, the runtime MUST NOT manipulate any `resctrl` psuedo-filesystems.
	454
	455	The following parameters can be specified for the container:
	456
	457	* `l3CacheSchema` (string, OPTIONAL) - specifies the schema for L3 cache id and capacity bitmask (CBM).
	458	If `l3CacheSchema` is set, runtimes MUST write the value to the `schemata` file in the `<container-id>` directory discussed in `intelRdt`.
	459
	460	If `l3CacheSchema` is not set, runtimes MUST NOT write to `schemata` files in any `resctrl` psuedo-filesystems.
	461
	462	### Example
	463
	464	Consider a two-socket machine with two L3 caches where the default CBM is 0xfffff and the max CBM length is 20 bits.
	465	Tasks inside the container only have access to the "upper" 80% of L3 cache id 0 and the "lower" 50% L3 cache id 1:
	466
	467	```json
	468	"linux": {
	469	"intelRdt": {
	470	"l3CacheSchema": "L3:0=ffff0;1=3ff"
	471	}
	472	}
	473	```
	474
	475	## <a name="configLinuxSysctl" />Sysctl
	476
	477	`sysctl` (object, OPTIONAL) allows kernel parameters to be modified at runtime for the container.
	478	For more information, see the [sysctl(8)][sysctl.8] man page.
	479
	480	### Example
	481
	482	```json
	483	"sysctl": {
476	484	"net.ipv4.ip_forward": "1",
477	485	"net.core.somaxconn": "256"
478	486	}
479	487	```
480	488
481		## seccomp
	489	## <a name="configLinuxSeccomp" />Seccomp
482	490
483	491	Seccomp provides application sandboxing mechanism in the Linux kernel.
484	492	Seccomp configuration allows one to configure actions to take for matched syscalls and furthermore also allows matching on values passed as arguments to syscalls.
485		For more information about Seccomp, see [Seccomp kernel documentation](https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt)
486		The actions, architectures, and operators are strings that match the definitions in seccomp.h from [libseccomp](https://github.com/seccomp/libseccomp) and are translated to corresponding values.
487		A valid list of constants as of libseccomp v2.3.0 is shown below.
488
489		Architecture Constants
490		* `SCMP_ARCH_X86`
491		* `SCMP_ARCH_X86_64`
492		* `SCMP_ARCH_X32`
493		* `SCMP_ARCH_ARM`
494		* `SCMP_ARCH_AARCH64`
495		* `SCMP_ARCH_MIPS`
496		* `SCMP_ARCH_MIPS64`
497		* `SCMP_ARCH_MIPS64N32`
498		* `SCMP_ARCH_MIPSEL`
499		* `SCMP_ARCH_MIPSEL64`
500		* `SCMP_ARCH_MIPSEL64N32`
501		* `SCMP_ARCH_PPC`
502		* `SCMP_ARCH_PPC64`
503		* `SCMP_ARCH_PPC64LE`
504		* `SCMP_ARCH_S390`
505		* `SCMP_ARCH_S390X`
506
507		Action Constants:
508		* `SCMP_ACT_KILL`
509		* `SCMP_ACT_TRAP`
510		* `SCMP_ACT_ERRNO`
511		* `SCMP_ACT_TRACE`
512		* `SCMP_ACT_ALLOW`
513
514		Operator Constants:
515		* `SCMP_CMP_NE`
516		* `SCMP_CMP_LT`
517		* `SCMP_CMP_LE`
518		* `SCMP_CMP_EQ`
519		* `SCMP_CMP_GE`
520		* `SCMP_CMP_GT`
521		* `SCMP_CMP_MASKED_EQ`
522
523		###### Example
524
525		```json
526		"seccomp": {
527		"defaultAction": "SCMP_ACT_ALLOW",
528		"architectures": [
529		"SCMP_ARCH_X86"
530		],
531		"syscalls": [
532		{
533		"name": "getcwd",
534		"action": "SCMP_ACT_ERRNO"
535		}
536		]
537		}
538		```
539
540		## Rootfs Mount Propagation
541
542		`rootfsPropagation` sets the rootfs's mount propagation.
543		Its value is either slave, private, or shared.
544		[The kernel doc](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) has more information about mount propagation.
545
546		###### Example
	493	For more information about Seccomp, see [Seccomp][seccomp] kernel documentation.
	494	The actions, architectures, and operators are strings that match the definitions in seccomp.h from [libseccomp][] and are translated to corresponding values.
	495
	496	`seccomp` (object, OPTIONAL)
	497
	498	The following parameters can be specified to set up seccomp:
	499
	500	* `defaultAction` (string, REQUIRED) - the default action for seccomp. Allowed values are the same as `syscalls[].action`.
	501
	502	* `architectures` (array of strings, OPTIONAL) - the architecture used for system calls.
	503	A valid list of constants as of libseccomp v2.3.2 is shown below.
	504
	505	* `SCMP_ARCH_X86`
	506	* `SCMP_ARCH_X86_64`
	507	* `SCMP_ARCH_X32`
	508	* `SCMP_ARCH_ARM`
	509	* `SCMP_ARCH_AARCH64`
	510	* `SCMP_ARCH_MIPS`
	511	* `SCMP_ARCH_MIPS64`
	512	* `SCMP_ARCH_MIPS64N32`
	513	* `SCMP_ARCH_MIPSEL`
	514	* `SCMP_ARCH_MIPSEL64`
	515	* `SCMP_ARCH_MIPSEL64N32`
	516	* `SCMP_ARCH_PPC`
	517	* `SCMP_ARCH_PPC64`
	518	* `SCMP_ARCH_PPC64LE`
	519	* `SCMP_ARCH_S390`
	520	* `SCMP_ARCH_S390X`
	521	* `SCMP_ARCH_PARISC`
	522	* `SCMP_ARCH_PARISC64`
	523
	524	* `syscalls` (array of objects, OPTIONAL) - match a syscall in seccomp.
	525
	526	While this property is OPTIONAL, some values of `defaultAction` are not useful without `syscalls` entries.
	527	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.
	528
	529	Each entry has the following structure:
	530
	531	* `names` (array of strings, REQUIRED) - the names of the syscalls.
	532	`names` MUST contain at least one entry.
	533	* `action` (string, REQUIRED) - the action for seccomp rules.
	534	A valid list of constants as of libseccomp v2.3.2 is shown below.
	535
	536	* `SCMP_ACT_KILL`
	537	* `SCMP_ACT_TRAP`
	538	* `SCMP_ACT_ERRNO`
	539	* `SCMP_ACT_TRACE`
	540	* `SCMP_ACT_ALLOW`
	541
	542	* `args` (array of objects, OPTIONAL) - the specific syscall in seccomp.
	543
	544	Each entry has the following structure:
	545
	546	* `index` (uint, REQUIRED) - the index for syscall arguments in seccomp.
	547	* `value` (uint64, REQUIRED) - the value for syscall arguments in seccomp.
	548	* `valueTwo` (uint64, OPTIONAL) - the value for syscall arguments in seccomp.
	549	* `op` (string, REQUIRED) - the operator for syscall arguments in seccomp.
	550	A valid list of constants as of libseccomp v2.3.2 is shown below.
	551
	552	* `SCMP_CMP_NE`
	553	* `SCMP_CMP_LT`
	554	* `SCMP_CMP_LE`
	555	* `SCMP_CMP_EQ`
	556	* `SCMP_CMP_GE`
	557	* `SCMP_CMP_GT`
	558	* `SCMP_CMP_MASKED_EQ`
	559
	560	### Example
	561
	562	```json
	563	"seccomp": {
	564	"defaultAction": "SCMP_ACT_ALLOW",
	565	"architectures": [
	566	"SCMP_ARCH_X86",
	567	"SCMP_ARCH_X32"
	568	],
	569	"syscalls": [
	570	{
	571	"names": [
	572	"getcwd",
	573	"chmod"
	574	],
	575	"action": "SCMP_ACT_ERRNO"
	576	}
	577	]
	578	}
	579	```
	580
	581	## <a name="configLinuxRootfsMountPropagation" />Rootfs Mount Propagation
	582
	583	`rootfsPropagation` (string, OPTIONAL) sets the rootfs's mount propagation.
	584	Its value is either slave, private, shared or unbindable.
	585	The [Shared Subtrees][sharedsubtree] article in the kernel documentation has more information about mount propagation.
	586
	587	### Example
547	588
548	589	```json
549	590	"rootfsPropagation": "slave",
550	591	```
551	592
552		## Masked Paths
553
554		`maskedPaths` will mask over the provided paths inside the container so that they cannot be read.
555
556		###### Example
	593	## <a name="configLinuxMaskedPaths" />Masked Paths
	594
	595	`maskedPaths` (array of strings, OPTIONAL) will mask over the provided paths inside the container so that they cannot be read.
	596	The values MUST be absolute paths in the [container namespace](glossary.md#container_namespace).
	597
	598	### Example
557	599
558	600	```json
559	601	"maskedPaths": [

561	603	]
562	604	```
563	605
564		## Readonly Paths
565
566		`readonlyPaths` will set the provided paths as readonly inside the container.
567
568		###### Example
	606	## <a name="configLinuxReadonlyPaths" />Readonly Paths
	607
	608	`readonlyPaths` (array of strings, OPTIONAL) will set the provided paths as readonly inside the container.
	609	The values MUST be absolute paths in the [container namespace](glossary.md#container-namespace).
	610
	611	### Example
569	612
570	613	```json
571	614	"readonlyPaths": [

573	616	]
574	617	```
575	618
576		## Mount Label
577
578		`mountLabel` will set the Selinux context for the mounts in the container.
579
580		###### Example
	619	## <a name="configLinuxMountLabel" />Mount Label
	620
	621	`mountLabel` (string, OPTIONAL) will set the Selinux context for the mounts in the container.
	622
	623	### Example
581	624
582	625	```json
583	626	"mountLabel": "system_u:object_r:svirt_sandbox_file_t:s0:c715,c811"
584	627	```
	628
585	629
586	630	[cgroup-v1]: https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt
587	631	[cgroup-v1-blkio]: https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt

593	637	[cgroup-v1-net-prio]: https://www.kernel.org/doc/Documentation/cgroup-v1/net_prio.txt
594	638	[cgroup-v1-pids]: https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt
595	639	[cgroup-v2]: https://www.kernel.org/doc/Documentation/cgroup-v2.txt
596		[devices]: https://www.kernel.org/doc/Documentation/devices.txt
	640	[devices]: https://www.kernel.org/doc/Documentation/admin-guide/devices.txt
597	641	[devpts]: https://www.kernel.org/doc/Documentation/filesystems/devpts.txt
598
	642	[file]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_164
	643	[libseccomp]: https://github.com/seccomp/libseccomp
	644	[procfs]: https://www.kernel.org/doc/Documentation/filesystems/proc.txt
	645	[seccomp]: https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt
	646	[sharedsubtree]: https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt
	647	[sysfs]: https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt
	648	[tmpfs]: https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt
	649
	650	[console.4]: http://man7.org/linux/man-pages/man4/console.4.html
	651	[full.4]: http://man7.org/linux/man-pages/man4/full.4.html
599	652	[mknod.1]: http://man7.org/linux/man-pages/man1/mknod.1.html
600	653	[mknod.2]: http://man7.org/linux/man-pages/man2/mknod.2.html
601		[console.4]: http://man7.org/linux/man-pages/man4/console.4.html
602		[full.4]: http://man7.org/linux/man-pages/man4/full.4.html
	654	[namespaces.7_2]: http://man7.org/linux/man-pages/man7/namespaces.7.html
603	655	[null.4]: http://man7.org/linux/man-pages/man4/null.4.html
604	656	[pts.4]: http://man7.org/linux/man-pages/man4/pts.4.html
605	657	[random.4]: http://man7.org/linux/man-pages/man4/random.4.html
	658	[sysctl.8]: http://man7.org/linux/man-pages/man8/sysctl.8.html
606	659	[tty.4]: http://man7.org/linux/man-pages/man4/tty.4.html
607	660	[zero.4]: http://man7.org/linux/man-pages/man4/zero.4.html
	661	[user-namespaces]: http://man7.org/linux/man-pages/man7/user_namespaces.7.html
	662	[intel-rdt-cat-kernel-interface]: https://www.kernel.org/doc/Documentation/x86/intel_rdt_ui.txt

+36

-31

config-solaris.md less more

0		# Solaris Application Container Configuration
	0	# <a name="solarisApplicationContainerConfiguration" />Solaris Application Container Configuration
1	1
2		Solaris application containers can be configured using the following properties, all of the below properties have mappings to properties specified under zonecfg(1M) man page, except milestone.
	2	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.
3	3
4		## milestone
	4	## <a name="configSolarisMilestone" />milestone
5	5	The SMF(Service Management Facility) FMRI which should go to "online" state before we start the desired process within the container.
6	6
7	7	`milestone` (string, OPTIONAL)

11	11	"milestone": "svc:/milestone/container:default"
12	12	```
13	13
14		## limitpriv
	14	## <a name="configSolarisLimitpriv" />limitpriv
15	15	The maximum set of privileges any process in this container can obtain.
16		The property should consist of a comma-separated privilege set specification as described in priv_str_to_set(3C) man page for the respective release of Solaris.
	16	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.
17	17
18	18	`limitpriv` (string, OPTIONAL)
19	19

22	22	"limitpriv": "default"
23	23	```
24	24
25		## maxShmMemory
	25	## <a name="configSolarisMaxShmMemory" />maxShmMemory
26	26	The maximum amount of shared memory allowed for this application container.
27	27	A scale (K, M, G, T) can be applied to the value for each of these numbers (for example, 1M is one megabyte).
28		Mapped to max-shm-memory in zonecfg(1M) man page.
	28	Mapped to `max-shm-memory` in [zonecfg(1M)][zonecfg.1m_2] man page.
29	29
30	30	`maxShmMemory` (string, OPTIONAL)
31	31

34	34	"maxShmMemory": "512m"
35	35	```
36	36
37		## cappedCPU
	37	## <a name="configSolarisCappedCpu" />cappedCPU
38	38	Sets a limit on the amount of CPU time that can be used by a container.
39	39	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).
40	40	An ncpu value of 1 means 100% of a CPU, a value of 1.25 means 125%, .75 mean 75%, and so forth.
41	41	When projects within a capped container have their own caps, the minimum value takes precedence.
42		cappedCPU is mapped to capped-cpu in zonecfg(1M) man page.
	42	cappedCPU is mapped to `capped-cpu` in [zonecfg(1M)][zonecfg.1m_2] man page.
43	43
44	44	* `ncpus` (string, OPTIONAL)
45	45

50	50	}
51	51	```
52	52
53		## cappedMemory
	53	## <a name="configSolarisCappedMemory" />cappedMemory
54	54	The physical and swap caps on the memory that can be used by this application container.
55	55	A scale (K, M, G, T) can be applied to the value for each of these numbers (for example, 1M is one megabyte).
56		cappedMemory is mapped to capped-memory in zonecfg(1M) man page.
	56	cappedMemory is mapped to `capped-memory` in [zonecfg(1M)][zonecfg.1m_2] man page.
57	57
58	58	* `physical` (string, OPTIONAL)
59	59	* `swap` (string, OPTIONAL)

66	66	}
67	67	```
68	68
69		## Network
	69	## <a name="configSolarisNetwork" />Network
70	70
71		### Automatic Network (anet)
72		anet is specified as an array that is used to setup networking for Solaris application containers.
	71	### <a name="configSolarisAutomaticNetwork" />Automatic Network (anet)
	72	anet is specified as an array that is used to set up networking for Solaris application containers.
73	73	The anet resource represents the automatic creation of a network resource for an application container.
74	74	The zones administration daemon, zoneadmd, is the primary process for managing the container's virtual platform.
75		One of the daemons is responsibilities is creation and teardown of the networks for the container.
76		For more information on the daemon check the zoneadmd(1M) man page.
	75	One of the daemon's responsibilities is creation and teardown of the networks for the container.
	76	For more information on the daemon see the [zoneadmd(1M)][zoneadmd.1m] man page.
77	77	When such a container is started, a temporary VNIC(Virtual NIC) is automatically created for the container.
78	78	The VNIC is deleted when the container is torn down.
79		The following properties can be used to setup automatic networks.
80		For additional information on properties check zonecfg(1M) man page for the respective release of Solaris.
	79	The following properties can be used to set up automatic networks.
	80	For additional information on properties, check the [zonecfg(1M)][zonecfg.1m_2] man page for the respective release of Solaris.
81	81
82	82	* `linkname` (string, OPTIONAL) Specify a name for the automatically created VNIC datalink.
83	83	* `lowerLink` (string, OPTIONAL) Specify the link over which the VNIC will be created.
84		Mapped to lower-link in the zonecfg(1M) man page.
85		* `allowedAddress` (string, OPTIONAL) The set of IP addresses that the container can use might be constrained by specifying the allowedAddress property.
86		If allowedAddress has not been specified, then they can use any IP address on the associated physical interface for the network resource.
87		Otherwise, when allowedAddress is specified, the container cannot use IP addresses that are not in the allowedAddress list for the physical address.
88		Mapped to allowed-address in the zonecfg(1M) man page.
89		* `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.
90		When it is set to false, the allowedAddress will not be configured on container start.
91		Mapped to configure-allowed-address in the zonecfg(1M) man page.
	84	Mapped to `lower-link` in the [zonecfg(1M)][zonecfg.1m_2] man page.
	85	* `allowedAddress` (string, OPTIONAL) The set of IP addresses that the container can use might be constrained by specifying the `allowedAddress` property.
	86	If `allowedAddress` has not been specified, then they can use any IP address on the associated physical interface for the network resource.
	87	Otherwise, when `allowedAddress` is specified, the container cannot use IP addresses that are not in the `allowedAddress` list for the physical address.
	88	Mapped to `allowed-address` in the [zonecfg(1M)][zonecfg.1m_2] man page.
	89	* `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.
	90	When it is set to false, the `allowedAddress` will not be configured on container start.
	91	Mapped to `configure-allowed-address` in the [zonecfg(1M)][zonecfg.1m_2] man page.
92	92	* `defrouter` (string, OPTIONAL) The value for the OPTIONAL default router.
93	93	* `macAddress` (string, OPTIONAL) Set the VNIC's MAC addresses based on the specified value or keyword.
94		If not a keyword, it is interpreted as a unicast MAC address.
95		For a list of the supported keywords please refer to the zonecfg(1M) man page of the respective Solaris release.
96		Mapped to mac-address in the zonecfg(1M) man page.
	94	If not a keyword, it is interpreted as a unicast MAC address.
	95	For a list of the supported keywords please refer to the [zonecfg(1M)][zonecfg.1m_2] man page of the respective Solaris release.
	96	Mapped to `mac-address` in the [zonecfg(1M)][zonecfg.1m_2] man page.
97	97	* `linkProtection` (string, OPTIONAL) Enables one or more types of link protection using comma-separated values.
98		See the protection property in dladm(8) for supported values in respective release of Solaris.
99		Mapped to link-protection in the zonecfg(1M) man page.
	98	See the protection property in dladm(8) for supported values in respective release of Solaris.
	99	Mapped to `link-protection` in the [zonecfg(1M)][zonecfg.1m_2] man page.
100	100
101	101	#### Example
102	102	```json

112	112	}
113	113	]
114	114	```
	115
	116
	117	[priv-str-to-set.3c]: http://docs.oracle.com/cd/E86824_01/html/E54766/priv-str-to-set-3c.html
	118	[zoneadmd.1m]: http://docs.oracle.com/cd/E86824_01/html/E54764/zoneadmd-1m.html
	119	[zonecfg.1m_2]: http://docs.oracle.com/cd/E86824_01/html/E54764/zonecfg-1m.html

+100

-24

config-windows.md less more

0		# Windows-specific Container Configuration
	0	# <a name="windowsSpecificContainerConfiguration" />Windows-specific Container Configuration
1	1
2	2	This document describes the schema for the [Windows-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md).
3	3	The Windows container specification uses APIs provided by the Windows Host Compute Service (HCS) to fulfill the spec.
4	4
5		## Resources
	5	## <a name="configWindowsLayerFolders" />LayerFolders
	6
	7	`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.
	8	`layerFolders` MUST contain at least one entry.
	9
	10	### Example
	11
	12	```json
	13	"windows": {
	14	"layerFolders": [
	15	"C:\\Layers\\layer1",
	16	"C:\\Layers\\layer2"
	17	]
	18	}
	19	```
	20
	21	## <a name="configWindowsResources" />Resources
6	22
7	23	You can configure a container's resource limits via the OPTIONAL `resources` field of the Windows configuration.
8	24
9		### Memory
	25	### <a name="configWindowsMemory" />Memory
10	26
11	27	`memory` is an OPTIONAL configuration for the container's memory usage.
12	28

14	30
15	31	* `limit` (uint64, OPTIONAL) - sets limit of memory usage in bytes.
16	32
17		* `reservation` (uint64, OPTIONAL) - sets the guaranteed minimum amount of memory for a container in bytes.
18
19	33	#### Example
20	34
21	35	```json
22	36	"windows": {
23	37	"resources": {
24	38	"memory": {
25		"limit": 2097152,
26		"reservation": 524288
	39	"limit": 2097152
27	40	}
28	41	}
29	42	}
30	43	```
31	44
32		### CPU
	45	### <a name="configWindowsCpu" />CPU
33	46
34	47	`cpu` is an OPTIONAL configuration for the container's CPU usage.
35	48
36	49	The following parameters can be specified:
37	50
38	51	* `count` (uint64, OPTIONAL) - specifies the number of CPUs available to the container.
39
40		* `shares` (uint16, OPTIONAL) - specifies the relative weight to other containers with CPU shares. The range is from 1 to 10000.
41
42		* `percent` (uint, OPTIONAL) - specifies the percentage of available CPUs usable by the container.
	52	* `shares` (uint16, OPTIONAL) - specifies the relative weight to other containers with CPU shares.
	53	* `maximum` (uint, OPTIONAL) - specifies the portion of processor cycles that this container can use as a percentage times 100.
43	54
44	55	#### Example
45	56

47	58	"windows": {
48	59	"resources": {
49	60	"cpu": {
50		"percent": 50
	61	"maximum": 5000
51	62	}
52	63	}
53	64	}
54	65	```
55	66
56		### Storage
	67	### <a name="configWindowsStorage" />Storage
57	68
58	69	`storage` is an OPTIONAL configuration for the container's storage usage.
59	70
60	71	The following parameters can be specified:
61	72
62	73	* `iops` (uint64, OPTIONAL) - specifies the maximum IO operations per second for the system drive of the container.
63
64	74	* `bps` (uint64, OPTIONAL) - specifies the maximum bytes per second for the system drive of the container.
65
66	75	* `sandboxSize` (uint64, OPTIONAL) - specifies the minimum size of the system drive in bytes.
67	76
68	77	#### Example

77	86	}
78	87	```
79	88
80		### Network
	89	## <a name="configWindowsNetwork" />Network
81	90
82		`network` is an OPTIONAL configuration for the container's network usage.
	91	You can configure a container's networking options via the OPTIONAL `network` field of the Windows configuration.
83	92
84	93	The following parameters can be specified:
85	94
86		* `egressBandwidth` (uint64, OPTIONAL) - specified the maximum egress bandwidth in bytes per second for the container.
	95	* `endpointList` (array of strings, OPTIONAL) - list of HNS (Host Network Service) endpoints that the container should connect to.
	96	* `allowUnqualifiedDNSQuery` (bool, OPTIONAL) - specifies if unqualified DNS name resolution is allowed.
	97	* `DNSSearchList` (array of strings, OPTIONAL) - comma separated list of DNS suffixes to use for name resolution.
	98	* `networkSharedContainerName` (string, OPTIONAL) - name (ID) of the container that we will share with the network stack.
87	99
88		#### Example
	100	### Example
89	101
90	102	```json
91	103	"windows": {
92		"resources": {
93		"network": {
94		"egressBandwidth": 1048577
95		}
	104	"network": {
	105	"endpointList": [
	106	"7a010682-17e0-4455-a838-02e5d9655fe6"
	107	],
	108	"allowUnqualifiedDNSQuery": true,
	109	"DNSSearchList": [
	110	"a.com",
	111	"b.com"
	112	],
	113	"networkSharedContainerName": "containerName"
96	114	}
97	115	}
98	116	```
	117
	118	## <a name="configWindowsCredentialSpec" />Credential Spec
	119
	120	You can configure a container's group Managed Service Account (gMSA) via the OPTIONAL `credentialSpec` field of the Windows configuration.
	121	The `credentialSpec` is a JSON object whose properties are implementation-defined.
	122	For more information about gMSAs, see [Active Directory Service Accounts for Windows Containers][gMSAOverview].
	123	For more information about tooling to generate a gMSA, see [Deployment Overview][gMSATooling].
	124
	125
	126	[gMSAOverview]: https://aka.ms/windowscontainers/manage-serviceaccounts
	127	[gMSATooling]: https://aka.ms/windowscontainers/credentialspec-tools
	128
	129	## <a name="configWindowsServicing" />Servicing
	130
	131	When a container terminates, the Host Compute Service indicates if a Windows update servicing operation is pending.
	132	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.
	133
	134	### Example
	135
	136	```json
	137	"windows": {
	138	"servicing": true
	139	}
	140	```
	141
	142	## <a name="configWindowsIgnoreFlushesDuringBoot" />IgnoreFlushesDuringBoot
	143
	144	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.
	145
	146	### Example
	147
	148	```json
	149	"windows": {
	150	"ignoreFlushesDuringBoot": true
	151	}
	152	```
	153
	154	## <a name="configWindowsHyperV" />HyperV
	155
	156	`hyperv` is an OPTIONAL field of the Windows configuration.
	157	If present, the container MUST be run with Hyper-V isolation.
	158	If omitted, the container MUST be run as a Windows Server container.
	159
	160	The following parameters can be specified:
	161
	162	* `utilityVMPath` (string, OPTIONAL) - specifies the path to the image used for the utility VM.
	163	This would be specified if using a base image which does not contain a utility VM image.
	164	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.
	165
	166	### Example
	167
	168	```json
	169	"windows": {
	170	"hyperv": {
	171	"utilityVMPath": "C:\\path\\to\\utilityvm"
	172	}
	173	}
	174	```

+321

-207

config.md less more

0		# Container Configuration file
1
2		The container's top-level directory MUST contain a configuration file called `config.json`.
	0	# <a name="containerConfigurationFile" />Container Configuration file
	1
	2	This configuration file contains metadata necessary to implement [standard operations](runtime.md#operations) against the container.
	3	This includes the process to run, environment variables to inject, sandboxing features to use, etc.
	4
3	5	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).
4
5		The configuration file contains metadata necessary to implement standard operations against the container.
6		This includes the process to run, environment variables to inject, sandboxing features to use, etc.
7
8		Below is a detailed description of each field defined in the configuration format.
9
10		## Specification version
11
12		* `ociVersion` (string, REQUIRED) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the Open Container Runtime Specification with which the bundle complies.
13		The Open Container Runtime Specification follows semantic versioning and retains forward and backward compatibility within major versions.
14		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.
	6	[Platform](spec.md#platforms)-specific configuration schema are defined in the [platform-specific documents](#platform-specific-configuration) linked below.
	7	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"`).
	8
	9	Below is a detailed description of each field defined in the configuration format and valid values are specified.
	10	Platform-specific fields are identified as such.
	11	For all platform-specific configuration values, the scope defined below in the [Platform-specific configuration](#platform-specific-configuration) section applies.
	12
	13
	14	## <a name="configSpecificationVersion" />Specification version
	15
	16	* `ociVersion` (string, REQUIRED) MUST be in [SemVer v2.0.0][semver-v2.0.0] format and specifies the version of the Open Container Runtime Specification with which the bundle complies.
	17	The Open Container Runtime Specification follows semantic versioning and retains forward and backward compatibility within major versions.
	18	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.
15	19
16	20	### Example
17	21

19	23	"ociVersion": "0.1.0"
20	24	```
21	25
22		## Root Configuration
23
24		`root` (object, REQUIRED) configures the container's root filesystem.
	26	## <a name="configRoot" />Root
	27
	28	`root` (object, OPTIONAL) specifies the container's root filesystem.
	29	On Windows, for Windows Server Containers, this field is REQUIRED.
	30	For [Hyper-V Containers](config-windows.md#hyperv), this field MUST NOT be set.
	31
	32	On all other platforms, this field is REQUIRED.
25	33
26	34	* `path` (string, REQUIRED) Specifies the path to the root filesystem for the container.
27		The path can be an absolute path (starting with /) or a relative path (not starting with /), which is relative to the bundle.
28		For example (Linux), with a bundle at `/to/bundle` and a root filesystem at `/to/bundle/rootfs`, the `path` value can be either `/to/bundle/rootfs` or `rootfs`.
29		A directory MUST exist at the path declared by the field.
	35
	36	* On Windows, `path` MUST be a [volume GUID path][naming-a-volume].
	37
	38	* On POSIX platforms, `path` is either an absolute path or a relative path to the bundle.
	39	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`.
	40	The value SHOULD be the conventional `rootfs`.
	41
	42	A directory MUST exist at the path declared by the field.
	43
30	44	* `readonly` (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container, defaults to false.
31
32		### Example
	45	* On Windows, this field MUST be omitted or false.
	46
	47	### Example (POSIX platforms)
33	48
34	49	```json
35	50	"root": {

38	53	}
39	54	```
40	55
41		## Mounts
42
43		`mounts` (array, OPTIONAL) configures additional mounts (on top of [`root`](#root-configuration)).
44		The runtime MUST mount entries in the listed order.
45		The parameters are similar to the ones in [the Linux mount system call](http://man7.org/linux/man-pages/man2/mount.2.html).
	56	### Example (Windows)
	57
	58	```json
	59	"root": {
	60	"path": "\\\\?\\Volume{ec84d99e-3f02-11e7-ac6c-00155d7682cf}\\"
	61	}
	62	```
	63
	64	## <a name="configMounts" />Mounts
	65
	66	`mounts` (array of objects, OPTIONAL) specifies additional mounts beyond [`root`](#root).
	67	The runtime MUST mount entries in the listed order.
	68	For Linux, the parameters are as documented in [mount(2)][mount.2] system call man page.
	69	For Solaris, the mount entry corresponds to the 'fs' resource in the [zonecfg(1M)][zonecfg.1m] man page.
46	70
47	71	* `destination` (string, REQUIRED) Destination of mount point: path inside container.
48		For the Windows operating system, one mount destination MUST NOT be nested within another mount (e.g., c:\\foo and c:\\foo\\bar).
49		* `type` (string, REQUIRED) The filesystem type of the filesystem to be mounted.
50		Linux: filesystemtype argument supported by the kernel are listed in /proc/filesystems (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660").
51		Windows: ntfs.
52		* `source` (string, REQUIRED) A device name, but can also be a directory name or a dummy.
53		Windows: the volume name that is the target of the mount point, \\?\Volume\{GUID}\ (on Windows source is called target).
54		* `options` (list of strings, OPTIONAL) Mount options of the filesystem to be used.
55		Linux: [supported][mount.8-filesystem-independent] [options][mount.8-filesystem-specific] are listed in [mount(8)][mount.8].
	72	This value MUST be an absolute path.
	73	* Windows: one mount destination MUST NOT be nested within another mount (e.g., c:\\foo and c:\\foo\\bar).
	74	* Solaris: corresponds to "dir" of the fs resource in [zonecfg(1M)][zonecfg.1m].
	75	* `source` (string, OPTIONAL) A device name, but can also be a directory name or a dummy.
	76	Path values are either absolute or relative to the bundle.
	77	* Windows: a local directory on the filesystem of the container host. UNC paths and mapped drives are not supported.
	78	* Solaris: corresponds to "special" of the fs resource in [zonecfg(1M)][zonecfg.1m].
	79	* `options` (array of strings, OPTIONAL) Mount options of the filesystem to be used.
	80	* Linux: supported options are listed in the [mount(8)][mount.8] man page.
	81	Note both [filesystem-independent][mount.8-filesystem-independent] and [filesystem-specific][mount.8-filesystem-specific] options are listed.
	82	* Solaris: corresponds to "options" of the fs resource in [zonecfg(1M)][zonecfg.1m].
	83	* Windows: runtimes MUST support `ro`, mounting the filesystem read-only when `ro` is given.
	84
	85	### Example (Windows)
	86
	87	```json
	88	"mounts": [
	89	{
	90	"destination": "C:\\folder-inside-container",
	91	"source": "C:\\folder-on-host",
	92	"options": ["ro"]
	93	}
	94	]
	95	```
	96
	97	### <a name="configPOSIXMounts" />POSIX-platform Mounts
	98
	99	For POSIX platforms the `mounts` structure has the following fields:
	100
	101	* `type` (string, OPTIONAL) The type of the filesystem to be mounted.
	102	* Linux: filesystem types supported by the kernel as listed in /proc/filesystems (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660").
	103	* Solaris: corresponds to "type" of the fs resource in [zonecfg(1M)][zonecfg.1m].
56	104
57	105	### Example (Linux)
58	106

73	121	]
74	122	```
75	123
76		### Example (Windows)
	124	### Example (Solaris)
77	125
78	126	```json
79	127	"mounts": [
80		"myfancymountpoint": {
81		"destination": "C:\\Users\\crosbymichael\\My Fancy Mount Point\\",
82		"type": "ntfs",
83		"source": "\\\\?\\Volume\\{2eca078d-5cbc-43d3-aff8-7e8511f60d0e}\\",
84		"options": []
	128	{
	129	"destination": "/opt/local",
	130	"type": "lofs",
	131	"source": "/usr/local",
	132	"options": ["ro","nodevices"]
	133	},
	134	{
	135	"destination": "/opt/sfw",
	136	"type": "lofs",
	137	"source": "/opt/sfw"
85	138	}
86	139	]
87	140	```
88	141
89		See links for details about [mountvol](http://ss64.com/nt/mountvol.html) and [SetVolumeMountPoint](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365561(v=vs.85).aspx) in Windows.
90
91
92		## Process configuration
93
94		`process` (object, REQUIRED) configures the container process.
95
96		* `terminal` (bool, OPTIONAL) specifies whether you want a terminal attached to that process, defaults to false.
97		* `consoleSize` (object, OPTIONAL) specifies the console size of the terminal if attached, containing the following properties:
98		* `height` (uint, REQUIRED)
99		* `width` (uint, REQUIRED)
	142	## <a name="configProcess" />Process
	143
	144	`process` (object, OPTIONAL) specifies the container process.
	145	This property is REQUIRED when [`start`](runtime.md#start) is called.
	146
	147	* `terminal` (bool, OPTIONAL) specifies whether a terminal is attached to the process, defaults to false.
	148	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].
	149	* `consoleSize` (object, OPTIONAL) specifies the console size in characters of the terminal.
	150	Runtimes MUST ignore `consoleSize` if `terminal` is `false` or unset.
	151	* `height` (uint, REQUIRED)
	152	* `width` (uint, REQUIRED)
100	153	* `cwd` (string, REQUIRED) is the working directory that will be set for the executable.
101		This value MUST be an absolute path.
102		* `env` (array of strings, OPTIONAL) contains a list of variables that will be set in the process's environment prior to execution.
103		Elements in the array are specified as Strings in the form "KEY=value".
104		The left hand side MUST consist solely of letters, digits, and underscores `_` as outlined in [IEEE Std 1003.1-2001](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html).
105		* `args` (array of strings, REQUIRED) executable to launch and any flags as an array.
106		The executable is the first element and MUST be available at the given path inside of the rootfs.
107		If the executable path is not an absolute path then the search $PATH is interpreted to find the executable.
108
109		For Linux-based systems the process structure supports the following process specific fields:
110
111		* `capabilities` (array of strings, OPTIONAL) capabilities is an array that specifies Linux capabilities that can be provided to the process inside the container.
112		Valid values are the strings for capabilities defined in [the man page](http://man7.org/linux/man-pages/man7/capabilities.7.html)
113		* `rlimits` (array of rlimits, OPTIONAL) rlimits is an array of rlimits that allows setting resource limits for a process inside the container.
114		The kernel enforces the `soft` limit for a resource while the `hard` limit acts as a ceiling for that value that could be set by an unprivileged process.
115		Valid values for the 'type' field are the resources defined in [the man page](http://man7.org/linux/man-pages/man2/setrlimit.2.html).
116		* `apparmorProfile` (string, OPTIONAL) apparmor profile specifies the name of the apparmor profile that will be used for the container.
117		For more information about Apparmor, see [Apparmor documentation](https://wiki.ubuntu.com/AppArmor)
118		* `selinuxLabel` (string, OPTIONAL) SELinux process label specifies the label with which the processes in a container are run.
119		For more information about SELinux, see [Selinux documentation](http://selinuxproject.org/page/Main_Page)
120		* `noNewPrivileges` (bool, OPTIONAL) setting `noNewPrivileges` to true prevents the processes in the container from gaining additional privileges.
121		[The kernel doc](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt) has more information on how this is achieved using a prctl system call.
122
123		### User
	154	This value MUST be an absolute path.
	155	* `env` (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008's `environ`][ieee-1003.1-2008-xbd-c8.1].
	156	* `args` (array of strings, REQUIRED) with similar semantics to [IEEE Std 1003.1-2008 `execvp`'s argv][ieee-1003.1-2008-xsh-exec].
	157	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.
	158
	159	### <a name="configPOSIXProcess" />POSIX process
	160
	161	For systems that support POSIX rlimits (for example Linux and Solaris), the `process` object supports the following process-specific properties:
	162
	163	* `rlimits` (array of objects, OPTIONAL) allows setting resource limits for the process.
	164	Each entry has the following structure:
	165
	166	* `type` (string, REQUIRED) the platform resource being limited.
	167	* Linux: valid values are defined in the [`getrlimit(2)`][getrlimit.2] man page, such as `RLIMIT_MSGQUEUE`.
	168	* Solaris: valid values are defined in the [`getrlimit(3)`][getrlimit.3] man page, such as `RLIMIT_CORE`.
	169
	170	The runtime MUST [generate an error](runtime.md#errors) for any values which cannot be mapped to a relevant kernel interface
	171	For each entry in `rlimits`, a [`getrlimit(3)`][getrlimit.3] on `type` MUST succeed.
	172	For the following properties, `rlim` refers to the status returned by the `getrlimit(3)` call.
	173
	174	* `soft` (uint64, REQUIRED) the value of the limit enforced for the corresponding resource.
	175	`rlim.rlim_cur` MUST match the configured value.
	176	* `hard` (uint64, REQUIRED) the ceiling for the soft limit that could be set by an unprivileged process.
	177	`rlim.rlim_max` MUST match the configured value.
	178	Only a privileged process (e.g. one with the `CAP_SYS_RESOURCE` capability) can raise a hard limit.
	179
	180	If `rlimits` contains duplicated entries with same `type`, the runtime MUST [generate an error](runtime.md#errors).
	181
	182	### <a name="configLinuxProcess" />Linux Process
	183
	184	For Linux-based systems, the `process` object supports the following process-specific properties.
	185
	186	* `apparmorProfile` (string, OPTIONAL) specifies the name of the AppArmor profile for the process.
	187	For more information about AppArmor, see [AppArmor documentation][apparmor].
	188	* `capabilities` (object, OPTIONAL) is an object containing arrays that specifies the sets of capabilities for the process.
	189	Valid values are defined in the [capabilities(7)][capabilities.7] man page, such as `CAP_CHOWN`.
	190	Any value which cannot be mapped to a relevant kernel interface MUST cause an error.
	191	`capabilities` contains the following properties:
	192
	193	* `effective` (array of strings, OPTIONAL) the `effective` field is an array of effective capabilities that are kept for the process.
	194	* `bounding` (array of strings, OPTIONAL) the `bounding` field is an array of bounding capabilities that are kept for the process.
	195	* `inheritable` (array of strings, OPTIONAL) the `inheritable` field is an array of inheritable capabilities that are kept for the process.
	196	* `permitted` (array of strings, OPTIONAL) the `permitted` field is an array of permitted capabilities that are kept for the process.
	197	* `ambient` (array of strings, OPTIONAL) the `ambient` field is an array of ambient capabilities that are kept for the process.
	198	* `noNewPrivileges` (bool, OPTIONAL) setting `noNewPrivileges` to true prevents the process from gaining additional privileges.
	199	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.
	200	* `oomScoreAdj` (int, OPTIONAL) adjusts the oom-killer score in `[pid]/oom_score_adj` for the process's `[pid]` in a [proc pseudo-filesystem][procfs].
	201	If `oomScoreAdj` is set, the runtime MUST set `oom_score_adj` to the given value.
	202	If `oomScoreAdj` is not set, the runtime MUST NOT change the value of `oom_score_adj`.
	203
	204	This is a per-process setting, where as [`disableOOMKiller`](config-linux.md#memory) is scoped for a memory cgroup.
	205	For more information on how these two settings work together, see [the memory cgroup documentation section 10. OOM Contol][cgroup-v1-memory_2].
	206	* `selinuxLabel` (string, OPTIONAL) specifies the SELinux label for the process.
	207	For more information about SELinux, see [SELinux documentation][selinux].
	208
	209	### <a name="configUser" />User
124	210
125	211	The user for the process is a platform-specific structure that allows specific control over which user the process runs as.
126	212
127		#### Linux and Solaris User
128
129		For Linux and Solaris based systems the user structure has the following fields:
130
131		* `uid` (int, REQUIRED) specifies the user ID in the [container namespace][container-namespace].
132		* `gid` (int, REQUIRED) specifies the group ID in the [container namespace][container-namespace].
133		* `additionalGids` (array of ints, OPTIONAL) specifies additional group IDs (in the [container namespace][container-namespace]) to be added to the process.
	213	#### <a name="configPOSIXUser" />POSIX-platform User
	214
	215	For POSIX platforms the `user` structure has the following fields:
	216
	217	* `uid` (int, REQUIRED) specifies the user ID in the [container namespace](glossary.md#container-namespace).
	218	* `gid` (int, REQUIRED) specifies the group ID in the [container namespace](glossary.md#container-namespace).
	219	* `additionalGids` (array of ints, OPTIONAL) specifies additional group IDs in the [container namespace](glossary.md#container-namespace) to be added to the process.
134	220
135	221	_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)_
136
137		_Note: For Solaris, uid and gid specify the uid and gid of the process inside the container and need not be same as in the host._
138	222
139	223	### Example (Linux)
140	224

161	245	"apparmorProfile": "acme_secure_profile",
162	246	"selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675",
163	247	"noNewPrivileges": true,
164		"capabilities": [
165		"CAP_AUDIT_WRITE",
166		"CAP_KILL",
167		"CAP_NET_BIND_SERVICE"
168		],
	248	"capabilities": {
	249	"bounding": [
	250	"CAP_AUDIT_WRITE",
	251	"CAP_KILL",
	252	"CAP_NET_BIND_SERVICE"
	253	],
	254	"permitted": [
	255	"CAP_AUDIT_WRITE",
	256	"CAP_KILL",
	257	"CAP_NET_BIND_SERVICE"
	258	],
	259	"inheritable": [
	260	"CAP_AUDIT_WRITE",
	261	"CAP_KILL",
	262	"CAP_NET_BIND_SERVICE"
	263	],
	264	"effective": [
	265	"CAP_AUDIT_WRITE",
	266	"CAP_KILL"
	267	],
	268	"ambient": [
	269	"CAP_NET_BIND_SERVICE"
	270	]
	271	},
169	272	"rlimits": [
170	273	{
171	274	"type": "RLIMIT_NOFILE",

200	303	}
201	304	```
202	305
203		#### Windows User
	306	#### <a name="configWindowsUser" />Windows User
204	307
205	308	For Windows based systems the user structure has the following fields:
206	309

225	328	```
226	329
227	330
228		## Hostname
229
230		* `hostname` (string, OPTIONAL) configures the container's hostname as seen by processes running inside the container.
231		On Linux, you can only set this if your bundle creates a new [UTS namespace][uts-namespace].
	331	## <a name="configHostname" />Hostname
	332
	333	* `hostname` (string, OPTIONAL) specifies the container's hostname as seen by processes running inside the container.
	334	On Linux, for example, this will change the hostname in the [container](glossary.md#container-namespace) [UTS namespace][uts-namespace.7].
	335	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].
232	336
233	337	### Example
234	338

236	340	"hostname": "mrsdalloway"
237	341	```
238	342
239		## Platform
240
241		`platform` specifies the configuration's target platform.
242
243		* `os` (string, REQUIRED) specifies the operating system family this image targets.
244		The runtime MUST generate an error if it does not support the configured `os`.
245		Bundles SHOULD use, and runtimes SHOULD understand, `os` entries listed in the Go Language document for [`$GOOS`][go-environment].
246		If an operating system is not included in the `$GOOS` documentation, it SHOULD be submitted to this specification for standardization.
247		* `arch` (string, REQUIRED) specifies the instruction set for which the binaries in the image have been compiled.
248		The runtime MUST generate an error if it does not support the configured `arch`.
249		Values for `arch` SHOULD use, and runtimes SHOULD understand, `arch` entries listed in the Go Language document for [`$GOARCH`][go-environment].
250		If an architecture is not included in the `$GOARCH` documentation, it SHOULD be submitted to this specification for standardization.
251
252		### Example
253
254		```json
255		"platform": {
256		"os": "linux",
257		"arch": "amd64"
258		}
259		```
260
261		## Platform-specific configuration
262
263		[`platform.os`](#platform) is used to lookup further platform-specific configuration.
	343	## <a name="configPlatformSpecificConfiguration" />Platform-specific configuration
264	344
265	345	* `linux` (object, OPTIONAL) [Linux-specific configuration](config-linux.md).
266		This SHOULD only be set if `platform.os` is `linux`.
	346	This MAY be set if the target platform of this spec is `linux`.
	347	* `windows` (object, OPTIONAL) [Windows-specific configuration](config-windows.md).
	348	This MUST be set if the target platform of this spec is `windows`.
267	349	* `solaris` (object, OPTIONAL) [Solaris-specific configuration](config-solaris.md).
268		This SHOULD only be set if `platform.os` is `solaris`.
269		* `windows` (object, optional) [Windows-specific configuration](config-windows.md).
270		This SHOULD only be set if `platform.os` is `windows`.
	350	This MAY be set if the target platform of this spec is `solaris`.
271	351
272	352	### Example (Linux)
273	353
274	354	```json
275	355	{
276		"platform": {
277		"os": "linux",
278		"arch": "amd64"
279		},
280	356	"linux": {
281	357	"namespaces": [
282		{
283		"type": "pid"
284		}
	358	{
	359	"type": "pid"
	360	}
285	361	]
286	362	}
287	363	}
288	364	```
289	365
290		## Hooks
291
292		`hooks` (object, OPTIONAL) configures callbacks for container lifecycle events.
293		Lifecycle hooks allow custom events for different points in a container's runtime.
294		Presently there are `Prestart`, `Poststart` and `Poststop`.
295
296		* [`Prestart`](#prestart) is a list of hooks to be run before the container process is executed
297		* [`Poststart`](#poststart) is a list of hooks to be run immediately after the container process is started
298		* [`Poststop`](#poststop) is a list of hooks to be run after the container process exits
299
300		Hooks allow one to run code before/after various lifecycle events of the container.
	366	## <a name="configHooks" />POSIX-platform Hooks
	367
	368	For POSIX platforms, the configuration structure supports `hooks` for configuring custom actions related to the [lifecycle](runtime.md#lifecycle) of the container.
	369
	370	* `hooks` (object, OPTIONAL) MAY contain any of the following properties:
	371	* `prestart` (array of objects, OPTIONAL) is an array of [pre-start hooks](#prestart).
	372	Entries in the array contain the following properties:
	373	* `path` (string, REQUIRED) with similar semantics to [IEEE Std 1003.1-2008 `execv`'s path][ieee-1003.1-2008-functions-exec].
	374	This specification extends the IEEE standard in that `path` MUST be absolute.
	375	* `args` (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008 `execv`'s argv][ieee-1003.1-2008-functions-exec].
	376	* `env` (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008's `environ`][ieee-1003.1-2008-xbd-c8.1].
	377	* `timeout` (int, OPTIONAL) is the number of seconds before aborting the hook.
	378	If set, `timeout` MUST be greater than zero.
	379	* `poststart` (array of objects, OPTIONAL) is an array of [post-start hooks](#poststart).
	380	Entries in the array have the same schema as pre-start entries.
	381	* `poststop` (array of objects, OPTIONAL) is an array of [post-stop hooks](#poststop).
	382	Entries in the array have the same schema as pre-start entries.
	383
	384	Hooks allow users to specify programs to run before or after various lifecycle events.
301	385	Hooks MUST be called in the listed order.
302		The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work.
303
304		Hook paths are absolute and are executed from the host's filesystem in the [runtime namespace][runtime-namespace].
305
306		### Prestart
307
308		The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed.
309		They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container.
310		In Linux, for e.g., the network namespace could be configured in this hook.
311
312		If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down.
313
314		### Poststart
315
316		The post-start hooks are called after the user process is started.
317		For example this hook can notify user that real process is spawned.
318
319		If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
320
321		### Poststop
322
323		The post-stop hooks are called after the container process is stopped.
324		Cleanup or debugging could be performed in such a hook.
325		If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
	386	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.
	387
	388	### <a name="configHooksPrestart" />Prestart
	389
	390	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).
	391	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).
	392
	393	### <a name="configHooksPoststart" />Poststart
	394
	395	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.
	396	For example, this hook can notify the user that the container process is spawned.
	397
	398	### <a name="configHooksPoststop" />Poststop
	399
	400	The post-stop hooks MUST be called [after the container is deleted](runtime.md#lifecycle) but before the [`delete`](runtime.md#delete) operation returns.
	401	Cleanup or debugging functions are examples of such a hook.
326	402
327	403	### Example
328	404

353	429	}
354	430	```
355	431
356		`path` is REQUIRED for a hook.
357		`args` and `env` are OPTIONAL.
358		`timeout` is the number of seconds before aborting the hook.
359		The semantics are the same as `Path`, `Args` and `Env` in [golang Cmd](https://golang.org/pkg/os/exec/#Cmd).
360
361		## Annotations
	432	## <a name="configAnnotations" />Annotations
362	433
363	434	`annotations` (object, OPTIONAL) contains arbitrary metadata for the container.
364		This information MAY be structured or unstructured.
365		Annotations MUST be a key-value map where both the key and value MUST be strings.
366		While the value MUST be present, it MAY be an empty string.
367		Keys MUST be unique within this map, and best practice is to namespace the keys.
368		Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`.
369		Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by subsequent specifications.
370		If there are no annotations then this property MAY either be absent or an empty map.
371		Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown annotation key.
	435	This information MAY be structured or unstructured.
	436	Annotations MUST be a key-value map.
	437	If there are no annotations then this property MAY either be absent or an empty map.
	438
	439	Keys MUST be strings.
	440	Keys MUST NOT be an empty string.
	441	Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`.
	442	Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by subsequent specifications.
	443	Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown annotation key.
	444
	445	Values MUST be strings.
	446	Values MAY be an empty string.
372	447
373	448	```json
374	449	"annotations": {

376	451	}
377	452	```
378	453
379		## Extensibility
380		Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown property.
	454	## <a name="configExtensibility" />Extensibility
	455
	456	Runtimes that are reading or processing this configuration file MUST NOT generate an error if they encounter an unknown property.
381	457	Instead they MUST ignore unknown properties.
	458
	459	## Valid values
	460
	461	Runtimes that are reading or processing this configuration file MUST generate an error when invalid or unsupported values are encountered.
	462	Unless support for a valid value is explicitly required, runtimes MAY choose which subset of the valid values it will support.
382	463
383	464	## Configuration Schema Example
384	465

387	468	```json
388	469	{
389	470	"ociVersion": "0.5.0-dev",
390		"platform": {
391		"os": "linux",
392		"arch": "amd64"
393		},
394	471	"process": {
395	472	"terminal": true,
396	473	"user": {

409	486	"TERM=xterm"
410	487	],
411	488	"cwd": "/",
412		"capabilities": [
413		"CAP_AUDIT_WRITE",
414		"CAP_KILL",
415		"CAP_NET_BIND_SERVICE"
416		],
	489	"capabilities": {
	490	"bounding": [
	491	"CAP_AUDIT_WRITE",
	492	"CAP_KILL",
	493	"CAP_NET_BIND_SERVICE"
	494	],
	495	"permitted": [
	496	"CAP_AUDIT_WRITE",
	497	"CAP_KILL",
	498	"CAP_NET_BIND_SERVICE"
	499	],
	500	"inheritable": [
	501	"CAP_AUDIT_WRITE",
	502	"CAP_KILL",
	503	"CAP_NET_BIND_SERVICE"
	504	],
	505	"effective": [
	506	"CAP_AUDIT_WRITE",
	507	"CAP_KILL"
	508	],
	509	"ambient": [
	510	"CAP_NET_BIND_SERVICE"
	511	]
	512	},
417	513	"rlimits": [
418	514	{
419	515	"type": "RLIMIT_CORE",

427	523	}
428	524	],
429	525	"apparmorProfile": "acme_secure_profile",
	526	"oomScoreAdj": 100,
430	527	"selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675",
431	528	"noNewPrivileges": true
432	529	},

606	703	"limit": 9223372036854772000
607	704	}
608	705	],
609		"oomScoreAdj": 100,
610	706	"memory": {
611	707	"limit": 536870912,
612	708	"reservation": 536870912,
613	709	"swap": 536870912,
614		"kernel": 0,
615		"kernelTCP": 0,
616		"swappiness": 0
	710	"kernel": -1,
	711	"kernelTCP": -1,
	712	"swappiness": 0,
	713	"disableOOMKiller": false
617	714	},
618	715	"cpu": {
619	716	"shares": 1024,

624	721	"cpus": "2-3",
625	722	"mems": "0-7"
626	723	},
627		"disableOOMKiller": false,
628	724	"devices": [
629	725	{
630	726	"allow": false,

646	742	}
647	743	],
648	744	"blockIO": {
649		"blkioWeight": 10,
650		"blkioLeafWeight": 10,
651		"blkioWeightDevice": [
	745	"weight": 10,
	746	"leafWeight": 10,
	747	"weightDevice": [
652	748	{
653	749	"major": 8,
654	750	"minor": 0,

661	757	"weight": 500
662	758	}
663	759	],
664		"blkioThrottleReadBpsDevice": [
	760	"throttleReadBpsDevice": [
665	761	{
666	762	"major": 8,
667	763	"minor": 0,
668	764	"rate": 600
669	765	}
670	766	],
671		"blkioThrottleWriteIOPSDevice": [
	767	"throttleWriteIOPSDevice": [
672	768	{
673	769	"major": 8,
674	770	"minor": 16,

681	777	"seccomp": {
682	778	"defaultAction": "SCMP_ACT_ALLOW",
683	779	"architectures": [
684		"SCMP_ARCH_X86"
	780	"SCMP_ARCH_X86",
	781	"SCMP_ARCH_X32"
685	782	],
686	783	"syscalls": [
687	784	{
688		"name": "getcwd",
	785	"names": [
	786	"getcwd",
	787	"chmod"
	788	],
689	789	"action": "SCMP_ACT_ERRNO"
690	790	}
691	791	]

736	836	}
737	837	```
738	838
739		[container-namespace]: glossary.md#container-namespace
740		[go-environment]: https://golang.org/doc/install/source#environment
741		[runtime-namespace]: glossary.md#runtime-namespace
742		[uts-namespace]: http://man7.org/linux/man-pages/man7/namespaces.7.html
	839
	840	[apparmor]: https://wiki.ubuntu.com/AppArmor
	841	[cgroup-v1-memory_2]: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt
	842	[selinux]:http://selinuxproject.org/page/Main_Page
	843	[no-new-privs]: https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt
	844	[procfs_2]: https://www.kernel.org/doc/Documentation/filesystems/proc.txt
	845	[semver-v2.0.0]: http://semver.org/spec/v2.0.0.html
	846	[ieee-1003.1-2008-xbd-c8.1]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_01
	847	[ieee-1003.1-2008-xsh-exec]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html
	848	[naming-a-volume]: https://aka.ms/nb3hqb
	849
	850	[capabilities.7]: http://man7.org/linux/man-pages/man7/capabilities.7.html
	851	[mount.2]: http://man7.org/linux/man-pages/man2/mount.2.html
	852	[mount.8]: http://man7.org/linux/man-pages/man8/mount.8.html
743	853	[mount.8-filesystem-independent]: http://man7.org/linux/man-pages/man8/mount.8.html#FILESYSTEM-INDEPENDENT_MOUNT%20OPTIONS
744	854	[mount.8-filesystem-specific]: http://man7.org/linux/man-pages/man8/mount.8.html#FILESYSTEM-SPECIFIC_MOUNT%20OPTIONS
745		[mount.8]: http://man7.org/linux/man-pages/man8/mount.8.html
	855	[getrlimit.2]: http://man7.org/linux/man-pages/man2/getrlimit.2.html
	856	[getrlimit.3]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/getrlimit.html
	857	[stdin.3]: http://man7.org/linux/man-pages/man3/stdin.3.html
	858	[uts-namespace.7]: http://man7.org/linux/man-pages/man7/namespaces.7.html
	859	[zonecfg.1m]: http://docs.oracle.com/cd/E86824_01/html/E54764/zonecfg-1m.html

+14

-12

glossary.md less more

0		# Glossary
	0	# <a name="glossary" />Glossary
1	1
2		## Bundle
	2	## <a name="glossaryBundle" />Bundle
3	3
4	4	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.
5	5
6		## Configuration
	6	## <a name="glossaryConfiguration" />Configuration
7	7
8	8	The [`config.json`](config.md) file in a [bundle](#bundle) which defines the intended [container](#container) and container process.
9	9
10		## Container
	10	## <a name="glossaryContainer" />Container
11	11
12	12	An environment for executing processes with configurable isolation and resource limitations.
13	13	For example, namespaces, resource limits, and mounts are all part of the container environment.
14	14
15		## Container namespace
	15	## <a name="glossaryContainerNamespace" />Container namespace
16	16
17		On Linux, a leaf in the [namespace][namespaces.7] hierarchy in which the [configured process](config.md#process-configuration) executes.
	17	On Linux,the [namespaces][namespaces.7] in which the [configured process](config.md#process) executes.
18	18
19		## JSON
	19	## <a name="glossaryJson" />JSON
20	20
21	21	All configuration [JSON][] MUST be encoded in [UTF-8][].
	22	JSON objects MUST NOT include duplicate names.
	23	The order of entries in JSON objects is not significant.
22	24
23		## Runtime
	25	## <a name="glossaryRuntime" />Runtime
24	26
25	27	An implementation of this specification.
26	28	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).
27	29
28		## Runtime namespace
	30	## <a name="glossaryRuntimeNamespace" />Runtime namespace
29	31
30		On Linux, a leaf in the [namespace][namespaces.7] hierarchy from which the [runtime](#runtime) process is executed.
31		New container namespaces will be created as children of the runtime namespaces.
	32	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.
32	33
33		[JSON]: http://json.org/
	34	[JSON]: https://tools.ietf.org/html/rfc7159
34	35	[UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf
	36
35	37	[namespaces.7]: http://man7.org/linux/man-pages/man7/namespaces.7.html

+18

-10

implementations.md less more

0		# Implementations
	0	# <a name="implementations" />Implementations
1	1
2	2	The following sections link to associated projects, some of which are maintained by the OCI and some of which are maintained by external organizations.
3	3	If you know of any associated projects that are not listed here, please file a pull request adding a link to that project.
4	4
5		## Runtime (Container)
	5	## <a name="implementationsRuntimeContainer" />Runtime (Container)
6	6
7		* [opencontainers/runc](https://github.com/opencontainers/runc) - Reference implementation of OCI runtime
	7	* [opencontainers/runc][runc] - Reference implementation of OCI runtime
8	8
9		## Runtime (Virtual Machine)
	9	## <a name="implementationsRuntimeVirtualMachine" />Runtime (Virtual Machine)
10	10
11		* [hyperhq/runv](https://github.com/hyperhq/runv) - Hypervisor-based runtime for OCI
12		* [01org/cc-oci-runtime](https://github.com/01org/cc-oci-runtime) - Hypervisor-based OCI runtime for Intel® Architecture
	11	* [hyperhq/runv][runv] - Hypervisor-based runtime for OCI
	12	* [01org/cc-oci-runtime][cc-oci] - Hypervisor-based OCI runtime for Intel® Architecture
13	13
14		## Testing & Tools
	14	## <a name="implementationsTestingTools" />Testing & Tools
15	15
16		* [kunalkushwaha/octool](https://github.com/kunalkushwaha/octool) - A config linter and validator.
17		* [opencontainers/ocitools](https://github.com/opencontainers/ocitools) - A config generator and runtime/bundle testing framework.
18		* [huawei-openlab/oct](https://github.com/huawei-openlab/oct) - Open Container Testing framework for OCI configuration and runtime
	16	* [kunalkushwaha/octool][octool] - A config linter and validator.
	17	* [huawei-openlab/oct][oct] - Open Container Testing framework for OCI configuration and runtime
	18	* [opencontainers/runtime-tools][runtime-tools] - A config generator and runtime/bundle testing framework.
	19
	20
	21	[runc]: https://github.com/opencontainers/runc
	22	[runv]: https://github.com/hyperhq/runv
	23	[cc-oci]: https://github.com/01org/cc-oci-runtime
	24	[octool]: https://github.com/kunalkushwaha/octool
	25	[oct]: https://github.com/huawei-openlab/oct
	26	[runtime-tools]: https://github.com/opencontainers/runtime-tools

+52

-0

meeting.ics less more

	0	BEGIN:VCALENDAR
	1	VERSION:2.0
	2	PRODID:-//Open Containers Initiative//Developer Meeting//EN
	3	BEGIN:VTIMEZONE
	4	TZID:America/Los_Angeles
	5	LAST-MODIFIED:20050809T050000Z
	6	BEGIN:STANDARD
	7	DTSTART:20071104T020000
	8	RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU
	9	TZOFFSETFROM:-0700
	10	TZOFFSETTO:-0800
	11	TZNAME:PST
	12	END:STANDARD
	13	BEGIN:DAYLIGHT
	14	DTSTART:20070311T020000
	15	RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU
	16	TZOFFSETFROM:-0800
	17	TZOFFSETTO:-0700
	18	TZNAME:PDT
	19	END:DAYLIGHT
	20	END:VTIMEZONE
	21	BEGIN:VEVENT
	22	UID:tdc-meeting-1@opencontainers.org
	23	DTSTAMP:20170405T220000Z
	24	DTSTART;TZID=America/Los_Angeles:20170329T080000
	25	RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=WE
	26	DURATION:PT1H
	27	SUMMARY:OCI TDC Meeting
	28	DESCRIPTION;ALTREP="https://github.com/opencontainers/runtime-spec#
	29	weekly-call":Open Containers Initiative Developer Meeting\n
	30	https://github.com/opencontainers/runtime-spec#weekly-call\n
	31	Web: https://www.uberconference.com/opencontainers\n
	32	Audio-only: +1 415 968 0849 (no PIN needed)
	33	LOCATION:https://www.uberconference.com/opencontainers
	34	URL:https://github.com/opencontainers/runtime-spec/blob/master/meeting.ics
	35	END:VEVENT
	36	BEGIN:VEVENT
	37	UID:tdc-meeting-2@opencontainers.org
	38	DTSTAMP:20170517T143500Z
	39	DTSTART;TZID=America/Los_Angeles:20170517T140000
	40	RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=WE
	41	DURATION:PT1H
	42	SUMMARY:OCI TDC Meeting
	43	DESCRIPTION;ALTREP="https://github.com/opencontainers/runtime-spec#
	44	weekly-call":Open Containers Initiative Developer Meeting\n
	45	https://github.com/opencontainers/runtime-spec#weekly-call\n
	46	Web: https://www.uberconference.com/opencontainers\n
	47	Audio-only: +1 415 968 0849 (no PIN needed)
	48	LOCATION:https://www.uberconference.com/opencontainers
	49	URL:https://github.com/opencontainers/runtime-spec/blob/master/meeting.ics
	50	END:VEVENT
	51	END:VCALENDAR

-6

principles.md less more

0		# The 5 principles of Standard Containers
	0	# <a name="the5PrinciplesOfStandardContainers" />The 5 principles of Standard Containers
1	1
2	2	Define a unit of software delivery called a Standard Container.
3	3	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.

13	13	Irrespective of their contents, by standardizing the container itself it allowed for a consistent, more streamlined and efficient set of processes to be defined.
14	14	For software Standard Containers offer similar functionality by being the fundamental, standardized, unit of delivery for a software package.
15	15
16		## 1. Standard operations
	16	## <a name="standardOperations" />1. Standard operations
17	17
18	18	Standard Containers define a set of STANDARD OPERATIONS.
19	19	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.
20	20
21		## 2. Content-agnostic
	21	## <a name="contentAgnostic" />2. Content-agnostic
22	22
23	23	Standard Containers are CONTENT-AGNOSTIC: all standard operations have the same effect regardless of the contents.
24	24	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.
25	25
26		## 3. Infrastructure-agnostic
	26	## <a name="infrastructureAgnostic" />3. Infrastructure-agnostic
27	27
28	28	Standard Containers are INFRASTRUCTURE-AGNOSTIC: they can be run in any OCI supported infrastructure.
29	29	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.
30	30
31		## 4. Designed for automation
	31	## <a name="designedForAutomation" />4. Designed for automation
32	32
33	33	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.
34	34	In fact, you could say automation is their secret weapon.

38	38	Builds failed, libraries conflicted, mirrors crashed, post-it notes were lost, logs were misplaced, cluster updates were half-broken.
39	39	The process was slow, inefficient and cost a fortune - and was entirely different depending on the language and infrastructure provider.
40	40
41		## 5. Industrial-grade delivery
	41	## <a name="industrialGradeDelivery" />5. Industrial-grade delivery
42	42
43	43	Standard Containers make INDUSTRIAL-GRADE DELIVERY of software a reality.
44	44	Leveraging all of the properties listed above, Standard Containers are enabling large and small enterprises to streamline and automate their software delivery pipelines.

-3

project.md less more

0		# Project docs
	0	# <a name="projectDocs" />Project docs
1	1
2		## Release Process
	2	## <a name="projectReleaseProcess" />Release Process
3	3
4	4	* Increment version in [`specs-go/version.go`](specs-go/version.go)
5	5	* `git commit` version increment
6	6	* `git tag` the prior commit (preferably signed tag)
7	7	* `make docs` to produce PDF and HTML copies of the spec
8		* Make a release on [github.com/opencontainers/runtime-spec](https://github.com/opencontainers/runtime-spec/releases) for the version. Attach the produced docs.
	8	* Make a [release][releases] for the version. Attach the produced docs.
9	9
	10
	11	[releases]: https://github.com/opencontainers/runtime-spec/releases

-5

runtime-linux.md less more

0		# Linux Runtime
	0	# <a name="linuxRuntime" />Linux Runtime
1	1
2		## File descriptors
	2	## <a name="runtimeLinuxFileDescriptors" />File descriptors
3	3
4	4	By default, only the `stdin`, `stdout` and `stderr` file descriptors are kept open for the application by the runtime.
5		The runtime MAY pass additional file descriptors to the application to support features such as [socket activation](http://0pointer.de/blog/projects/socket-activated-containers.html).
	5	The runtime MAY pass additional file descriptors to the application to support features such as [socket activation][socket-activated-containers].
6	6	Some of the file descriptors MAY be redirected to `/dev/null` even though they are open.
7	7
8		## Dev symbolic links
	8	## <a name="runtimeLinuxDevSymbolicLinks" /> Dev symbolic links
9	9
10		After the container has `/proc` mounted, the following standard symlinks MUST be setup within `/dev/` for the io.
	10	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):
11	11
12	12	\| Source \| Destination \|
13	13	\| --------------- \| ----------- \|

15	15	\| /proc/self/fd/0 \| /dev/stdin \|
16	16	\| /proc/self/fd/1 \| /dev/stdout \|
17	17	\| /proc/self/fd/2 \| /dev/stderr \|
	18
	19
	20	[socket-activated-containers]: http://0pointer.de/blog/projects/socket-activated-containers.html

+74

-65

runtime.md less more

0		# Runtime and Lifecycle
	0	# <a name="runtimeAndLifecycle" />Runtime and Lifecycle
1	1
2		## Scope of a Container
	2	## <a name="runtimeScopeContainer" />Scope of a Container
3	3
4		Barring access control concerns, the entity using a runtime to create a container MUST be able to use the operations defined in this specification against that same container.
	4	The entity using a runtime to create a container MUST be able to use the operations defined in this specification against that same container.
5	5	Whether other entities using the same, or other, instance of the runtime can see that container is out of scope of this specification.
6	6
7		## State
	7	## <a name="runtimeState" />State
8	8
9		The state of a container MUST include, at least, the following properties:
	9	The state of a container includes the following properties:
10	10
11		* `ociVersion`: (string) is the OCI specification version used when creating the container.
12		* `id`: (string) is the container's ID.
13		This MUST be unique across all containers on this host.
14		There is no requirement that it be unique across hosts.
15		* `status`: (string) is the runtime state of the container.
16		The value MAY be one of:
17		* `created`: the container has been created but the user-specified code has not yet been executed
18		* `running`: the container has been created and the user-specified code is running
19		* `stopped`: the container has been created and the user-specified code has been executed but is no longer running
	11	* `ociVersion` (string, REQUIRED) is the OCI specification version used when creating the container.
	12	* `id` (string, REQUIRED) is the container's ID.
	13	This MUST be unique across all containers on this host.
	14	There is no requirement that it be unique across hosts.
	15	* `status` (string, REQUIRED) is the runtime state of the container.
	16	The value MAY be one of:
20	17
21		Additional values MAY be defined by the runtime, however, they MUST be used to represent new runtime states not defined above.
22		* `pid`: (int) is the ID of the container process, as seen by the host.
23		* `bundlePath`: (string) is the absolute path to the container's bundle directory.
24		This is provided so that consumers can find the container's configuration and root filesystem on the host.
25		* `annotations`: (map) contains the list of annotations associated with the container.
26		If no annotations were provided then this property MAY either be absent or an empty map.
	18	* `creating`: the container is being created (step 2 in the [lifecycle](#lifecycle))
	19	* `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
	20	* `running`: the container process has executed the user-specified program but has not exited (after step 5 in the [lifecycle](#lifecycle))
	21	* `stopped`: the container process has exited (step 7 in the [lifecycle](#lifecycle))
	22
	23	Additional values MAY be defined by the runtime, however, they MUST be used to represent new runtime states not defined above.
	24	* `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.
	25	* `bundle` (string, REQUIRED) is the absolute path to the container's bundle directory.
	26	This is provided so that consumers can find the container's configuration and root filesystem on the host.
	27	* `annotations` (map, OPTIONAL) contains the list of annotations associated with the container.
	28	If no annotations were provided then this property MAY either be absent or an empty map.
	29
	30	The state MAY include additional properties.
27	31
28	32	When serialized in JSON, the format MUST adhere to the following pattern:
29	33

33	37	"id": "oci-container1",
34	38	"status": "running",
35	39	"pid": 4422,
36		"bundlePath": "/containers/redis",
	40	"bundle": "/containers/redis",
37	41	"annotations": {
38	42	"myKey": "myValue"
39	43	}

42	46
43	47	See [Query State](#query-state) for information on retrieving the state of a container.
44	48
45		## Lifecycle
	49	## <a name="runtimeLifecycle" />Lifecycle
46	50	The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist.
47	51
48		1. OCI compliant runtime's `create` command is invoked with a reference to the location of the bundle and a unique identifier.
	52	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.
49	53	2. The container's runtime environment MUST be created according to the configuration in [`config.json`](config.md).
50		If the runtime is unable to create the environment specified in the [`config.json`](config.md), it MUST generate an error.
51		While the resources requested in the [`config.json`](config.md) MUST be created, the user-specified code (from [`process`](config.md#process-configuration) MUST NOT be run at this time.
52		Any updates to `config.json` after this step MUST NOT affect the container.
53		3. Once the container is created additional actions MAY be performed based on the features the runtime chooses to support.
54		However, some actions might only be available based on the current state of the container (e.g. only available while it is started).
55		4. Runtime's `start` command is invoked with the unique identifier of the container.
56		The runtime MUST run the user-specified code, as specified by [`process`](config.md#process-configuration).
57		5. The container's process is stopped.
58		This MAY happen due to them erroring out, exiting, crashing or the runtime's `kill` operation being invoked.
59		6. Runtime's `delete` command is invoked with the unique identifier of the container.
60		The container MUST be destroyed by undoing the steps performed during create phase (step 2).
	54	If the runtime is unable to create the environment specified in the [`config.json`](config.md), it MUST [generate an error](#errors).
	55	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.
	56	Any updates to [`config.json`](config.md) after this step MUST NOT affect the container.
	57	3. Runtime's [`start`](runtime.md#start) command is invoked with the unique identifier of the container.
	58	4. The [prestart hooks](config.md#prestart) MUST be invoked by the runtime.
	59	If any prestart hook fails, the runtime MUST [generate an error](#errors), stop the container, and continue the lifecycle at step 9.
	60	5. The runtime MUST run the user-specified program, as specified by [`process`](config.md#process).
	61	6. The [poststart hooks](config.md#poststart) MUST be invoked by the runtime.
	62	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.
	63	7. The container process exits.
	64	This MAY happen due to erroring out, exiting, crashing or the runtime's [`kill`](runtime.md#kill) operation being invoked.
	65	8. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container.
	66	9. The container MUST be destroyed by undoing the steps performed during create phase (step 2).
	67	10. The [poststop hooks](config.md#poststop) MUST be invoked by the runtime.
	68	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.
61	69
62		## Errors
	70	## <a name="runtimeErrors" />Errors
63	71
64	72	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.
65	73	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.
66	74
67		## Operations
	75	## <a name="runtimeWarnings" />Warnings
68	76
69		OCI compliant runtimes MUST support the following operations, unless the operation is not supported by the base operating system.
	77	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.
	78	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.
70	79
71		Note: these operations are not specifying any command-line APIs, and the paramenters are inputs for general operations.
	80	## <a name="runtimeOperations" />Operations
72	81
73		### Query State
	82	Unless otherwise stated, runtimes MUST support the following operations.
	83
	84	Note: these operations are not specifying any command-line APIs, and the parameters are inputs for general operations.
	85
	86	### <a name="runtimeQueryState" />Query State
74	87
75	88	`state <container-id>`
76	89
77		This operation MUST generate an error if it is not provided the ID of a container.
78		Attempting to query a container that does not exist MUST generate an error.
	90	This operation MUST [generate an error](#errors) if it is not provided the ID of a container.
	91	Attempting to query a container that does not exist MUST [generate an error](#errors).
79	92	This operation MUST return the state of a container as specified in the [State](#state) section.
80	93
81		### Create
	94	### <a name="runtimeCreate" />Create
82	95
83	96	`create <container-id> <path-to-bundle>`
84	97
85		This operation MUST generate an error if it is not provided a path to the bundle and the container ID to associate with the container.
86		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 and a new container MUST NOT be created.
87		Using the data in [`config.json`](config.md), this operation MUST create a new container.
88		This means that all of the resources associated with the container MUST be created, however, the user-specified code MUST NOT be run at this time.
89		If the runtime cannot create the container as specified in `config.md`, it MUST generate an error and a new container MUST NOT be created.
	98	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.
	99	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.
	100	This operation MUST create a new container.
90	101
91		Upon successful completion of this operation the `status` property of this container MUST be `created`.
	102	All of the properties configured in [`config.json`](config.md) except for [`process`](config.md#process) MUST be applied.
	103	[`process.args`](config.md#process) MUST NOT be applied until triggered by the [`start`](#start) operation.
	104	The remaining `process` properties MAY be applied by this operation.
	105	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.
92	106
93	107	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)).
94	108	Runtime callers who are interested in pre-create validation can run [bundle-validation tools](implementations.md#testing--tools) before invoking the create operation.
95	109
96	110	Any changes made to the [`config.json`](config.md) file after this operation will not have an effect on the container.
97	111
98		### Start
	112	### <a name="runtimeStart" />Start
99	113	`start <container-id>`
100	114
101		This operation MUST generate an error if it is not provided the container ID.
102		Attempting to start a container that does not exist MUST generate an error.
103		Attempting to start an already started container MUST have no effect on the container and MUST generate an error.
104		This operation MUST run the user-specified code as specified by [`process`](config.md#process-configuration).
	115	This operation MUST [generate an error](#errors) if it is not provided the container ID.
	116	Attempting to `start` a container that is not [`created`](#state) MUST have no effect on the container and MUST [generate an error](#errors).
	117	This operation MUST run the user-specified program as specified by [`process`](config.md#process).
	118	This operation MUST generate an error if `process` was not set.
105	119
106		Upon successful completion of this operation the `status` property of this container MUST be `running`.
107
108		### Kill
	120	### <a name="runtimeKill" />Kill
109	121	`kill <container-id> <signal>`
110	122
111		This operation MUST generate an error if it is not provided the container ID.
112		Attempting to send a signal to a container that is not running MUST have no effect on the container and MUST generate an error.
	123	This operation MUST [generate an error](#errors) if it is not provided the container ID.
	124	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).
113	125	This operation MUST send the specified signal to the process in the container.
114	126
115		When the process in the container is stopped, irrespective of it being as a result of a `kill` operation or any other reason, the `status` property of this container MUST be `stopped`.
116
117		### Delete
	127	### <a name="runtimeDelete" />Delete
118	128	`delete <container-id>`
119	129
120		This operation MUST generate an error if it is not provided the container ID.
121		Attempting to delete a container that does not exist MUST generate an error.
122		Attempting to delete a container whose process is still running MUST generate an error.
	130	This operation MUST [generate an error](#errors) if it is not provided the container ID.
	131	Attempting to `delete` a container that is not [`stopped`](#state) MUST have no effect on the container and MUST [generate an error](#errors).
123	132	Deleting a container MUST delete the resources that were created during the `create` step.
124	133	Note that resources associated with the container, but not created by this container, MUST NOT be deleted.
125	134	Once a container is deleted its ID MAY be used by a subsequent container.
126	135
127	136
128		## Hooks
	137	## <a name="runtimeHooks" />Hooks
129	138	Many of the operations specified in this specification have "hooks" that allow for additional actions to be taken before or after each operation.
130	139	See [runtime configuration for hooks](./config.md#hooks) for more information.

+37

-3

schema/Makefile less more

	0	GOOD_TESTS = $(wildcard test/good/*.json)
	1	BAD_TESTS = $(wildcard test/bad/*.json)
0	2
1		default: help
	3	default: validate
2	4
3	5	help:
4		@echo "Usage: make <target>"
	6	@echo "Usage: make [target]"
5	7	@echo
6	8	@echo " * 'fmt' - format the json with indentation"
	9	@echo " * 'help' - show this help information"
7	10	@echo " * 'validate' - build the validation tool"
8	11
9	12	fmt:
10		for i in *.json ; do jq --indent 4 -M . "$${i}" > xx && cat xx > "$${i}" && rm xx ; done
	13	find . -name '*.json' -exec bash -c 'jq --indent 4 -M . {} > xx && mv xx {} \|\| echo "skipping invalid {}"' \;
11	14
	15	.PHONY: validate
12	16	validate: validate.go
13	17	go get -d ./...
14	18	go build ./validate.go
15	19
	20	test: validate $(TESTS)
	21	for TYPE in $$(ls test); \
	22	do \
	23	echo "testing $${TYPE}"; \
	24	for FILE in $$(ls "test/$${TYPE}/good"); \
	25	do \
	26	echo " testing test/$${TYPE}/good/$${FILE}"; \
	27	if ./validate "$${TYPE}-schema.json" "test/$${TYPE}/good/$${FILE}" ; \
	28	then \
	29	echo " received expected validation success" ; \
	30	else \
	31	echo " received unexpected validation failure" ; \
	32	exit 1; \
	33	fi \
	34	done; \
	35	for FILE in $$(ls "test/$${TYPE}/bad"); \
	36	do \
	37	echo " testing test/$${TYPE}/bad/$${FILE}"; \
	38	if ./validate "$${TYPE}-schema.json" "test/$${TYPE}/good/$${FILE}" ; \
	39	then \
	40	echo " received unexpected validation success" ; \
	41	exit 1; \
	42	else \
	43	echo " received expected validation failure" ; \
	44	fi \
	45	done; \
	46	done
	47
	48	clean:
	49	rm -f validate

-0

schema/README.md less more

38	38	```bash
39	39	./validate config-schema.json <yourpath>/config.json
40	40	```
	41
	42	Or like:
	43
	44	```bash
	45	./validate https://raw.githubusercontent.com/opencontainers/runtime-spec/v1.0.0/schema/schema.json <yourpath>/config.json
	46	```

+115

-199

schema/config-linux.json less more

5	5	"properties": {
6	6	"devices": {
7	7	"id": "https://opencontainers.org/schema/bundle/linux/devices",
8		"oneOf": [
9		{
10		"type": "array",
11		"items": {
12		"$ref": "defs-linux.json#/definitions/Device"
13		}
14		},
15		{
16		"type": "null"
17		}
18		]
	8	"type": "array",
	9	"items": {
	10	"$ref": "defs-linux.json#/definitions/Device"
	11	}
19	12	},
20	13	"uidMappings": {
21	14	"id": "https://opencontainers.org/schema/bundle/linux/uidMappings",
22		"oneOf": [
23		{
24		"type": "array",
25		"items": {
26		"$ref": "defs.json#/definitions/IDMapping"
27		}
28		},
29		{
30		"type": "null"
31		}
32		]
	15	"type": "array",
	16	"items": {
	17	"$ref": "defs.json#/definitions/IDMapping"
	18	}
33	19	},
34	20	"gidMappings": {
35	21	"id": "https://opencontainers.org/schema/bundle/linux/gidMappings",
36		"oneOf": [
37		{
38		"type": "array",
39		"items": {
40		"$ref": "defs.json#/definitions/IDMapping"
41		}
42		},
43		{
44		"type": "null"
45		}
46		]
	22	"type": "array",
	23	"items": {
	24	"$ref": "defs.json#/definitions/IDMapping"
	25	}
47	26	},
48	27	"namespaces": {
49	28	"id": "https://opencontainers.org/schema/bundle/linux/namespaces",

62	41	"properties": {
63	42	"devices": {
64	43	"id": "https://opencontainers.org/schema/bundle/linux/resources/devices",
65		"oneOf": [
66		{
67		"type": "array",
68		"items": {
69		"$ref": "defs-linux.json#/definitions/DeviceCgroup"
70		}
71		},
72		{
73		"type": "null"
74		}
75		]
76		},
77		"oomScoreAdj": {
78		"id": "https://opencontainers.org/schema/bundle/linux/resources/oomScoreAdj",
79		"type": "integer",
80		"minimum": -1000,
81		"maximum": 1000
	44	"type": "array",
	45	"items": {
	46	"$ref": "defs-linux.json#/definitions/DeviceCgroup"
	47	}
82	48	},
83	49	"pids": {
84	50	"id": "https://opencontainers.org/schema/bundle/linux/resources/pids",

88	54	"id": "https://opencontainers.org/schema/bundle/linux/resources/pids/limit",
89	55	"$ref": "defs.json#/definitions/int64"
90	56	}
91		}
	57	},
	58	"required": [
	59	"limit"
	60	]
92	61	},
93	62	"blockIO": {
94	63	"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO",
95	64	"type": "object",
96	65	"properties": {
97		"blkioWeight": {
98		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioWeight",
99		"$ref": "defs-linux.json#/definitions/blkioWeightPointer"
100		},
101		"blkioLeafWeight": {
102		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioLeafWeight",
103		"$ref": "defs-linux.json#/definitions/blkioWeightPointer"
104		},
105		"blkioThrottleReadBpsDevice": {
106		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioThrottleReadBpsDevice",
107		"oneOf": [
108		{
109		"type": "array",
110		"items": [
111		{
112		"$ref": "defs-linux.json#/definitions/blockIODeviceThrottlePointer"
113		}
114		]
115		},
116		{
117		"type": "null"
118		}
119		]
120		},
121		"blkioThrottleWriteBpsDevice": {
122		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioThrottleWriteBpsDevice",
123		"oneOf": [
124		{
125		"type": "array",
126		"items": {
127		"$ref": "defs-linux.json#/definitions/blockIODeviceThrottlePointer"
128		}
129		},
130		{
131		"type": "null"
132		}
133		]
134		},
135		"blkioThrottleReadIopsDevice": {
136		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioThrottleReadIopsDevice",
137		"oneOf": [
138		{
139		"type": "array",
140		"items": {
141		"$ref": "defs-linux.json#/definitions/blockIODeviceThrottlePointer"
142		}
143		},
144		{
145		"type": "null"
146		}
147		]
148		},
149		"blkioThrottleWriteIopsDevice": {
150		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioThrottleWriteIopsDevice",
151		"oneOf": [
152		{
153		"type": "array",
154		"items": {
155		"$ref": "defs-linux.json#/definitions/blockIODeviceThrottlePointer"
156		}
157		},
158		{
159		"type": "null"
160		}
161		]
162		},
163		"blkioWeightDevice": {
164		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioWeightDevice",
165		"type": "array",
166		"items": {
167		"$ref": "defs-linux.json#/definitions/blockIODeviceWeightPointer"
	66	"weight": {
	67	"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/weight",
	68	"$ref": "defs-linux.json#/definitions/weight"
	69	},
	70	"leafWeight": {
	71	"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/leafWeight",
	72	"$ref": "defs-linux.json#/definitions/weight"
	73	},
	74	"throttleReadBpsDevice": {
	75	"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/throttleReadBpsDevice",
	76	"type": "array",
	77	"items": {
	78	"$ref": "defs-linux.json#/definitions/blockIODeviceThrottle"
	79	}
	80	},
	81	"throttleWriteBpsDevice": {
	82	"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/throttleWriteBpsDevice",
	83	"type": "array",
	84	"items": {
	85	"$ref": "defs-linux.json#/definitions/blockIODeviceThrottle"
	86	}
	87	},
	88	"throttleReadIopsDevice": {
	89	"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/throttleReadIopsDevice",
	90	"type": "array",
	91	"items": {
	92	"$ref": "defs-linux.json#/definitions/blockIODeviceThrottle"
	93	}
	94	},
	95	"throttleWriteIopsDevice": {
	96	"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/throttleWriteIopsDevice",
	97	"type": "array",
	98	"items": {
	99	"$ref": "defs-linux.json#/definitions/blockIODeviceThrottle"
	100	}
	101	},
	102	"weightDevice": {
	103	"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/weightDevice",
	104	"type": "array",
	105	"items": {
	106	"$ref": "defs-linux.json#/definitions/blockIODeviceWeight"
168	107	}
169	108	}
170	109	}

175	114	"properties": {
176	115	"cpus": {
177	116	"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/cpus",
178		"$ref": "defs.json#/definitions/stringPointer"
	117	"type": "string"
179	118	},
180	119	"mems": {
181	120	"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/mems",
182		"$ref": "defs.json#/definitions/stringPointer"
	121	"type": "string"
183	122	},
184	123	"period": {
185	124	"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/period",
186		"$ref": "defs.json#/definitions/uint64Pointer"
	125	"$ref": "defs.json#/definitions/uint64"
187	126	},
188	127	"quota": {
189	128	"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/quota",
190		"$ref": "defs.json#/definitions/uint64Pointer"
	129	"$ref": "defs.json#/definitions/int64"
191	130	},
192	131	"realtimePeriod": {
193	132	"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/realtimePeriod",
194		"$ref": "defs.json#/definitions/uint64Pointer"
	133	"$ref": "defs.json#/definitions/uint64"
195	134	},
196	135	"realtimeRuntime": {
197	136	"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/realtimeRuntime",
198		"$ref": "defs.json#/definitions/uint64Pointer"
	137	"$ref": "defs.json#/definitions/int64"
199	138	},
200	139	"shares": {
201	140	"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/shares",
202		"$ref": "defs.json#/definitions/uint64Pointer"
203		}
204		}
205		},
206		"disableOOMKiller": {
207		"id": "https://opencontainers.org/schema/bundle/linux/resources/disableOOMKiller",
208		"type": "boolean"
	141	"$ref": "defs.json#/definitions/uint64"
	142	}
	143	}
209	144	},
210	145	"hugepageLimits": {
211	146	"id": "https://opencontainers.org/schema/bundle/linux/resources/hugepageLimits",
212		"oneOf": [
213		{
214		"type": "array",
215		"items": {
216		"type": "object",
217		"properties": {
218		"pageSize": {
219		"type": "string"
220		},
221		"limit": {
222		"$ref": "defs.json#/definitions/uint64"
223		}
224		}
225		}
226		},
227		{
228		"type": "null"
229		}
230		]
	147	"type": "array",
	148	"items": {
	149	"type": "object",
	150	"properties": {
	151	"pageSize": {
	152	"type": "string"
	153	},
	154	"limit": {
	155	"$ref": "defs.json#/definitions/uint64"
	156	}
	157	},
	158	"required": [
	159	"pageSize",
	160	"limit"
	161	]
	162	}
231	163	},
232	164	"memory": {
233	165	"id": "https://opencontainers.org/schema/bundle/linux/resources/memory",

235	167	"properties": {
236	168	"kernel": {
237	169	"id": "https://opencontainers.org/schema/bundle/linux/resources/memory/kernel",
238		"$ref": "defs.json#/definitions/uint64Pointer"
	170	"$ref": "defs.json#/definitions/int64"
	171	},
	172	"kernelTCP": {
	173	"id": "https://opencontainers.org/schema/bundle/linux/resources/memory/kernelTCP",
	174	"$ref": "defs.json#/definitions/int64"
239	175	},
240	176	"limit": {
241	177	"id": "https://opencontainers.org/schema/bundle/linux/resources/memory/limit",
242		"$ref": "defs.json#/definitions/uint64Pointer"
	178	"$ref": "defs.json#/definitions/int64"
243	179	},
244	180	"reservation": {
245	181	"id": "https://opencontainers.org/schema/bundle/linux/resources/memory/reservation",
246		"$ref": "defs.json#/definitions/uint64Pointer"
	182	"$ref": "defs.json#/definitions/int64"
247	183	},
248	184	"swap": {
249	185	"id": "https://opencontainers.org/schema/bundle/linux/resources/memory/swap",
250		"$ref": "defs.json#/definitions/uint64Pointer"
	186	"$ref": "defs.json#/definitions/int64"
251	187	},
252	188	"swappiness": {
253	189	"id": "https://opencontainers.org/schema/bundle/linux/resources/memory/swappiness",
254		"$ref": "defs.json#/definitions/uint64Pointer"
	190	"$ref": "defs.json#/definitions/uint64"
	191	},
	192	"disableOOMKiller": {
	193	"id": "https://opencontainers.org/schema/bundle/linux/resources/memory/disableOOMKiller",
	194	"type": "boolean"
255	195	}
256	196	}
257	197	},

265	205	},
266	206	"priorities": {
267	207	"id": "https://opencontainers.org/schema/bundle/linux/resources/network/priorities",
268		"oneOf": [
269		{
270		"type": "array",
271		"items": {
272		"$ref": "defs-linux.json#/definitions/NetworkInterfacePriority"
273		}
274		},
275		{
276		"type": "null"
277		}
278		]
	208	"type": "array",
	209	"items": {
	210	"$ref": "defs-linux.json#/definitions/NetworkInterfacePriority"
	211	}
279	212	}
280	213	}
281	214	}
282	215	}
283	216	},
284	217	"cgroupsPath": {
285		"oneOf": [
286		{
287		"type": "null"
288		},
289		{
290		"type": "string"
291		}
292		]
	218	"id": "https://opencontainers.org/schema/bundle/linux/cgroupsPath",
	219	"type": "string"
293	220	},
294	221	"rootfsPropagation": {
295	222	"id": "https://opencontainers.org/schema/bundle/linux/rootfsPropagation",
296		"type": "string"
	223	"$ref": "defs-linux.json#/definitions/RootfsPropagation"
297	224	},
298	225	"seccomp": {
299	226	"id": "https://opencontainers.org/schema/bundle/linux/seccomp",

305	232	},
306	233	"architectures": {
307	234	"id": "https://opencontainers.org/schema/bundle/linux/seccomp/architectures",
308		"oneOf": [
309		{
310		"type": "array",
311		"items": {
312		"$ref": "defs-linux.json#/definitions/SeccompArch"
313		}
314		},
315		{
316		"type": "null"
317		}
318		]
	235	"type": "array",
	236	"items": {
	237	"$ref": "defs-linux.json#/definitions/SeccompArch"
	238	}
319	239	},
320	240	"syscalls": {
321	241	"id": "https://opencontainers.org/schema/bundle/linux/seccomp/syscalls",

324	244	"$ref": "defs-linux.json#/definitions/Syscall"
325	245	}
326	246	}
327		}
	247	},
	248	"required": [
	249	"defaultAction"
	250	]
328	251	},
329	252	"sysctl": {
330	253	"id": "https://opencontainers.org/schema/bundle/linux/sysctl",
331		"oneOf": [
332		{
333		"$ref": "defs.json#/definitions/mapStringString"
334		},
335		{
336		"type": "null"
337		}
338		]
	254	"$ref": "defs.json#/definitions/mapStringString"
339	255	},
340	256	"maskedPaths": {
341	257	"id": "https://opencontainers.org/schema/bundle/linux/maskedPaths",

+72

-27

schema/config-schema.json less more

36	36	"$ref": "defs.json#/definitions/Mount"
37	37	}
38	38	},
39		"platform": {
40		"id": "https://opencontainers.org/schema/bundle/platform",
41		"type": "object",
42		"required": [
43		"arch",
44		"os"
45		],
46		"properties": {
47		"arch": {
48		"id": "https://opencontainers.org/schema/bundle/platform/arch",
49		"type": "string"
50		},
51		"os": {
52		"id": "https://opencontainers.org/schema/bundle/platform/os",
53		"type": "string"
54		}
55		}
56		},
57	39	"root": {
58	40	"description": "Configures the container's root filesystem.",
59	41	"id": "https://opencontainers.org/schema/bundle/root",
60	42	"type": "object",
	43	"required": [
	44	"path"
	45	],
61	46	"properties": {
62	47	"path": {
63	48	"id": "https://opencontainers.org/schema/bundle/root/path",

81	66	"id": "https://opencontainers.org/schema/bundle/process/args",
82	67	"$ref": "defs.json#/definitions/ArrayOfStrings"
83	68	},
	69	"consoleSize": {
	70	"id": "https://opencontainers.org/schema/bundle/process/consoleSize",
	71	"type": "object",
	72	"required": [
	73	"height",
	74	"width"
	75	],
	76	"properties": {
	77	"height": {
	78	"id": "https://opencontainers.org/schema/bundle/process/consoleSize/height",
	79	"$ref": "defs.json#/definitions/uint64"
	80	},
	81	"width": {
	82	"id": "https://opencontainers.org/schema/bundle/process/consoleSize/width",
	83	"$ref": "defs.json#/definitions/uint64"
	84	}
	85	}
	86	},
84	87	"cwd": {
85	88	"id": "https://opencontainers.org/schema/bundle/process/cwd",
86	89	"type": "string"

108	111	"additionalGids": {
109	112	"id": "https://opencontainers.org/schema/bundle/process/user/additionalGids",
110	113	"$ref": "defs.json#/definitions/ArrayOfGIDs"
	114	},
	115	"username": {
	116	"id": "https://opencontainers.org/schema/bundle/process/user/username",
	117	"type": "string"
111	118	}
112	119	}
113	120	},
114	121	"capabilities": {
115	122	"id": "https://opencontainers.org/schema/bundle/process/linux/capabilities",
116		"type": "array",
117		"items": {
118		"$ref": "defs-linux.json#/definitions/Capability"
	123	"type": "object",
	124	"properties": {
	125	"bounding": {
	126	"id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/bounding",
	127	"type": "array",
	128	"items": {
	129	"type": "string"
	130	}
	131	},
	132	"permitted": {
	133	"id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/permitted",
	134	"type": "array",
	135	"items": {
	136	"type": "string"
	137	}
	138	},
	139	"effective": {
	140	"id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/effective",
	141	"type": "array",
	142	"items": {
	143	"type": "string"
	144	}
	145	},
	146	"inheritable": {
	147	"id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/inheritable",
	148	"type": "array",
	149	"items": {
	150	"type": "string"
	151	}
	152	},
	153	"ambient": {
	154	"id": "https://opencontainers.org/schema/bundle/process/linux/capabilities/ambient",
	155	"type": "array",
	156	"items": {
	157	"type": "string"
	158	}
	159	}
119	160	}
120	161	},
121	162	"apparmorProfile": {
122	163	"id": "https://opencontainers.org/schema/bundle/process/linux/apparmorProfile",
123	164	"type": "string"
	165	},
	166	"oomScoreAdj": {
	167	"id": "https://opencontainers.org/schema/bundle/process/linux/oomScoreAdj",
	168	"type": "integer"
124	169	},
125	170	"selinuxLabel": {
126	171	"id": "https://opencontainers.org/schema/bundle/process/linux/selinuxLabel",

136	181	"items": {
137	182	"id": "https://opencontainers.org/schema/bundle/linux/rlimits/0",
138	183	"type": "object",
	184	"required": [
	185	"type",
	186	"soft",
	187	"hard"
	188	],
139	189	"properties": {
140	190	"hard": {
141	191	"id": "https://opencontainers.org/schema/bundle/linux/rlimits/0/hard",

166	216	}
167	217	},
168	218	"required": [
169		"ociVersion",
170		"platform",
171		"process",
172		"root",
173		"mounts",
174		"hooks"
	219	"ociVersion"
175	220	]
176	221	}

+65

-24

schema/config-windows.json less more

3	3	"id": "https://opencontainers.org/schema/bundle/windows",
4	4	"type": "object",
5	5	"properties": {
	6	"layerFolders": {
	7	"id": "https://opencontainers.org/schema/bundle/windows/layerFolders",
	8	"type": "array",
	9	"items": {
	10	"$ref": "defs.json#/definitions/FilePath"
	11	},
	12	"minItems": 1
	13	},
6	14	"resources": {
7	15	"id": "https://opencontainers.org/schema/bundle/windows/resources",
8	16	"type": "object",

13	21	"properties": {
14	22	"limit": {
15	23	"id": "https://opencontainers.org/schema/bundle/windows/resources/memory/limit",
16		"$ref": "defs.json#/definitions/uint64Pointer"
17		},
18		"reservation": {
19		"id": "https://opencontainers.org/schema/bundle/windows/resources/memory/reservation",
20		"$ref": "defs.json#/definitions/uint64Pointer"
	24	"$ref": "defs.json#/definitions/uint64"
21	25	}
22	26	}
23	27	},

27	31	"properties": {
28	32	"count": {
29	33	"id": "https://opencontainers.org/schema/bundle/windows/resources/cpu/count",
30		"$ref": "defs.json#/definitions/uint64Pointer"
	34	"$ref": "defs.json#/definitions/uint64"
31	35	},
32	36	"shares": {
33	37	"id": "https://opencontainers.org/schema/bundle/windows/resources/cpu/shares",
34		"$ref": "defs-windows.json#/definitions/cpuSharesPointer"
	38	"$ref": "defs.json#/definitions/uint16"
35	39	},
36		"percent": {
37		"id": "https://opencontainers.org/schema/bundle/windows/resources/cpu/percent",
38		"$ref": "defs.json#/definitions/percentPointer"
	40	"maximum": {
	41	"id": "https://opencontainers.org/schema/bundle/windows/resources/cpu/maximum",
	42	"$ref": "defs.json#/definitions/uint16"
39	43	}
40	44	}
41	45	},

45	49	"properties": {
46	50	"iops": {
47	51	"id": "https://opencontainers.org/schema/bundle/windows/resources/storage/iops",
48		"$ref": "defs.json#/definitions/uint64Pointer"
	52	"$ref": "defs.json#/definitions/uint64"
49	53	},
50	54	"bps": {
51	55	"id": "https://opencontainers.org/schema/bundle/windows/resources/storage/bps",
52		"$ref": "defs.json#/definitions/uint64Pointer"
	56	"$ref": "defs.json#/definitions/uint64"
53	57	},
54	58	"sandboxSize": {
55	59	"id": "https://opencontainers.org/schema/bundle/windows/resources/storage/sandboxSize",
56		"$ref": "defs.json#/definitions/uint64Pointer"
57		}
58		}
59		},
60		"network": {
61		"id": "https://opencontainers.org/schema/bundle/windows/resources/network",
62		"type": "object",
63		"properties": {
64		"egressBandwidth": {
65		"id": "https://opencontainers.org/schema/bundle/windows/resources/network/egressBandwidth",
66		"$ref": "defs.json#/definitions/uint64Pointer"
	60	"$ref": "defs.json#/definitions/uint64"
67	61	}
68	62	}
69	63	}
70	64	}
	65	},
	66	"network": {
	67	"id": "https://opencontainers.org/schema/bundle/windows/network",
	68	"type": "object",
	69	"properties": {
	70	"endpointList": {
	71	"id": "https://opencontainers.org/schema/bundle/windows/network/endpointList",
	72	"$ref": "defs.json#/definitions/ArrayOfStrings"
	73	},
	74	"allowUnqualifiedDNSQuery": {
	75	"id": "https://opencontainers.org/schema/bundle/windows/network/allowUnqualifiedDNSQuery",
	76	"type": "boolean"
	77	},
	78	"DNSSearchList": {
	79	"id": "https://opencontainers.org/schema/bundle/windows/network/DNSSearchList",
	80	"$ref": "defs.json#/definitions/ArrayOfStrings"
	81	},
	82	"networkSharedContainerName": {
	83	"id": "https://opencontainers.org/schema/bundle/windows/network/networkSharedContainerName",
	84	"type": "string"
	85	}
	86	}
	87	},
	88	"credentialSpec": {
	89	"id": "https://opencontainers.org/schema/bundle/windows/credentialSpec",
	90	"type": "object"
	91	},
	92	"servicing": {
	93	"id": "https://opencontainers.org/schema/bundle/windows/servicing",
	94	"type": "boolean"
	95	},
	96	"ignoreFlushesDuringBoot": {
	97	"id": "https://opencontainers.org/schema/bundle/windows/ignoreFlushesDuringBoot",
	98	"type": "boolean"
	99	},
	100	"hyperv": {
	101	"id": "https://opencontainers.org/schema/bundle/windows/hyperv",
	102	"type": "object",
	103	"properties": {
	104	"utilityVMPath": {
	105	"id": "https://opencontainers.org/schema/bundle/windows/hyperv/utilityVMPath",
	106	"type": "string"
	107	}
	108	}
71	109	}
72		}
	110	},
	111	"required": [
	112	"layerFolders"
	113	]
73	114	}
74	115	}

+58

-77

schema/defs-linux.json less more

0	0	{
1	1	"definitions": {
	2	"RootfsPropagation": {
	3	"type": "string",
	4	"enum": [
	5	"private",
	6	"shared",
	7	"slave",
	8	"unbindable"
	9	]
	10	},
2	11	"SeccompArch": {
3	12	"type": "string",
4	13	"enum": [

17	26	"SCMP_ARCH_PPC64",
18	27	"SCMP_ARCH_PPC64LE",
19	28	"SCMP_ARCH_S390",
20		"SCMP_ARCH_S390X"
	29	"SCMP_ARCH_S390X",
	30	"SCMP_ARCH_PARISC",
	31	"SCMP_ARCH_PARISC64"
21	32	]
22	33	},
23	34	"SeccompAction": {

57	68	"op": {
58	69	"$ref": "#/definitions/SeccompOperators"
59	70	}
60		}
	71	},
	72	"required": [
	73	"index",
	74	"value",
	75	"op"
	76	]
61	77	},
62	78	"Syscall": {
63	79	"type": "object",
64	80	"properties": {
65		"name": {
66		"type": "string"
	81	"names": {
	82	"type": "array",
	83	"items": {
	84	"type": "string"
	85	},
	86	"minItems": 1
67	87	},
68	88	"action": {
69	89	"$ref": "#/definitions/SeccompAction"

74	94	"$ref": "#/definitions/SyscallArg"
75	95	}
76	96	}
77		}
78		},
79		"Capability": {
80		"description": "Linux process permissions",
81		"type": "string",
82		"pattern": "^CAP_([A-Z]\|_)+$"
	97	},
	98	"required": [
	99	"names",
	100	"action"
	101	]
83	102	},
84	103	"Major": {
85	104	"description": "major device number",
86		"$ref": "defs.json#/definitions/uint16"
	105	"$ref": "defs.json#/definitions/int64"
87	106	},
88	107	"Minor": {
89	108	"description": "minor device number",
90		"$ref": "defs.json#/definitions/uint16"
	109	"$ref": "defs.json#/definitions/int64"
91	110	},
92	111	"FileMode": {
93	112	"description": "File permissions mode (typically an octal value)",

95	114	"minimum": 0,
96	115	"maximum": 512
97	116	},
98		"FilePermissions": {
99		"type": "string"
100		},
101	117	"FileType": {
102	118	"description": "Type of a block or special character device",
103	119	"type": "string",

105	121	},
106	122	"Device": {
107	123	"type": "object",
	124	"required": [
	125	"type",
	126	"path"
	127	],
108	128	"properties": {
109	129	"type": {
110	130	"$ref": "#/definitions/FileType"
111	131	},
112		"permissions": {
113		"$ref": "#/definitions/FilePermissions"
114		},
115	132	"path": {
116	133	"$ref": "defs.json#/definitions/FilePath"
117	134	},

132	149	}
133	150	}
134	151	},
135		"blkioWeight": {
136		"type": "integer",
137		"minimum": 10,
138		"maximum": 1000
139		},
140		"blkioWeightPointer": {
141		"oneOf": [
142		{
143		"$ref": "#/definitions/blkioWeight"
144		},
145		{
146		"type": "null"
147		}
148		]
	152	"weight": {
	153	"type": "integer"
149	154	},
150	155	"blockIODevice": {
151	156	"type": "object",

172	177	"type": "object",
173	178	"properties": {
174	179	"weight": {
175		"$ref": "#/definitions/blkioWeightPointer"
	180	"$ref": "#/definitions/weight"
176	181	},
177	182	"leafWeight": {
178		"$ref": "#/definitions/blkioWeightPointer"
	183	"$ref": "#/definitions/weight"
179	184	}
180	185	}
181		}
182		]
183		},
184		"blockIODeviceWeightPointer": {
185		"oneOf": [
186		{
187		"$ref": "#/definitions/blockIODeviceWeight"
188		},
189		{
190		"type": "null"
191	186	}
192	187	]
193	188	},

200	195	"type": "object",
201	196	"properties": {
202	197	"rate": {
203		"$ref": "defs.json#/definitions/uint64Pointer"
	198	"$ref": "defs.json#/definitions/uint64"
204	199	}
205	200	}
206	201	}
207	202	]
208	203	},
209		"blockIODeviceThrottlePointer": {
210		"oneOf": [
211		{
212		"$ref": "#/definitions/blockIODeviceThrottle"
213		},
214		{
215		"type": "null"
216		}
217		]
218		},
219	204	"DeviceCgroup": {
220	205	"type": "object",
221	206	"properties": {

223	208	"type": "boolean"
224	209	},
225	210	"type": {
226		"$ref": "defs.json#/definitions/stringPointer"
	211	"type": "string"
227	212	},
228	213	"major": {
229		"oneOf": [
230		{
231		"$ref": "#/definitions/Major"
232		},
233		{
234		"type": "null"
235		}
236		]
	214	"$ref": "#/definitions/Major"
237	215	},
238	216	"minor": {
239		"oneOf": [
240		{
241		"$ref": "#/definitions/Minor"
242		},
243		{
244		"type": "null"
245		}
246		]
	217	"$ref": "#/definitions/Minor"
247	218	},
248	219	"access": {
249		"$ref": "defs.json#/definitions/stringPointer"
250		}
251		}
	220	"type": "string"
	221	}
	222	},
	223	"required": [
	224	"allow"
	225	]
252	226	},
253	227	"NetworkInterfacePriority": {
254	228	"type": "object",

259	233	"priority": {
260	234	"$ref": "defs.json#/definitions/uint32"
261	235	}
262		}
	236	},
	237	"required": [
	238	"name",
	239	"priority"
	240	]
263	241	},
264	242	"NamespaceType": {
265	243	"type": "string",

282	260	"path": {
283	261	"$ref": "defs.json#/definitions/FilePath"
284	262	}
285		}
	263	},
	264	"required": [
	265	"type"
	266	]
286	267	}
287	268	}
288	269	}

-20

~~schema/defs-windows.json~~ less more

0		{
1		"definitions": {
2		"cpuShares": {
3		"description": "Relative weight to other containers with CPU Shares defined",
4		"type": "integer",
5		"minimum": 1,
6		"maximum": 10000
7		},
8		"cpuSharesPointer": {
9		"oneOf": [
10		{
11		"$ref": "#/definitions/cpuShares"
12		},
13		{
14		"type": "null"
15		}
16		]
17		}
18		}
19		}

+14

-64

schema/defs.json less more

45	45	"minimum": 0,
46	46	"maximum": 100
47	47	},
48		"intPointer": {
49		"oneOf": [
50		{
51		"type": "integer"
52		},
53		{
54		"type": "null"
55		}
56		]
57		},
58		"uint16Pointer": {
59		"oneOf": [
60		{
61		"$ref": "#/definitions/uint16"
62		},
63		{
64		"type": "null"
65		}
66		]
67		},
68		"uint64Pointer": {
69		"oneOf": [
70		{
71		"$ref": "#/definitions/uint64"
72		},
73		{
74		"type": "null"
75		}
76		]
77		},
78		"percentPointer": {
79		"oneOf": [
80		{
81		"$ref": "#/definitions/percent"
82		},
83		{
84		"type": "null"
85		}
86		]
87		},
88		"stringPointer": {
89		"oneOf": [
90		{
91		"type": "string"
92		},
93		{
94		"type": "null"
95		}
96		]
97		},
98	48	"mapStringString": {
99	49	"type": "object",
100	50	"patternProperties": {

140	90	"$ref": "#/definitions/Env"
141	91	},
142	92	"timeout": {
143		"$ref": "#/definitions/intPointer"
	93	"type": "integer",
	94	"minimum": 1
144	95	}
145		}
	96	},
	97	"required": [
	98	"path"
	99	]
146	100	},
147	101	"ArrayOfHooks": {
148	102	"type": "array",

162	116	"size": {
163	117	"$ref": "#/definitions/uint32"
164	118	}
165		}
	119	},
	120	"required": [
	121	"hostID",
	122	"containerID",
	123	"size"
	124	]
166	125	},
167	126	"Mount": {
168	127	"type": "object",

181	140	}
182	141	},
183	142	"required": [
184		"destination",
185		"source",
186		"type"
	143	"destination"
187	144	]
188	145	},
189	146	"ociVersion": {

191	148	"type": "string"
192	149	},
193	150	"annotations": {
194		"oneOf": [
195		{
196		"$ref": "#/definitions/mapStringString"
197		},
198		{
199		"type": "null"
200		}
201		]
	151	"$ref": "#/definitions/mapStringString"
202	152	}
203	153	}
204	154	}

-4

schema/state-schema.json less more

16	16	"id": "https://opencontainers.org/schema/runtime/state/status",
17	17	"type": "string",
18	18	"enum": [
	19	"creating",
19	20	"created",
20	21	"running",
21	22	"stopped"

26	27	"type": "integer",
27	28	"minimum": 0
28	29	},
29		"bundlePath": {
30		"id": "https://opencontainers.org/schema/runtime/state/bundlePath",
	30	"bundle": {
	31	"id": "https://opencontainers.org/schema/runtime/state/bundle",
31	32	"type": "string"
32	33	},
33	34	"annotations": {

38	39	"ociVersion",
39	40	"id",
40	41	"status",
41		"pid",
42		"bundlePath"
	42	"bundle"
43	43	]
44	44	}

-0

schema/test/config/bad/invalid-json.json less more

{]

+16

-0

schema/test/config/good/minimal-for-start.json less more

	0	{
	1	"ociVersion": "1.0.0",
	2	"root": {
	3	"path": "rootfs"
	4	},
	5	"process": {
	6	"cwd": "/",
	7	"args": [
	8	"sh"
	9	],
	10	"user": {
	11	"uid": 0,
	12	"gid": 0
	13	}
	14	}
	15	}

-0

schema/test/config/good/minimal.json less more

	0	{
	1	"ociVersion": "1.0.0",
	2	"root": {
	3	"path": "rootfs"
	4	}
	5	}

+368

-0

schema/test/config/good/spec-example.json less more

	0	{
	1	"ociVersion": "0.5.0-dev",
	2	"process": {
	3	"terminal": true,
	4	"user": {
	5	"uid": 1,
	6	"gid": 1,
	7	"additionalGids": [
	8	5,
	9	6
	10	]
	11	},
	12	"args": [
	13	"sh"
	14	],
	15	"env": [
	16	"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
	17	"TERM=xterm"
	18	],
	19	"cwd": "/",
	20	"capabilities": {
	21	"bounding": [
	22	"CAP_AUDIT_WRITE",
	23	"CAP_KILL",
	24	"CAP_NET_BIND_SERVICE"
	25	],
	26	"permitted": [
	27	"CAP_AUDIT_WRITE",
	28	"CAP_KILL",
	29	"CAP_NET_BIND_SERVICE"
	30	],
	31	"inheritable": [
	32	"CAP_AUDIT_WRITE",
	33	"CAP_KILL",
	34	"CAP_NET_BIND_SERVICE"
	35	],
	36	"effective": [
	37	"CAP_AUDIT_WRITE",
	38	"CAP_KILL"
	39	],
	40	"ambient": [
	41	"CAP_NET_BIND_SERVICE"
	42	]
	43	},
	44	"rlimits": [
	45	{
	46	"type": "RLIMIT_CORE",
	47	"hard": 1024,
	48	"soft": 1024
	49	},
	50	{
	51	"type": "RLIMIT_NOFILE",
	52	"hard": 1024,
	53	"soft": 1024
	54	}
	55	],
	56	"apparmorProfile": "acme_secure_profile",
	57	"selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675",
	58	"noNewPrivileges": true
	59	},
	60	"root": {
	61	"path": "rootfs",
	62	"readonly": true
	63	},
	64	"hostname": "slartibartfast",
	65	"mounts": [
	66	{
	67	"destination": "/proc",
	68	"type": "proc",
	69	"source": "proc"
	70	},
	71	{
	72	"destination": "/dev",
	73	"type": "tmpfs",
	74	"source": "tmpfs",
	75	"options": [
	76	"nosuid",
	77	"strictatime",
	78	"mode=755",
	79	"size=65536k"
	80	]
	81	},
	82	{
	83	"destination": "/dev/pts",
	84	"type": "devpts",
	85	"source": "devpts",
	86	"options": [
	87	"nosuid",
	88	"noexec",
	89	"newinstance",
	90	"ptmxmode=0666",
	91	"mode=0620",
	92	"gid=5"
	93	]
	94	},
	95	{
	96	"destination": "/dev/shm",
	97	"type": "tmpfs",
	98	"source": "shm",
	99	"options": [
	100	"nosuid",
	101	"noexec",
	102	"nodev",
	103	"mode=1777",
	104	"size=65536k"
	105	]
	106	},
	107	{
	108	"destination": "/dev/mqueue",
	109	"type": "mqueue",
	110	"source": "mqueue",
	111	"options": [
	112	"nosuid",
	113	"noexec",
	114	"nodev"
	115	]
	116	},
	117	{
	118	"destination": "/sys",
	119	"type": "sysfs",
	120	"source": "sysfs",
	121	"options": [
	122	"nosuid",
	123	"noexec",
	124	"nodev"
	125	]
	126	},
	127	{
	128	"destination": "/sys/fs/cgroup",
	129	"type": "cgroup",
	130	"source": "cgroup",
	131	"options": [
	132	"nosuid",
	133	"noexec",
	134	"nodev",
	135	"relatime",
	136	"ro"
	137	]
	138	}
	139	],
	140	"hooks": {
	141	"prestart": [
	142	{
	143	"path": "/usr/bin/fix-mounts",
	144	"args": [
	145	"fix-mounts",
	146	"arg1",
	147	"arg2"
	148	],
	149	"env": [
	150	"key1=value1"
	151	]
	152	},
	153	{
	154	"path": "/usr/bin/setup-network"
	155	}
	156	],
	157	"poststart": [
	158	{
	159	"path": "/usr/bin/notify-start",
	160	"timeout": 5
	161	}
	162	],
	163	"poststop": [
	164	{
	165	"path": "/usr/sbin/cleanup.sh",
	166	"args": [
	167	"cleanup.sh",
	168	"-f"
	169	]
	170	}
	171	]
	172	},
	173	"linux": {
	174	"devices": [
	175	{
	176	"path": "/dev/fuse",
	177	"type": "c",
	178	"major": 10,
	179	"minor": 229,
	180	"fileMode": 438,
	181	"uid": 0,
	182	"gid": 0
	183	},
	184	{
	185	"path": "/dev/sda",
	186	"type": "b",
	187	"major": 8,
	188	"minor": 0,
	189	"fileMode": 432,
	190	"uid": 0,
	191	"gid": 0
	192	}
	193	],
	194	"uidMappings": [
	195	{
	196	"hostID": 1000,
	197	"containerID": 0,
	198	"size": 32000
	199	}
	200	],
	201	"gidMappings": [
	202	{
	203	"hostID": 1000,
	204	"containerID": 0,
	205	"size": 32000
	206	}
	207	],
	208	"sysctl": {
	209	"net.ipv4.ip_forward": "1",
	210	"net.core.somaxconn": "256"
	211	},
	212	"cgroupsPath": "/myRuntime/myContainer",
	213	"resources": {
	214	"network": {
	215	"classID": 1048577,
	216	"priorities": [
	217	{
	218	"name": "eth0",
	219	"priority": 500
	220	},
	221	{
	222	"name": "eth1",
	223	"priority": 1000
	224	}
	225	]
	226	},
	227	"pids": {
	228	"limit": 32771
	229	},
	230	"hugepageLimits": [
	231	{
	232	"pageSize": "2MB",
	233	"limit": 9223372036854772000
	234	}
	235	],
	236	"oomScoreAdj": 100,
	237	"memory": {
	238	"limit": 536870912,
	239	"reservation": 536870912,
	240	"swap": 536870912,
	241	"kernel": -1,
	242	"kernelTCP": -1,
	243	"swappiness": 0,
	244	"disableOOMKiller": false
	245	},
	246	"cpu": {
	247	"shares": 1024,
	248	"quota": 1000000,
	249	"period": 500000,
	250	"realtimeRuntime": 950000,
	251	"realtimePeriod": 1000000,
	252	"cpus": "2-3",
	253	"mems": "0-7"
	254	},
	255	"devices": [
	256	{
	257	"allow": false,
	258	"access": "rwm"
	259	},
	260	{
	261	"allow": true,
	262	"type": "c",
	263	"major": 10,
	264	"minor": 229,
	265	"access": "rw"
	266	},
	267	{
	268	"allow": true,
	269	"type": "b",
	270	"major": 8,
	271	"minor": 0,
	272	"access": "r"
	273	}
	274	],
	275	"blockIO": {
	276	"weight": 10,
	277	"leafWeight": 10,
	278	"weightDevice": [
	279	{
	280	"major": 8,
	281	"minor": 0,
	282	"weight": 500,
	283	"leafWeight": 300
	284	},
	285	{
	286	"major": 8,
	287	"minor": 16,
	288	"weight": 500
	289	}
	290	],
	291	"throttleReadBpsDevice": [
	292	{
	293	"major": 8,
	294	"minor": 0,
	295	"rate": 600
	296	}
	297	],
	298	"throttleWriteIOPSDevice": [
	299	{
	300	"major": 8,
	301	"minor": 16,
	302	"rate": 300
	303	}
	304	]
	305	}
	306	},
	307	"rootfsPropagation": "slave",
	308	"seccomp": {
	309	"defaultAction": "SCMP_ACT_ALLOW",
	310	"architectures": [
	311	"SCMP_ARCH_X86",
	312	"SCMP_ARCH_X32"
	313	],
	314	"syscalls": [
	315	{
	316	"names": [
	317	"getcwd",
	318	"chmod"
	319	],
	320	"action": "SCMP_ACT_ERRNO"
	321	}
	322	]
	323	},
	324	"namespaces": [
	325	{
	326	"type": "pid"
	327	},
	328	{
	329	"type": "network"
	330	},
	331	{
	332	"type": "ipc"
	333	},
	334	{
	335	"type": "uts"
	336	},
	337	{
	338	"type": "mount"
	339	},
	340	{
	341	"type": "user"
	342	},
	343	{
	344	"type": "cgroup"
	345	}
	346	],
	347	"maskedPaths": [
	348	"/proc/kcore",
	349	"/proc/latency_stats",
	350	"/proc/timer_stats",
	351	"/proc/sched_debug"
	352	],
	353	"readonlyPaths": [
	354	"/proc/asound",
	355	"/proc/bus",
	356	"/proc/fs",
	357	"/proc/irq",
	358	"/proc/sys",
	359	"/proc/sysrq-trigger"
	360	],
	361	"mountLabel": "system_u:object_r:svirt_sandbox_file_t:s0:c715,c811"
	362	},
	363	"annotations": {
	364	"com.example.key1": "value1",
	365	"com.example.key2": "value2"
	366	}
	367	}

-0

schema/test/state/bad/invalid-json.json less more

{]

+10

-0

schema/test/state/good/spec-example.json less more

	0	{
	1	"ociVersion": "0.2.0",
	2	"id": "oci-container1",
	3	"status": "running",
	4	"pid": 4422,
	5	"bundle": "/containers/redis",
	6	"annotations": {
	7	"myKey": "myValue"
	8	}
	9	}

+50

-8

schema/validate.go less more

4	4	"io/ioutil"
5	5	"os"
6	6	"path/filepath"
	7	"strings"
7	8
8	9	"github.com/xeipuuv/gojsonschema"
9	10	)
10	11
	12	const usage = `Validate is used to check document with specified schema.
	13	You can use validate in following ways:
	14
	15	1.specify document file as an argument
	16	validate <schema.json> <document.json>
	17
	18	2.pass document content through a pipe
	19	cat <document.json> \| validate <schema.json>
	20
	21	3.input document content manually, ended with ctrl+d(or your self-defined EOF keys)
	22	validate <schema.json>
	23	[INPUT DOCUMENT CONTENT HERE]
	24	`
	25
11	26	func main() {
12	27	nargs := len(os.Args[1:])
13	28	if nargs == 0 \|\| nargs > 2 {
14		fmt.Printf("ERROR: usage is: %s <schema.json> [<document.json>]\n", os.Args[0])
	29	fmt.Printf("ERROR: invalid arguments number\n\n%s\n", usage)
15	30	os.Exit(1)
16	31	}
17	32
18		schemaPath, err := filepath.Abs(os.Args[1])
19		if err != nil {
20		fmt.Println(err)
	33	if os.Args[1] == "help" \|\|
	34	os.Args[1] == "--help" \|\|
	35	os.Args[1] == "-h" {
	36	fmt.Printf("%s\n", usage)
21	37	os.Exit(1)
22	38	}
23		schemaLoader := gojsonschema.NewReferenceLoader("file://" + schemaPath)
	39
	40	schemaPath := os.Args[1]
	41	if !strings.Contains(schemaPath, "://") {
	42	var err error
	43	schemaPath, err = formatFilePath(schemaPath)
	44	if err != nil {
	45	fmt.Printf("ERROR: invalid schema-file path: %s\n", err)
	46	os.Exit(1)
	47	}
	48	schemaPath = "file://" + schemaPath
	49	}
	50
	51	schemaLoader := gojsonschema.NewReferenceLoader(schemaPath)
	52
24	53	var documentLoader gojsonschema.JSONLoader
25	54
26	55	if nargs > 1 {
27		documentPath, err := filepath.Abs(os.Args[2])
	56	documentPath, err := formatFilePath(os.Args[2])
28	57	if err != nil {
29		fmt.Println(err)
	58	fmt.Printf("ERROR: invalid document-file path: %s\n", err)
30	59	os.Exit(1)
31	60	}
32	61	documentLoader = gojsonschema.NewReferenceLoader("file://" + documentPath)

42	71
43	72	result, err := gojsonschema.Validate(schemaLoader, documentLoader)
44	73	if err != nil {
45		panic(err.Error())
	74	fmt.Println(err)
	75	os.Exit(1)
46	76	}
47	77
48	78	if result.Valid() {

55	85	os.Exit(1)
56	86	}
57	87	}
	88
	89	func formatFilePath(path string) (string, error) {
	90	if _, err := os.Stat(path); err != nil {
	91	return "", err
	92	}
	93
	94	absPath, err := filepath.Abs(path)
	95	if err != nil {
	96	return "", err
	97	}
	98	return absPath, nil
	99	}

+46

-0

spec.md less more

	0	# <a name="openContainerInitiativeRuntimeSpecification" />Open Container Initiative Runtime Specification
	1
	2	The [Open Container Initiative][oci] develops specifications for standards on Operating System process and application containers.
	3
	4	# <a name="ociRuntimeSpecAbstract" />Abstract
	5
	6	The OCI Runtime Specification aims to specify the configuration, execution environment, and lifecycle of a container.
	7
	8	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.
	9	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.
	10
	11	# <a name="ociRuntimeSpecPlatforms" />Platforms
	12
	13	Platforms defined by this specification are:
	14
	15	* `linux`: [runtime.md](runtime.md), [config.md](config.md), [config-linux.md](config-linux.md), and [runtime-linux.md](runtime-linux.md).
	16	* `solaris`: [runtime.md](runtime.md), [config.md](config.md), and [config-solaris.md](config-solaris.md).
	17	* `windows`: [runtime.md](runtime.md), [config.md](config.md), and [config-windows.md](config-windows.md).
	18
	19	# <a name="ociRuntimeSpecTOC" />Table of Contents
	20
	21	- [Introduction](spec.md)
	22	- [Notational Conventions](#notational-conventions)
	23	- [Container Principles](principles.md)
	24	- [Filesystem Bundle](bundle.md)
	25	- [Runtime and Lifecycle](runtime.md)
	26	- [Linux-specific Runtime and Lifecycle](runtime-linux.md)
	27	- [Configuration](config.md)
	28	- [Linux-specific Configuration](config-linux.md)
	29	- [Solaris-specific Configuration](config-solaris.md)
	30	- [Windows-specific Configuration](config-windows.md)
	31	- [Glossary](glossary.md)
	32
	33	# <a name="ociRuntimeSpecNotationalConventions" />Notational Conventions
	34
	35	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].
	36
	37	The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified].
	38
	39	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.
	40	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.
	41
	42
	43	[c99-unspecified]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18
	44	[oci]: http://www.opencontainers.org
	45	[rfc2119]: http://tools.ietf.org/html/rfc2119

+233

-198

specs-go/config.go less more

5	5	type Spec struct {
6	6	// Version of the Open Container Runtime Specification with which the bundle complies.
7	7	Version string `json:"ociVersion"`
8		// Platform specifies the configuration's target platform.
9		Platform Platform `json:"platform"`
10	8	// Process configures the container process.
11		Process Process `json:"process"`
	9	Process *Process `json:"process,omitempty"`
12	10	// Root configures the container's root filesystem.
13		Root Root `json:"root"`
	11	Root *Root `json:"root,omitempty"`
14	12	// Hostname configures the container's hostname.
15	13	Hostname string `json:"hostname,omitempty"`
16	14	// Mounts configures additional mounts (on top of Root).
17	15	Mounts []Mount `json:"mounts,omitempty"`
18	16	// Hooks configures callbacks for container lifecycle events.
19		Hooks Hooks `json:"hooks"`
	17	Hooks *Hooks `json:"hooks,omitempty" platform:"linux,solaris"`
20	18	// Annotations contains arbitrary metadata for the container.
21	19	Annotations map[string]string `json:"annotations,omitempty"`
22	20
23		// Linux is platform specific configuration for Linux based containers.
	21	// Linux is platform-specific configuration for Linux based containers.
24	22	Linux *Linux `json:"linux,omitempty" platform:"linux"`
25		// Solaris is platform specific configuration for Solaris containers.
	23	// Solaris is platform-specific configuration for Solaris based containers.
26	24	Solaris *Solaris `json:"solaris,omitempty" platform:"solaris"`
27		// Windows is platform specific configuration for Windows based containers, including Hyper-V containers.
	25	// Windows is platform-specific configuration for Windows based containers.
28	26	Windows *Windows `json:"windows,omitempty" platform:"windows"`
29	27	}
30	28

33	31	// Terminal creates an interactive terminal for the container.
34	32	Terminal bool `json:"terminal,omitempty"`
35	33	// ConsoleSize specifies the size of the console.
36		ConsoleSize Box `json:"consoleSize,omitempty"`
	34	ConsoleSize *Box `json:"consoleSize,omitempty"`
37	35	// User specifies user information for the process.
38	36	User User `json:"user"`
39	37	// Args specifies the binary and arguments for the application to execute.

43	41	// Cwd is the current working directory for the process and must be
44	42	// relative to the container's root.
45	43	Cwd string `json:"cwd"`
46		// Capabilities are Linux capabilities that are kept for the container.
47		Capabilities []string `json:"capabilities,omitempty" platform:"linux"`
	44	// Capabilities are Linux capabilities that are kept for the process.
	45	Capabilities *LinuxCapabilities `json:"capabilities,omitempty" platform:"linux"`
48	46	// Rlimits specifies rlimit options to apply to the process.
49		Rlimits []Rlimit `json:"rlimits,omitempty" platform:"linux"`
	47	Rlimits []POSIXRlimit `json:"rlimits,omitempty" platform:"linux,solaris"`
50	48	// NoNewPrivileges controls whether additional privileges could be gained by processes in the container.
51	49	NoNewPrivileges bool `json:"noNewPrivileges,omitempty" platform:"linux"`
52	50	// ApparmorProfile specifies the apparmor profile for the container.
53	51	ApparmorProfile string `json:"apparmorProfile,omitempty" platform:"linux"`
	52	// Specify an oom_score_adj for the container.
	53	OOMScoreAdj *int `json:"oomScoreAdj,omitempty" platform:"linux"`
54	54	// SelinuxLabel specifies the selinux context that the container process is run as.
55	55	SelinuxLabel string `json:"selinuxLabel,omitempty" platform:"linux"`
	56	}
	57
	58	// LinuxCapabilities specifies the whitelist of capabilities that are kept for a process.
	59	// http://man7.org/linux/man-pages/man7/capabilities.7.html
	60	type LinuxCapabilities struct {
	61	// Bounding is the set of capabilities checked by the kernel.
	62	Bounding []string `json:"bounding,omitempty" platform:"linux"`
	63	// Effective is the set of capabilities checked by the kernel.
	64	Effective []string `json:"effective,omitempty" platform:"linux"`
	65	// Inheritable is the capabilities preserved across execve.
	66	Inheritable []string `json:"inheritable,omitempty" platform:"linux"`
	67	// Permitted is the limiting superset for effective capabilities.
	68	Permitted []string `json:"permitted,omitempty" platform:"linux"`
	69	// Ambient is the ambient set of capabilities that are kept.
	70	Ambient []string `json:"ambient,omitempty" platform:"linux"`
56	71	}
57	72
58	73	// Box specifies dimensions of a rectangle. Used for specifying the size of a console.

83	98	Readonly bool `json:"readonly,omitempty"`
84	99	}
85	100
86		// Platform specifies OS and arch information for the host system that the container
87		// is created for.
88		type Platform struct {
89		// OS is the operating system.
90		OS string `json:"os"`
91		// Arch is the architecture
92		Arch string `json:"arch"`
93		}
94
95	101	// Mount specifies a mount for a container.
96	102	type Mount struct {
97		// Destination is the path where the mount will be placed relative to the container's root. The path and child directories MUST exist, a runtime MUST NOT create directories automatically to a mount point.
	103	// Destination is the absolute path where the mount will be placed in the container.
98	104	Destination string `json:"destination"`
99	105	// Type specifies the mount kind.
100		Type string `json:"type"`
101		// Source specifies the source path of the mount. In the case of bind mounts on
102		// Linux based systems this would be the file on the host.
103		Source string `json:"source"`
	106	Type string `json:"type,omitempty" platform:"linux,solaris"`
	107	// Source specifies the source path of the mount.
	108	Source string `json:"source,omitempty"`
104	109	// Options are fstab style mount options.
105	110	Options []string `json:"options,omitempty"`
106	111	}

116	121	// Hooks for container setup and teardown
117	122	type Hooks struct {
118	123	// Prestart is a list of hooks to be run before the container process is executed.
119		// On Linux, they are run after the container namespaces are created.
120	124	Prestart []Hook `json:"prestart,omitempty"`
121	125	// Poststart is a list of hooks to be run after the container process is started.
122	126	Poststart []Hook `json:"poststart,omitempty"`

124	128	Poststop []Hook `json:"poststop,omitempty"`
125	129	}
126	130
127		// Linux contains platform specific configuration for Linux based containers.
	131	// Linux contains platform-specific configuration for Linux based containers.
128	132	type Linux struct {
129		// UIDMapping specifies user mappings for supporting user namespaces on Linux.
130		UIDMappings []IDMapping `json:"uidMappings,omitempty"`
131		// GIDMapping specifies group mappings for supporting user namespaces on Linux.
132		GIDMappings []IDMapping `json:"gidMappings,omitempty"`
	133	// UIDMapping specifies user mappings for supporting user namespaces.
	134	UIDMappings []LinuxIDMapping `json:"uidMappings,omitempty"`
	135	// GIDMapping specifies group mappings for supporting user namespaces.
	136	GIDMappings []LinuxIDMapping `json:"gidMappings,omitempty"`
133	137	// Sysctl are a set of key value pairs that are set for the container on start
134	138	Sysctl map[string]string `json:"sysctl,omitempty"`
135	139	// Resources contain cgroup information for handling resource constraints
136	140	// for the container
137		Resources *Resources `json:"resources,omitempty"`
	141	Resources *LinuxResources `json:"resources,omitempty"`
138	142	// CgroupsPath specifies the path to cgroups that are created and/or joined by the container.
139	143	// The path is expected to be relative to the cgroups mountpoint.
140	144	// If resources are specified, the cgroups at CgroupsPath will be updated based on resources.
141		CgroupsPath *string `json:"cgroupsPath,omitempty"`
	145	CgroupsPath string `json:"cgroupsPath,omitempty"`
142	146	// Namespaces contains the namespaces that are created and/or joined by the container
143		Namespaces []Namespace `json:"namespaces,omitempty"`
	147	Namespaces []LinuxNamespace `json:"namespaces,omitempty"`
144	148	// Devices are a list of device nodes that are created for the container
145		Devices []Device `json:"devices,omitempty"`
	149	Devices []LinuxDevice `json:"devices,omitempty"`
146	150	// Seccomp specifies the seccomp security settings for the container.
147		Seccomp *Seccomp `json:"seccomp,omitempty"`
	151	Seccomp *LinuxSeccomp `json:"seccomp,omitempty"`
148	152	// RootfsPropagation is the rootfs mount propagation mode for the container.
149	153	RootfsPropagation string `json:"rootfsPropagation,omitempty"`
150	154	// MaskedPaths masks over the provided paths inside the container.

153	157	ReadonlyPaths []string `json:"readonlyPaths,omitempty"`
154	158	// MountLabel specifies the selinux context for the mounts in the container.
155	159	MountLabel string `json:"mountLabel,omitempty"`
156		}
157
158		// Namespace is the configuration for a Linux namespace
159		type Namespace struct {
160		// Type is the type of Linux namespace
161		Type NamespaceType `json:"type"`
	160	// IntelRdt contains Intel Resource Director Technology (RDT) information
	161	// for handling resource constraints (e.g., L3 cache) for the container
	162	IntelRdt *LinuxIntelRdt `json:"intelRdt,omitempty"`
	163	}
	164
	165	// LinuxNamespace is the configuration for a Linux namespace
	166	type LinuxNamespace struct {
	167	// Type is the type of namespace
	168	Type LinuxNamespaceType `json:"type"`
162	169	// Path is a path to an existing namespace persisted on disk that can be joined
163	170	// and is of the same type
164	171	Path string `json:"path,omitempty"`
165	172	}
166	173
167		// NamespaceType is one of the Linux namespaces
168		type NamespaceType string
	174	// LinuxNamespaceType is one of the Linux namespaces
	175	type LinuxNamespaceType string
169	176
170	177	const (
171	178	// PIDNamespace for isolating process IDs
172		PIDNamespace NamespaceType = "pid"
	179	PIDNamespace LinuxNamespaceType = "pid"
173	180	// NetworkNamespace for isolating network devices, stacks, ports, etc
174	181	NetworkNamespace = "network"
175	182	// MountNamespace for isolating mount points

184	191	CgroupNamespace = "cgroup"
185	192	)
186	193
187		// IDMapping specifies UID/GID mappings
188		type IDMapping struct {
189		// HostID is the UID/GID of the host user or group
	194	// LinuxIDMapping specifies UID/GID mappings
	195	type LinuxIDMapping struct {
	196	// HostID is the starting UID/GID on the host to be mapped to 'ContainerID'
190	197	HostID uint32 `json:"hostID"`
191		// ContainerID is the UID/GID of the container's user or group
	198	// ContainerID is the starting UID/GID in the container
192	199	ContainerID uint32 `json:"containerID"`
193		// Size is the length of the range of IDs mapped between the two namespaces
	200	// Size is the number of IDs to be mapped
194	201	Size uint32 `json:"size"`
195	202	}
196	203
197		// Rlimit type and restrictions
198		type Rlimit struct {
	204	// POSIXRlimit type and restrictions
	205	type POSIXRlimit struct {
199	206	// Type of the rlimit to set
200	207	Type string `json:"type"`
201	208	// Hard is the hard limit for the specified type

204	211	Soft uint64 `json:"soft"`
205	212	}
206	213
207		// HugepageLimit structure corresponds to limiting kernel hugepages
208		type HugepageLimit struct {
	214	// LinuxHugepageLimit structure corresponds to limiting kernel hugepages
	215	type LinuxHugepageLimit struct {
209	216	// Pagesize is the hugepage size
210		Pagesize *string `json:"pageSize,omitempty"`
	217	Pagesize string `json:"pageSize"`
211	218	// Limit is the limit of "hugepagesize" hugetlb usage
212		Limit *uint64 `json:"limit,omitempty"`
213		}
214
215		// InterfacePriority for network interfaces
216		type InterfacePriority struct {
	219	Limit uint64 `json:"limit"`
	220	}
	221
	222	// LinuxInterfacePriority for network interfaces
	223	type LinuxInterfacePriority struct {
217	224	// Name is the name of the network interface
218	225	Name string `json:"name"`
219	226	// Priority for the interface
220	227	Priority uint32 `json:"priority"`
221	228	}
222	229
223		// blockIODevice holds major:minor format supported in blkio cgroup
224		type blockIODevice struct {
	230	// linuxBlockIODevice holds major:minor format supported in blkio cgroup
	231	type linuxBlockIODevice struct {
225	232	// Major is the device's major number.
226	233	Major int64 `json:"major"`
227	234	// Minor is the device's minor number.
228	235	Minor int64 `json:"minor"`
229	236	}
230	237
231		// WeightDevice struct holds a `major:minor weight` pair for blkioWeightDevice
232		type WeightDevice struct {
233		blockIODevice
234		// Weight is the bandwidth rate for the device, range is from 10 to 1000
	238	// LinuxWeightDevice struct holds a `major:minor weight` pair for weightDevice
	239	type LinuxWeightDevice struct {
	240	linuxBlockIODevice
	241	// Weight is the bandwidth rate for the device.
235	242	Weight *uint16 `json:"weight,omitempty"`
236		// LeafWeight is the bandwidth rate for the device while competing with the cgroup's child cgroups, range is from 10 to 1000, CFQ scheduler only
	243	// LeafWeight is the bandwidth rate for the device while competing with the cgroup's child cgroups, CFQ scheduler only
237	244	LeafWeight *uint16 `json:"leafWeight,omitempty"`
238	245	}
239	246
240		// ThrottleDevice struct holds a `major:minor rate_per_second` pair
241		type ThrottleDevice struct {
242		blockIODevice
	247	// LinuxThrottleDevice struct holds a `major:minor rate_per_second` pair
	248	type LinuxThrottleDevice struct {
	249	linuxBlockIODevice
243	250	// Rate is the IO rate limit per cgroup per device
244		Rate *uint64 `json:"rate,omitempty"`
245		}
246
247		// BlockIO for Linux cgroup 'blkio' resource management
248		type BlockIO struct {
249		// Specifies per cgroup weight, range is from 10 to 1000
250		Weight *uint16 `json:"blkioWeight,omitempty"`
251		// Specifies tasks' weight in the given cgroup while competing with the cgroup's child cgroups, range is from 10 to 1000, CFQ scheduler only
252		LeafWeight *uint16 `json:"blkioLeafWeight,omitempty"`
	251	Rate uint64 `json:"rate"`
	252	}
	253
	254	// LinuxBlockIO for Linux cgroup 'blkio' resource management
	255	type LinuxBlockIO struct {
	256	// Specifies per cgroup weight
	257	Weight *uint16 `json:"weight,omitempty"`
	258	// Specifies tasks' weight in the given cgroup while competing with the cgroup's child cgroups, CFQ scheduler only
	259	LeafWeight *uint16 `json:"leafWeight,omitempty"`
253	260	// Weight per cgroup per device, can override BlkioWeight
254		WeightDevice []WeightDevice `json:"blkioWeightDevice,omitempty"`
	261	WeightDevice []LinuxWeightDevice `json:"weightDevice,omitempty"`
255	262	// IO read rate limit per cgroup per device, bytes per second
256		ThrottleReadBpsDevice []ThrottleDevice `json:"blkioThrottleReadBpsDevice,omitempty"`
	263	ThrottleReadBpsDevice []LinuxThrottleDevice `json:"throttleReadBpsDevice,omitempty"`
257	264	// IO write rate limit per cgroup per device, bytes per second
258		ThrottleWriteBpsDevice []ThrottleDevice `json:"blkioThrottleWriteBpsDevice,omitempty"`
	265	ThrottleWriteBpsDevice []LinuxThrottleDevice `json:"throttleWriteBpsDevice,omitempty"`
259	266	// IO read rate limit per cgroup per device, IO per second
260		ThrottleReadIOPSDevice []ThrottleDevice `json:"blkioThrottleReadIOPSDevice,omitempty"`
	267	ThrottleReadIOPSDevice []LinuxThrottleDevice `json:"throttleReadIOPSDevice,omitempty"`
261	268	// IO write rate limit per cgroup per device, IO per second
262		ThrottleWriteIOPSDevice []ThrottleDevice `json:"blkioThrottleWriteIOPSDevice,omitempty"`
263		}
264
265		// Memory for Linux cgroup 'memory' resource management
266		type Memory struct {
	269	ThrottleWriteIOPSDevice []LinuxThrottleDevice `json:"throttleWriteIOPSDevice,omitempty"`
	270	}
	271
	272	// LinuxMemory for Linux cgroup 'memory' resource management
	273	type LinuxMemory struct {
267	274	// Memory limit (in bytes).
268		Limit *uint64 `json:"limit,omitempty"`
	275	Limit *int64 `json:"limit,omitempty"`
269	276	// Memory reservation or soft_limit (in bytes).
270		Reservation *uint64 `json:"reservation,omitempty"`
	277	Reservation *int64 `json:"reservation,omitempty"`
271	278	// Total memory limit (memory + swap).
272		Swap *uint64 `json:"swap,omitempty"`
	279	Swap *int64 `json:"swap,omitempty"`
273	280	// Kernel memory limit (in bytes).
274		Kernel *uint64 `json:"kernel,omitempty"`
	281	Kernel *int64 `json:"kernel,omitempty"`
275	282	// Kernel memory limit for tcp (in bytes)
276		KernelTCP *uint64 `json:"kernelTCP,omitempty"`
277		// How aggressive the kernel will swap memory pages. Range from 0 to 100.
	283	KernelTCP *int64 `json:"kernelTCP,omitempty"`
	284	// How aggressive the kernel will swap memory pages.
278	285	Swappiness *uint64 `json:"swappiness,omitempty"`
279		}
280
281		// CPU for Linux cgroup 'cpu' resource management
282		type CPU struct {
	286	// DisableOOMKiller disables the OOM killer for out of memory conditions
	287	DisableOOMKiller *bool `json:"disableOOMKiller,omitempty"`
	288	}
	289
	290	// LinuxCPU for Linux cgroup 'cpu' resource management
	291	type LinuxCPU struct {
283	292	// CPU shares (relative weight (ratio) vs. other cgroups with cpu shares).
284	293	Shares *uint64 `json:"shares,omitempty"`
285	294	// CPU hardcap limit (in usecs). Allowed cpu time in a given period.
286		Quota *uint64 `json:"quota,omitempty"`
	295	Quota *int64 `json:"quota,omitempty"`
287	296	// CPU period to be used for hardcapping (in usecs).
288	297	Period *uint64 `json:"period,omitempty"`
289	298	// How much time realtime scheduling may use (in usecs).
290		RealtimeRuntime *uint64 `json:"realtimeRuntime,omitempty"`
	299	RealtimeRuntime *int64 `json:"realtimeRuntime,omitempty"`
291	300	// CPU period to be used for realtime scheduling (in usecs).
292	301	RealtimePeriod *uint64 `json:"realtimePeriod,omitempty"`
293	302	// CPUs to use within the cpuset. Default is to use any CPU available.
294		Cpus *string `json:"cpus,omitempty"`
	303	Cpus string `json:"cpus,omitempty"`
295	304	// List of memory nodes in the cpuset. Default is to use any available memory node.
296		Mems *string `json:"mems,omitempty"`
297		}
298
299		// Pids for Linux cgroup 'pids' resource management (Linux 4.3)
300		type Pids struct {
	305	Mems string `json:"mems,omitempty"`
	306	}
	307
	308	// LinuxPids for Linux cgroup 'pids' resource management (Linux 4.3)
	309	type LinuxPids struct {
301	310	// Maximum number of PIDs. Default is "no limit".
302		Limit *int64 `json:"limit,omitempty"`
303		}
304
305		// Network identification and priority configuration
306		type Network struct {
	311	Limit int64 `json:"limit"`
	312	}
	313
	314	// LinuxNetwork identification and priority configuration
	315	type LinuxNetwork struct {
307	316	// Set class identifier for container's network packets
308	317	ClassID *uint32 `json:"classID,omitempty"`
309	318	// Set priority of network traffic for container
310		Priorities []InterfacePriority `json:"priorities,omitempty"`
311		}
312
313		// Resources has container runtime resource constraints
314		type Resources struct {
	319	Priorities []LinuxInterfacePriority `json:"priorities,omitempty"`
	320	}
	321
	322	// LinuxResources has container runtime resource constraints
	323	type LinuxResources struct {
315	324	// Devices configures the device whitelist.
316		Devices []DeviceCgroup `json:"devices,omitempty"`
317		// DisableOOMKiller disables the OOM killer for out of memory conditions
318		DisableOOMKiller *bool `json:"disableOOMKiller,omitempty"`
319		// Specify an oom_score_adj for the container.
320		OOMScoreAdj *int `json:"oomScoreAdj,omitempty"`
	325	Devices []LinuxDeviceCgroup `json:"devices,omitempty"`
321	326	// Memory restriction configuration
322		Memory *Memory `json:"memory,omitempty"`
	327	Memory *LinuxMemory `json:"memory,omitempty"`
323	328	// CPU resource restriction configuration
324		CPU *CPU `json:"cpu,omitempty"`
	329	CPU *LinuxCPU `json:"cpu,omitempty"`
325	330	// Task resource restriction configuration.
326		Pids *Pids `json:"pids,omitempty"`
	331	Pids *LinuxPids `json:"pids,omitempty"`
327	332	// BlockIO restriction configuration
328		BlockIO *BlockIO `json:"blockIO,omitempty"`
	333	BlockIO *LinuxBlockIO `json:"blockIO,omitempty"`
329	334	// Hugetlb limit (in bytes)
330		HugepageLimits []HugepageLimit `json:"hugepageLimits,omitempty"`
	335	HugepageLimits []LinuxHugepageLimit `json:"hugepageLimits,omitempty"`
331	336	// Network restriction configuration
332		Network *Network `json:"network,omitempty"`
333		}
334
335		// Device represents the mknod information for a Linux special device file
336		type Device struct {
	337	Network *LinuxNetwork `json:"network,omitempty"`
	338	}
	339
	340	// LinuxDevice represents the mknod information for a Linux special device file
	341	type LinuxDevice struct {
337	342	// Path to the device.
338	343	Path string `json:"path"`
339	344	// Device type, block, char, etc.

350	355	GID *uint32 `json:"gid,omitempty"`
351	356	}
352	357
353		// DeviceCgroup represents a device rule for the whitelist controller
354		type DeviceCgroup struct {
	358	// LinuxDeviceCgroup represents a device rule for the whitelist controller
	359	type LinuxDeviceCgroup struct {
355	360	// Allow or deny
356	361	Allow bool `json:"allow"`
357	362	// Device type, block, char, etc.
358		Type *string `json:"type,omitempty"`
	363	Type string `json:"type,omitempty"`
359	364	// Major is the device's major number.
360	365	Major *int64 `json:"major,omitempty"`
361	366	// Minor is the device's minor number.
362	367	Minor *int64 `json:"minor,omitempty"`
363	368	// Cgroup access permissions format, rwm.
364		Access *string `json:"access,omitempty"`
365		}
366
367		// Seccomp represents syscall restrictions
368		type Seccomp struct {
369		DefaultAction Action `json:"defaultAction"`
370		Architectures []Arch `json:"architectures"`
371		Syscalls []Syscall `json:"syscalls,omitempty"`
372		}
373
374		// Solaris contains platform specific configuration for Solaris application containers.
	369	Access string `json:"access,omitempty"`
	370	}
	371
	372	// Solaris contains platform-specific configuration for Solaris application containers.
375	373	type Solaris struct {
376	374	// SMF FMRI which should go "online" before we start the container process.
377	375	Milestone string `json:"milestone,omitempty"`

380	378	// The maximum amount of shared memory allowed for this container.
381	379	MaxShmMemory string `json:"maxShmMemory,omitempty"`
382	380	// Specification for automatic creation of network resources for this container.
383		Anet []Anet `json:"anet,omitempty"`
	381	Anet []SolarisAnet `json:"anet,omitempty"`
384	382	// Set limit on the amount of CPU time that can be used by container.
385		CappedCPU *CappedCPU `json:"cappedCPU,omitempty"`
	383	CappedCPU *SolarisCappedCPU `json:"cappedCPU,omitempty"`
386	384	// The physical and swap caps on the memory that can be used by this container.
387		CappedMemory *CappedMemory `json:"cappedMemory,omitempty"`
388		}
389
390		// CappedCPU allows users to set limit on the amount of CPU time that can be used by container.
391		type CappedCPU struct {
	385	CappedMemory *SolarisCappedMemory `json:"cappedMemory,omitempty"`
	386	}
	387
	388	// SolarisCappedCPU allows users to set limit on the amount of CPU time that can be used by container.
	389	type SolarisCappedCPU struct {
392	390	Ncpus string `json:"ncpus,omitempty"`
393	391	}
394	392
395		// CappedMemory allows users to set the physical and swap caps on the memory that can be used by this container.
396		type CappedMemory struct {
	393	// SolarisCappedMemory allows users to set the physical and swap caps on the memory that can be used by this container.
	394	type SolarisCappedMemory struct {
397	395	Physical string `json:"physical,omitempty"`
398	396	Swap string `json:"swap,omitempty"`
399	397	}
400	398
401		// Anet provides the specification for automatic creation of network resources for this container.
402		type Anet struct {
	399	// SolarisAnet provides the specification for automatic creation of network resources for this container.
	400	type SolarisAnet struct {
403	401	// Specify a name for the automatically created VNIC datalink.
404	402	Linkname string `json:"linkname,omitempty"`
405	403	// Specify the link over which the VNIC will be created.

418	416
419	417	// Windows defines the runtime configuration for Windows based containers, including Hyper-V containers.
420	418	type Windows struct {
	419	// LayerFolders contains a list of absolute paths to directories containing image layers.
	420	LayerFolders []string `json:"layerFolders"`
421	421	// Resources contains information for handling resource constraints for the container.
422	422	Resources *WindowsResources `json:"resources,omitempty"`
	423	// CredentialSpec contains a JSON object describing a group Managed Service Account (gMSA) specification.
	424	CredentialSpec interface{} `json:"credentialSpec,omitempty"`
	425	// Servicing indicates if the container is being started in a mode to apply a Windows Update servicing operation.
	426	Servicing bool `json:"servicing,omitempty"`
	427	// IgnoreFlushesDuringBoot indicates if the container is being started in a mode where disk writes are not flushed during its boot process.
	428	IgnoreFlushesDuringBoot bool `json:"ignoreFlushesDuringBoot,omitempty"`
	429	// HyperV contains information for running a container with Hyper-V isolation.
	430	HyperV *WindowsHyperV `json:"hyperv,omitempty"`
	431	// Network restriction configuration.
	432	Network *WindowsNetwork `json:"network,omitempty"`
423	433	}
424	434
425	435	// WindowsResources has container runtime resource constraints for containers running on Windows.

430	440	CPU *WindowsCPUResources `json:"cpu,omitempty"`
431	441	// Storage restriction configuration.
432	442	Storage *WindowsStorageResources `json:"storage,omitempty"`
433		// Network restriction configuration.
434		Network *WindowsNetworkResources `json:"network,omitempty"`
435	443	}
436	444
437	445	// WindowsMemoryResources contains memory resource management settings.
438	446	type WindowsMemoryResources struct {
439	447	// Memory limit in bytes.
440	448	Limit *uint64 `json:"limit,omitempty"`
441		// Memory reservation in bytes.
442		Reservation *uint64 `json:"reservation,omitempty"`
443	449	}
444	450
445	451	// WindowsCPUResources contains CPU resource management settings.
446	452	type WindowsCPUResources struct {
447	453	// Number of CPUs available to the container.
448	454	Count *uint64 `json:"count,omitempty"`
449		// CPU shares (relative weight to other containers with cpu shares). Range is from 1 to 10000.
	455	// CPU shares (relative weight to other containers with cpu shares).
450	456	Shares *uint16 `json:"shares,omitempty"`
451		// Percent of available CPUs usable by the container.
452		Percent *uint8 `json:"percent,omitempty"`
	457	// Specifies the portion of processor cycles that this container can use as a percentage times 100.
	458	Maximum *uint16 `json:"maximum,omitempty"`
453	459	}
454	460
455	461	// WindowsStorageResources contains storage resource management settings.

462	468	SandboxSize *uint64 `json:"sandboxSize,omitempty"`
463	469	}
464	470
465		// WindowsNetworkResources contains network resource management settings.
466		type WindowsNetworkResources struct {
467		// EgressBandwidth is the maximum egress bandwidth in bytes per second.
468		EgressBandwidth *uint64 `json:"egressBandwidth,omitempty"`
	471	// WindowsNetwork contains network settings for Windows containers.
	472	type WindowsNetwork struct {
	473	// List of HNS endpoints that the container should connect to.
	474	EndpointList []string `json:"endpointList,omitempty"`
	475	// Specifies if unqualified DNS name resolution is allowed.
	476	AllowUnqualifiedDNSQuery bool `json:"allowUnqualifiedDNSQuery,omitempty"`
	477	// Comma separated list of DNS suffixes to use for name resolution.
	478	DNSSearchList []string `json:"DNSSearchList,omitempty"`
	479	// Name (ID) of the container that we will share with the network stack.
	480	NetworkSharedContainerName string `json:"networkSharedContainerName,omitempty"`
	481	}
	482
	483	// WindowsHyperV contains information for configuring a container to run with Hyper-V isolation.
	484	type WindowsHyperV struct {
	485	// UtilityVMPath is an optional path to the image used for the Utility VM.
	486	UtilityVMPath string `json:"utilityVMPath,omitempty"`
	487	}
	488
	489	// LinuxSeccomp represents syscall restrictions
	490	type LinuxSeccomp struct {
	491	DefaultAction LinuxSeccompAction `json:"defaultAction"`
	492	Architectures []Arch `json:"architectures,omitempty"`
	493	Syscalls []LinuxSyscall `json:"syscalls,omitempty"`
469	494	}
470	495
471	496	// Arch used for additional architectures

490	515	ArchPPC64LE Arch = "SCMP_ARCH_PPC64LE"
491	516	ArchS390 Arch = "SCMP_ARCH_S390"
492	517	ArchS390X Arch = "SCMP_ARCH_S390X"
	518	ArchPARISC Arch = "SCMP_ARCH_PARISC"
	519	ArchPARISC64 Arch = "SCMP_ARCH_PARISC64"
493	520	)
494	521
495		// Action taken upon Seccomp rule match
496		type Action string
	522	// LinuxSeccompAction taken upon Seccomp rule match
	523	type LinuxSeccompAction string
497	524
498	525	// Define actions for Seccomp rules
499	526	const (
500		ActKill Action = "SCMP_ACT_KILL"
501		ActTrap Action = "SCMP_ACT_TRAP"
502		ActErrno Action = "SCMP_ACT_ERRNO"
503		ActTrace Action = "SCMP_ACT_TRACE"
504		ActAllow Action = "SCMP_ACT_ALLOW"
	527	ActKill LinuxSeccompAction = "SCMP_ACT_KILL"
	528	ActTrap LinuxSeccompAction = "SCMP_ACT_TRAP"
	529	ActErrno LinuxSeccompAction = "SCMP_ACT_ERRNO"
	530	ActTrace LinuxSeccompAction = "SCMP_ACT_TRACE"
	531	ActAllow LinuxSeccompAction = "SCMP_ACT_ALLOW"
505	532	)
506	533
507		// Operator used to match syscall arguments in Seccomp
508		type Operator string
	534	// LinuxSeccompOperator used to match syscall arguments in Seccomp
	535	type LinuxSeccompOperator string
509	536
510	537	// Define operators for syscall arguments in Seccomp
511	538	const (
512		OpNotEqual Operator = "SCMP_CMP_NE"
513		OpLessThan Operator = "SCMP_CMP_LT"
514		OpLessEqual Operator = "SCMP_CMP_LE"
515		OpEqualTo Operator = "SCMP_CMP_EQ"
516		OpGreaterEqual Operator = "SCMP_CMP_GE"
517		OpGreaterThan Operator = "SCMP_CMP_GT"
518		OpMaskedEqual Operator = "SCMP_CMP_MASKED_EQ"
	539	OpNotEqual LinuxSeccompOperator = "SCMP_CMP_NE"
	540	OpLessThan LinuxSeccompOperator = "SCMP_CMP_LT"
	541	OpLessEqual LinuxSeccompOperator = "SCMP_CMP_LE"
	542	OpEqualTo LinuxSeccompOperator = "SCMP_CMP_EQ"
	543	OpGreaterEqual LinuxSeccompOperator = "SCMP_CMP_GE"
	544	OpGreaterThan LinuxSeccompOperator = "SCMP_CMP_GT"
	545	OpMaskedEqual LinuxSeccompOperator = "SCMP_CMP_MASKED_EQ"
519	546	)
520	547
521		// Arg used for matching specific syscall arguments in Seccomp
522		type Arg struct {
523		Index uint `json:"index"`
524		Value uint64 `json:"value"`
525		ValueTwo uint64 `json:"valueTwo"`
526		Op Operator `json:"op"`
527		}
528
529		// Syscall is used to match a syscall in Seccomp
530		type Syscall struct {
531		Name string `json:"name"`
532		Action Action `json:"action"`
533		Args []Arg `json:"args,omitempty"`
534		}
	548	// LinuxSeccompArg used for matching specific syscall arguments in Seccomp
	549	type LinuxSeccompArg struct {
	550	Index uint `json:"index"`
	551	Value uint64 `json:"value"`
	552	ValueTwo uint64 `json:"valueTwo,omitempty"`
	553	Op LinuxSeccompOperator `json:"op"`
	554	}
	555
	556	// LinuxSyscall is used to match a syscall in Seccomp
	557	type LinuxSyscall struct {
	558	Names []string `json:"names"`
	559	Action LinuxSeccompAction `json:"action"`
	560	Args []LinuxSeccompArg `json:"args,omitempty"`
	561	}
	562
	563	// LinuxIntelRdt has container runtime resource constraints
	564	// for Intel RDT/CAT which introduced in Linux 4.10 kernel
	565	type LinuxIntelRdt struct {
	566	// The schema for L3 cache id and capacity bitmask (CBM)
	567	// Format: "L3:<cache_id0>=<cbm0>;<cache_id1>=<cbm1>;..."
	568	L3CacheSchema string `json:"l3CacheSchema,omitempty"`
	569	}

-7

specs-go/state.go less more

2	2	// State holds information about the runtime state of the container.
3	3	type State struct {
4	4	// Version is the version of the specification that is supported.
5		Version string `json:"version"`
	5	Version string `json:"ociVersion"`
6	6	// ID is the container ID
7	7	ID string `json:"id"`
8		// Status is the runtime state of the container.
	8	// Status is the runtime status of the container.
9	9	Status string `json:"status"`
10	10	// Pid is the process ID for the container process.
11		Pid int `json:"pid"`
12		// BundlePath is the path to the container's bundle directory.
13		BundlePath string `json:"bundlePath"`
14		// Annotations are the annotations associated with the container.
15		Annotations map[string]string `json:"annotations"`
	11	Pid int `json:"pid,omitempty"`
	12	// Bundle is the path to the container's bundle directory.
	13	Bundle string `json:"bundle"`
	14	// Annotations are key values associated with the container.
	15	Annotations map[string]string `json:"annotations,omitempty"`
16	16	}

-1

specs-go/version.go less more

10	10	VersionPatch = 0
11	11
12	12	// VersionDev indicates development branch. Releases will be empty string.
13		VersionDev = "-rc2-dev"
	13	VersionDev = ""
14	14	)
15	15
16	16	// Version is the specification version that the package types support.

+52

-18

style.md less more

0		# Style and conventions
	0	# <a name="styleAndConventions" />Style and conventions
1	1
2		## One sentence per line
	2	## <a name="styleOneSentence" />One sentence per line
3	3
4	4	To keep consistency throughout the Markdown files in the Open Container spec all files should be formatted one sentence per line.
5	5	This fixes two things: it makes diffing easier with git and it resolves fights about line wrapping length.
6	6	For example, this paragraph will span three lines in the Markdown source.
7	7
8		## Traditionally hex settings should use JSON integers, not JSON strings
	8	## <a name="styleHex" />Traditionally hex settings should use JSON integers, not JSON strings
9	9
10		For example, [`"classID": 1048577`][class-id] instead of `"classID": "0x100001"`.
	10	For example, [`"classID": 1048577`](config-linux.md#network) instead of `"classID": "0x100001"`.
11	11	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]).
12	12
13		## Constant names should keep redundant prefixes
	13	## <a name="styleConstantNames" />Constant names should keep redundant prefixes
14	14
15		For example, `CAP_KILL` instead of `KILL` in [`linux.capabilities`][capabilities].
	15	For example, `CAP_KILL` instead of `KILL` in [`process.capabilities`](config.md#process).
16	16	The redundancy reduction from removing the namespacing prefix is not useful enough to be worth trimming the upstream identifier ([source][keep-prefix]).
17	17
18		## Optional settings should have pointer Go types
	18	## <a name="styleOptionalSettings" />Optional settings should not have pointer Go types
19	19
20		So we have a consistent way to identify unset values ([source][optional-pointer]).
21		The exceptions are entries where the Go default for the type is a no-op in the spec, in which case `omitempty` is sufficient and no pointer is needed (sources [here][no-pointer-for-slices], [here][no-pointer-for-boolean], and [here][pointer-when-updates-require-changes]).
	20	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]).
	21	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.
	22
	23	## Links
	24
	25	Internal links should be [relative links][markdown-relative-links] when linking to content within the repository.
	26	Internal links should be used inline.
	27
	28	External links should be collected at the bottom of a markdown file and used as referenced links.
	29	See 'Referenced Links' in this [markdown quick reference][markdown-quick-reference].
	30	The use of referenced links in the markdown body helps to keep files clean and organized.
	31	This also facilitates updates of external link targets on a per-file basis.
	32
	33	Referenced links should be kept in two alphabetically sorted sets, a general reference section followed by a man page section.
	34	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.
	35	The organization and style of an existing reference section should be maintained unless it violates these style guidelines.
	36
	37	An exception to these rules is when a URL is needed contextually, for example when showing an explicit link to the reader.
22	38
23	39	## Examples
24	40
25		### Anchoring
	41	### <a name="styleAnchoring" />Anchoring
26	42
27	43	For any given section that provides a notable example, it is ideal to have it denoted with [markdown headers][markdown-headers].
28	44	The level of header should be such that it is a subheader of the header it is an example of.

46	62
47	63	```
48	64
49		### Content
	65	### <a name="styleContent" />Content
50	66
51	67	Where necessary, the values in the example can be empty or unset, but accommodate with comments regarding this intention.
52	68

85	101	}
86	102	```
87	103
88		[capabilities]: config-linux.md#capabilities
89		[class-id]: config-linux.md#network
90		[integer-over-hex]: https://github.com/opencontainers/runtime-spec/pull/267#discussion_r48360013
	104	### Links
	105
	106	The following is an example of different types of links.
	107	This is shown as a complete markdown file, where the referenced links are at the bottom.
	108
	109	```markdown
	110	The specification repository's [glossary](glossary.md) is where readers can find definitions of commonly used terms.
	111
	112	Readers may click through to the [Open Containers namespace][open-containers] on [GitHub][github].
	113
	114	The URL for the Open Containers link above is: https://github.com/opencontainers
	115
	116
	117	[github]: https://github.com
	118	[open-containers]: https://github.com/opencontainers
	119	```
	120
	121
	122	[integer-over-hex]: https://github.com/opencontainers/runtime-spec/pull/267#r48360013
91	123	[keep-prefix]: https://github.com/opencontainers/runtime-spec/pull/159#issuecomment-138728337
92		[no-pointer-for-boolean]: https://github.com/opencontainers/runtime-spec/pull/290#discussion_r50296396
93		[no-pointer-for-slices]: https://github.com/opencontainers/runtime-spec/pull/316/files#r50782982
94		[optional-pointer]: https://github.com/opencontainers/runtime-spec/pull/233#discussion_r47829711
95		[pointer-when-updates-require-changes]: https://github.com/opencontainers/runtime-spec/pull/317/files#r50932706
	124	[no-pointer-for-boolean]: https://github.com/opencontainers/runtime-spec/pull/290#r50296396
	125	[no-pointer-for-slices]: https://github.com/opencontainers/runtime-spec/pull/316#r50782982
	126	[no-pointer-for-strings]: https://github.com/opencontainers/runtime-spec/pull/653#issue-200439192
	127	[pointer-when-updates-require-changes]: https://github.com/opencontainers/runtime-spec/pull/317#r50932706
96	128	[markdown-headers]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#headings
	129	[markdown-quick-reference]: https://en.support.wordpress.com/markdown-quick-reference
	130	[markdown-relative-links]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#relative-links