Commit 87b00373c256508b10e3dbd73e78daba90b032b3 - golang-github-opencontainers-specs

drop upstream files from 'master' Dmitry Smirnov 7 years ago

29 changed file(s) with 10 addition(s) and 3781 deletion(s). Raw diff Collapse all Expand all

-1

~~.gitignore~~ less more

.pc

-18

~~.travis.yml~~ less more

0		language: go
1		go:
2		- 1.6
3		- 1.5.3
4
5		sudo: false
6
7		before_install:
8		- go version \| (grep -q 'go1.[56]' \|\| exit 0 && go get -u github.com/golang/lint/golint )
9		- go get github.com/vbatts/git-validation
10
11		install: true
12
13		script:
14		- go vet -x ./...
15		- make .golint
16		- $HOME/gopath/bin/git-validation -run DCO,short-subject -v -range ${TRAVIS_COMMIT_RANGE}
17

-280

~~ChangeLog~~ less more

0		OpenContainers Specifications
1
2		Changes with v0.5.0:
3		Breaking changes:
4
5		* specs-go: Renamed the repository from opencontainers/specs to
6		opencontainers/runtime-spec, #365
7
8		Additions:
9
10		* config: Add 'timeout' for hooks, #346
11		* config-linux: Add 'maskedPaths' and 'readonlyPaths', #364
12
13		Minor fixes and documentation:
14
15		* JSON Schema bug-fixes and improved examples, #370
16		* README: Define "unconditionally compliant", #374
17		* config: Make Markdown canonical, #342
18		* config: Explicitly list mapping from symbolic names to UID/GIDs as
19		out-of-scope, #347
20		* config-linux: Require the runtime mount namespace for namespace
21		'path' values, #275
22		* config-linux: Reword kernelTCP docs, #377
23		* specs-go: Add omitempty to 'Device' and 'Namespace', #340
24		* .travis.yml: Use built-in 'go vet' and current 'go lint', dropping
25		Go < 1.5, #372, #352
26		* implementations: Expand ocitools scope to include testing, #328
27		* style: Move one-sentence-per-line rule from the README, #369
28		* style: Remove dangling parenthesis, #359
29		* README: Add a link to the IRC logs, #358
30		* Fix "manadate", "exmaple", "paramters", and "preferrably" typos,
31		#353, #354
32
33		Changes with v0.4.0:
34		Breaking changes:
35
36		* config: Move capabilities, selinuxProcessLabel, apparmorProfile,
37		and noNewPrivileges from the linux setting to the process setting
38		and make them optional, renaming selinuxProcessLabel to
39		selinuxLabel, #329, #330, #339
40		* runtime: Rename version to ociVerison in the state JSON, #225
41		* runtime: Remove the directory requirement for storing state, now
42		that there is a 'state' operation, #225, #334
43		* go: Shift .go to specs-go/.go, #276
44		* config: Move rlimits to process, #341
45		* go: Move config_linux.go content into config.go, removing
46		LinuxSpec, #310
47
48		Additions:
49
50		* schema: Add JSON Schema (and validator) for `config.json`, #313
51		* config: Add annotations for opaque-to-the-runtime data, #331
52		* config-linux: Make seccomp optional, #333
53		* runtime: Added additional operations: state, stop, and exec.
54		#225
55
56		Minor fixes and documentation:
57
58		* config-linux: Change mount type from rune to string and fix
59		octal fileMode examples, #323
60		* runtime: RFC 2119 phrasing for the lifecycle, #225
61		* README: Add a full example of config.json, #276
62		* README: Replace BlueJeans with UberConference, #326, #338
63		* style: Document Go-pointer exceptions, #317
64
65		Changes with v0.3.0:
66		Breaking changes:
67
68		* config: Single, unified config file, #284
69		* config: cwd is a required default, and must be absolute, #286,
70		#307, #308, #312
71		* config: qualify the name of the version field, #309
72		* config-linux: Convert classID from hex to uint32, #296
73		* config-linux: Separate mknod from cgroups, #298
74
75		Additions:
76
77		* config-linux: Add NoNewPrivileges setting for linux, #290
78
79		Minor fixes and documentation:
80
81		* config-linux: clarify oom_score_adj, #236, #292
82		* config-linux: Update links to cgroups documentation, #318
83		* config-linux: Remove pointers for slices preferring omitempty
84		tag instead, #316
85		* README: add runtime, bundle, and hook author user, #280
86		* ROADMAP: reshuffled and split into GitHub issues, #300, #301,
87		#304, #306
88		* style: Collect established styles in a discoverable location, #287, #311
89
90		Changes with v0.2.0:
91		* Add Apparmor, Selinux and Seccomp
92		* Add Apparmor, Selinux and Seccomp sections
93		* Add bind mount example
94		* Add fd section for linux container process
95		* Add Go types for specification
96		* *: adding a code of conduct
97		* Adding cgroups path to the Spec.
98		* .: Adding listing of implementations
99		* .: adding travis file for future CI
100		* Add license and DCO information for contributions
101		* Add linux spec description
102		* Add MAINTAINERS file
103		* Add memory swappiness to linux spec
104		* Add runtime state configuration and structs
105		* Adds a section for user namespace mappings
106		* Adds link to kernel cgroups documentation
107		* Adds section for Linux Rlimits
108		* Adds section for Linux Sysctl.
109		* Adds user namespace to the list of namespaces
110		* bundle: add initial run use case
111		* bundle: Fix 'and any number of and other related' typo
112		* bundle.md: clarify arbitrary/conventional dirnames
113		* bundle.md: fix link formatting
114		* bundle.md: fix off-by-one error
115		* bundle.md: various updates to latest spec
116		* bundle: Move 'Linux sysctl' header to its own line
117		* Change commiter to committer
118		* Change Device field order in spec_linux.go, 'Path' should be top of the 'Type' field, according to the different of the config-linux.md, 'Path' field is the unique key.
119		* Change layout of mountpoints and mounts
120		* Change the rlimit type to string instead of int
121		* Clarify behavior around namespaces paths.
122		* config: Add example additionalGids
123		* config: Add example cwd
124		* config: cleanup language on readonly parameter
125		* config: fix links to go files
126		* config-linux: specify the default devices/filesystems available
127		* config.md: clarify destination for mounts
128		* config.md: make the version a semver
129		* config.md: make the version field example a semver
130		* config.md: minor clean up of process specification
131		* config.md: reformat into a standard style
132		* config.md: update links to spec schema code
133		* config.md: various cleanup/consistency fixes
134		* config: minor cleanup
135		* Deduplicate the field of RootfsPropagation
136		* Define constants for Linux Namespace names
137		* Fix LinuxRuntime field
138		* Fix root object keys
139		* Fix typos in config.md
140		* Fix typos in the "Namespace types" section
141		* Fix typos in the rlimits section
142		* Fix Windows path escaping in example mount JSON
143		* JSON objects are easier to parse/manipulate
144		* made repo public. Added warning in README
145		* Make namespaces match runc
146		* make rootfs mount propagation mode settable
147		* Makes namespaces description linux specific
148		* *.md: markdown formatting
149		* Modify the capabilities constants to match header files like other constants
150		* Move linux specific options to linux spec
151		* README: add a rule for paragraph formatting in markdown
152		* README: Document BlueJeans and wiki archive for meetings
153		* README: Document pre-meeting agenda alteration
154		* README: Document YouTube and IRC backchannel for meetings
155		* README: Focus on local runtime (create/start/stop)
156		* README.md: Add a git commit style guide
157		* README.md: contribution about discussion
158		* README: releases section
159		* README: Remove blank line from infrastructure-agnostic paragraph
160		* removed boilerplate file
161		* *: remove superfluous comma in code-of-conduct
162		* Remove trailing whitespace
163		* Rename SystemProperties to Sysctl
164		* Rename the header "Access to devices" to "Devices" to fit with the config
165		* *: re-org the spec
166		* Replace Linux.Device with more specific config
167		* restore formatting
168		* Return golang compliant names for UID and GID in User
169		* Return golint-compliant naming for mappings
170		* runtime: Add prestart/poststop hooks
171		* runtime_config: comments for golint
172		* runtime-config-linux: Drop 'Linux' from headers
173		* runtime_config_linux: Fix 'LinuxSpec' -> 'LinuxRuntimeSpec' in comment
174		* runtime-config-linux: One sentence per line for opening two paragraphs
175		* runtime-config: Remove blank lines from the end of files
176		* runtime-config: Remove 'destination' docs from mounts
177		* runtime.md: convert oc to runc
178		* runtime: use opencontainer vs oci
179		* *: small spelling fixes
180		* Specific platform specific user struct for spec
181		* spec: linux: add support for the PIDs cgroup
182		* spec_linux: conform to `golint`
183		* spec_linux.go: Rename IDMapping fields to follow syscall.SysProcIDMap
184		* spec_linux: remove ending periods on one-line comments
185		* spec: rename ocp to oci and add a link
186		* specs: add json notation
187		* specs: align the ascii graph
188		* specs: fix the description for the [ug]idMappings
189		* specs: introduce the concept of a runtime.json
190		* .tools: cleanup the commit entry
191		* .tools: repo validation tool
192		* travis: fix DCO validation for merges
193		* typo: containers -> container's
194		* typo: the -> for
195		* Update config-linux for better formatting on values
196		* Update README.md
197		* Update readme with weekly call and mailing list
198		* Update runtime.md
199		* Update runtime.md
200		* Update runtime.md
201		* version: more explicit version for comparison
202
203		Changes with v0.1.0:
204		* Add Architecture field to Seccomp configuration in Linux runtime
205		* Add @hqhq as maintainer
206		* Add hyphen for host specific
207		* Adding Vishnu Kannan as a Maintainer.
208		* Add initial roadmap
209		* Add lifecycle for containers
210		* Add oom_score_adj to the runtime Spec.
211		* Add post-start hooks
212		* Add Seccomp constants to description of Linux runtime spec
213		* Add Seccomp constants to Linux runtime config
214		* Add some clarity around the state.json file
215		* adds text describing the upper-case keywords used in the spec
216		* add testing framework to ROADMAP
217		* Appropriately mark optional fields as omitempty
218		* cgroup: Add support for memory.kmem.tcp.limit_in_bytes
219		* Change HugepageLimit.Limit type to uint64
220		* Change the behavior when cgroupsPath is absent
221		* Change version from 0.1.0 to 0.2.0
222		* Clarify the semantics of hook elements
223		* Cleanup bundle.md
224		* Cleanup principles
225		* config: linux: update description of PidsLimit
226		* config: Require a new UTS namespace for config.json's hostname
227		* config: Require the runtime to mount Spec.Mounts in order
228		* convert name to `name`
229		* Example lists "root' but text mentions "bundlePath"
230		* Fix an extra space in VersionMinor
231		* Fix golint warnings
232		* Fix typo in BlockIO struct comment
233		* Fix typo in Filesystem Bundle
234		* Fix value of swappiness
235		* glossary: Provide a quick overview of important terms
236		* glossary: Specify UTF-8 for all our JSON
237		* hooks: deduplicate the hooks docs
238		* implementations: Link to kunalkushwaha/octool
239		* implementations: Link to mrunalp/ocitools
240		* lifecycle: Don't require /run/opencontainer/<runtime>/containers
241		* lifecycle: Mention runtime.json
242		* lifecycle: no hypens
243		* MAINTAINERS: add tianon per the charter
244		* MAINTAINERS: correct Vish's github account
245		* Makefile: Add glossary to DOC_FILES
246		* Make optional Cgroup related config params pointers along with `omitempty` json tag.
247		* Mark RootfsPropagation as omitempty
248		* *.md: update TOC and links
249		* move the description of Rlimits before example
250		* move the description of user ns mapping to proper file
251		* principles: Give principles their own home
252		* *: printable documents
253		* Project: document release process
254		* README: Fix some headers
255		* README: make header more concise
256		* remove blank char from blank line
257		* Remove the unneeded build tag from the config_linux.go
258		* Remove trailing comma in hooks json example
259		* Rename State's Root to Bundle
260		* ROADMAP.md: remove the tail spaces
261		* roadmap: update links and add wiki reference
262		* runtime: Add 'version' to the state.json example
263		* runtime-config: add example label before json example
264		* runtime-config: add section about Hooks
265		* runtime: config: linux: add cgroups information
266		* runtime: config: linux: Edit BlockIO struct
267		* runtime: config: linux: Fix typo and trailing commas in json example
268		* runtime_config_linux.go: add missing pointer
269		* runtime-config-linux.md: fix the type of cpus and mems
270		* runtime.md: fix spacing
271		* Talk about host specific/independent instead of mutability
272		* .tools: commit validator is a separate project
273		* .tools: make GetFetchHeadCommit do what it says
274		* .travis.yml: add go 1.5.1, update from 1.4.2 to 1.4.3
275		* Update readme with wiki link to minutes
276		* Update Typo in ROADMAP.md
277		* Use unsigned for IDs
278		* version: introduce a string for dev indication
279

-191

~~LICENSE~~ less more

0
1		Apache License
2		Version 2.0, January 2004
3		http://www.apache.org/licenses/
4
5		TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
7		1. Definitions.
8
9		"License" shall mean the terms and conditions for use, reproduction,
10		and distribution as defined by Sections 1 through 9 of this document.
11
12		"Licensor" shall mean the copyright owner or entity authorized by
13		the copyright owner that is granting the License.
14
15		"Legal Entity" shall mean the union of the acting entity and all
16		other entities that control, are controlled by, or are under common
17		control with that entity. For the purposes of this definition,
18		"control" means (i) the power, direct or indirect, to cause the
19		direction or management of such entity, whether by contract or
20		otherwise, or (ii) ownership of fifty percent (50%) or more of the
21		outstanding shares, or (iii) beneficial ownership of such entity.
22
23		"You" (or "Your") shall mean an individual or Legal Entity
24		exercising permissions granted by this License.
25
26		"Source" form shall mean the preferred form for making modifications,
27		including but not limited to software source code, documentation
28		source, and configuration files.
29
30		"Object" form shall mean any form resulting from mechanical
31		transformation or translation of a Source form, including but
32		not limited to compiled object code, generated documentation,
33		and conversions to other media types.
34
35		"Work" shall mean the work of authorship, whether in Source or
36		Object form, made available under the License, as indicated by a
37		copyright notice that is included in or attached to the work
38		(an example is provided in the Appendix below).
39
40		"Derivative Works" shall mean any work, whether in Source or Object
41		form, that is based on (or derived from) the Work and for which the
42		editorial revisions, annotations, elaborations, or other modifications
43		represent, as a whole, an original work of authorship. For the purposes
44		of this License, Derivative Works shall not include works that remain
45		separable from, or merely link (or bind by name) to the interfaces of,
46		the Work and Derivative Works thereof.
47
48		"Contribution" shall mean any work of authorship, including
49		the original version of the Work and any modifications or additions
50		to that Work or Derivative Works thereof, that is intentionally
51		submitted to Licensor for inclusion in the Work by the copyright owner
52		or by an individual or Legal Entity authorized to submit on behalf of
53		the copyright owner. For the purposes of this definition, "submitted"
54		means any form of electronic, verbal, or written communication sent
55		to the Licensor or its representatives, including but not limited to
56		communication on electronic mailing lists, source code control systems,
57		and issue tracking systems that are managed by, or on behalf of, the
58		Licensor for the purpose of discussing and improving the Work, but
59		excluding communication that is conspicuously marked or otherwise
60		designated in writing by the copyright owner as "Not a Contribution."
61
62		"Contributor" shall mean Licensor and any individual or Legal Entity
63		on behalf of whom a Contribution has been received by Licensor and
64		subsequently incorporated within the Work.
65
66		2. Grant of Copyright License. Subject to the terms and conditions of
67		this License, each Contributor hereby grants to You a perpetual,
68		worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69		copyright license to reproduce, prepare Derivative Works of,
70		publicly display, publicly perform, sublicense, and distribute the
71		Work and such Derivative Works in Source or Object form.
72
73		3. Grant of Patent License. Subject to the terms and conditions of
74		this License, each Contributor hereby grants to You a perpetual,
75		worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76		(except as stated in this section) patent license to make, have made,
77		use, offer to sell, sell, import, and otherwise transfer the Work,
78		where such license applies only to those patent claims licensable
79		by such Contributor that are necessarily infringed by their
80		Contribution(s) alone or by combination of their Contribution(s)
81		with the Work to which such Contribution(s) was submitted. If You
82		institute patent litigation against any entity (including a
83		cross-claim or counterclaim in a lawsuit) alleging that the Work
84		or a Contribution incorporated within the Work constitutes direct
85		or contributory patent infringement, then any patent licenses
86		granted to You under this License for that Work shall terminate
87		as of the date such litigation is filed.
88
89		4. Redistribution. You may reproduce and distribute copies of the
90		Work or Derivative Works thereof in any medium, with or without
91		modifications, and in Source or Object form, provided that You
92		meet the following conditions:
93
94		(a) You must give any other recipients of the Work or
95		Derivative Works a copy of this License; and
96
97		(b) You must cause any modified files to carry prominent notices
98		stating that You changed the files; and
99
100		(c) You must retain, in the Source form of any Derivative Works
101		that You distribute, all copyright, patent, trademark, and
102		attribution notices from the Source form of the Work,
103		excluding those notices that do not pertain to any part of
104		the Derivative Works; and
105
106		(d) If the Work includes a "NOTICE" text file as part of its
107		distribution, then any Derivative Works that You distribute must
108		include a readable copy of the attribution notices contained
109		within such NOTICE file, excluding those notices that do not
110		pertain to any part of the Derivative Works, in at least one
111		of the following places: within a NOTICE text file distributed
112		as part of the Derivative Works; within the Source form or
113		documentation, if provided along with the Derivative Works; or,
114		within a display generated by the Derivative Works, if and
115		wherever such third-party notices normally appear. The contents
116		of the NOTICE file are for informational purposes only and
117		do not modify the License. You may add Your own attribution
118		notices within Derivative Works that You distribute, alongside
119		or as an addendum to the NOTICE text from the Work, provided
120		that such additional attribution notices cannot be construed
121		as modifying the License.
122
123		You may add Your own copyright statement to Your modifications and
124		may provide additional or different license terms and conditions
125		for use, reproduction, or distribution of Your modifications, or
126		for any such Derivative Works as a whole, provided Your use,
127		reproduction, and distribution of the Work otherwise complies with
128		the conditions stated in this License.
129
130		5. Submission of Contributions. Unless You explicitly state otherwise,
131		any Contribution intentionally submitted for inclusion in the Work
132		by You to the Licensor shall be under the terms and conditions of
133		this License, without any additional terms or conditions.
134		Notwithstanding the above, nothing herein shall supersede or modify
135		the terms of any separate license agreement you may have executed
136		with Licensor regarding such Contributions.
137
138		6. Trademarks. This License does not grant permission to use the trade
139		names, trademarks, service marks, or product names of the Licensor,
140		except as required for reasonable and customary use in describing the
141		origin of the Work and reproducing the content of the NOTICE file.
142
143		7. Disclaimer of Warranty. Unless required by applicable law or
144		agreed to in writing, Licensor provides the Work (and each
145		Contributor provides its Contributions) on an "AS IS" BASIS,
146		WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147		implied, including, without limitation, any warranties or conditions
148		of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149		PARTICULAR PURPOSE. You are solely responsible for determining the
150		appropriateness of using or redistributing the Work and assume any
151		risks associated with Your exercise of permissions under this License.
152
153		8. Limitation of Liability. In no event and under no legal theory,
154		whether in tort (including negligence), contract, or otherwise,
155		unless required by applicable law (such as deliberate and grossly
156		negligent acts) or agreed to in writing, shall any Contributor be
157		liable to You for damages, including any direct, indirect, special,
158		incidental, or consequential damages of any character arising as a
159		result of this License or out of the use or inability to use the
160		Work (including but not limited to damages for loss of goodwill,
161		work stoppage, computer failure or malfunction, or any and all
162		other commercial damages or losses), even if such Contributor
163		has been advised of the possibility of such damages.
164
165		9. Accepting Warranty or Additional Liability. While redistributing
166		the Work or Derivative Works thereof, You may choose to offer,
167		and charge a fee for, acceptance of support, warranty, indemnity,
168		or other liability obligations and/or rights consistent with this
169		License. However, in accepting such obligations, You may act only
170		on Your own behalf and on Your sole responsibility, not on behalf
171		of any other Contributor, and only if You agree to indemnify,
172		defend, and hold each Contributor harmless for any liability
173		incurred by, or claims asserted against, such Contributor by reason
174		of your accepting any such warranty or additional liability.
175
176		END OF TERMS AND CONDITIONS
177
178		Copyright 2015 The Linux Foundation.
179
180		Licensed under the Apache License, Version 2.0 (the "License");
181		you may not use this file except in compliance with the License.
182		You may obtain a copy of the License at
183
184		http://www.apache.org/licenses/LICENSE-2.0
185
186		Unless required by applicable law or agreed to in writing, software
187		distributed under the License is distributed on an "AS IS" BASIS,
188		WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
189		See the License for the specific language governing permissions and
190		limitations under the License.

-9

~~MAINTAINERS~~ less more

0		Michael Crosby <michael@docker.com> (@crosbymichael)
1		Alexander Morozov <lk4d4@docker.com> (@LK4D4)
2		Vishnu Kannan <vishnuk@google.com> (@vishh)
3		Mrunal Patel <mpatel@redhat.com> (@mrunalp)
4		Vincent Batts <vbatts@redhat.com> (@vbatts)
5		Daniel, Dao Quang Minh <dqminh89@gmail.com> (@dqminh)
6		Brandon Philips <brandon.philips@coreos.com> (@philips)
7		Tianon Gravi <admwiggin@gmail.com> (@tianon)
8		Qiang Huang <h.huangqiang@huawei.com> (@hqhq)

-69

~~Makefile~~ less more

0
1		DOCKER ?= $(shell which docker)
2		DOC_FILES := \
3		README.md \
4		code-of-conduct.md \
5		principles.md \
6		style.md \
7		ROADMAP.md \
8		implementations.md \
9		bundle.md \
10		runtime.md \
11		runtime-linux.md \
12		config.md \
13		config-linux.md \
14		glossary.md
15		EPOCH_TEST_COMMIT := 041eb73d2e0391463894c04c8ac938036143eba3
16
17		docs: pdf html
18		.PHONY: docs
19
20		pdf:
21		@mkdir -p output/ && \
22		$(DOCKER) run \
23		-it \
24		--rm \
25		-v $(shell pwd)/:/input/:ro \
26		-v $(shell pwd)/output/:/output/ \
27		-u $(shell id -u) \
28		vbatts/pandoc -f markdown_github -t latex -o /output/docs.pdf $(patsubst %,/input/%,$(DOC_FILES)) && \
29		ls -sh $(shell readlink -f output/docs.pdf)
30
31		html:
32		@mkdir -p output/ && \
33		$(DOCKER) run \
34		-it \
35		--rm \
36		-v $(shell pwd)/:/input/:ro \
37		-v $(shell pwd)/output/:/output/ \
38		-u $(shell id -u) \
39		vbatts/pandoc -f markdown_github -t html5 -o /output/docs.html $(patsubst %,/input/%,$(DOC_FILES)) && \
40		ls -sh $(shell readlink -f output/docs.html)
41
42
43		HOST_GOLANG_VERSION = $(shell go version \| cut -d ' ' -f3 \| cut -c 3-)
44		# this variable is used like a function. First arg is the minimum version, Second arg is the version to be checked.
45		ALLOWED_GO_VERSION = $(shell test '$(shell /bin/echo -e "$(1)\n$(2)" \| sort -V \| head -n1)' == '$(1)' && echo 'true')
46
47		.PHONY: test .govet .golint .gitvalidation
48
49		test: .govet .golint .gitvalidation
50
51		# `go get golang.org/x/tools/cmd/vet`
52		.govet:
53		go vet -x ./...
54
55		# `go get github.com/golang/lint/golint`
56		.golint:
57		ifeq ($(call ALLOWED_GO_VERSION,1.5,$(HOST_GOLANG_VERSION)),true)
58		golint ./...
59		endif
60
61
62		# `go get github.com/vbatts/git-validation`
63		.gitvalidation:
64		git-validation -q -run DCO,short-subject -v -range $(EPOCH_TEST_COMMIT)..HEAD
65
66		clean:
67		rm -rf output/ *~
68

-158

~~README.md~~ less more

0		# Open Container Runtime Specification
1
2		The [Open Container Initiative](http://www.opencontainers.org/) develops specifications for standards on Operating System process and application containers.
3
4
5		Table of Contents
6
7		- [Introduction](README.md)
8		- [Code of Conduct](code-of-conduct.md)
9		- [Container Principles](principles.md)
10		- [Style and Conventions](style.md)
11		- [Roadmap](ROADMAP.md)
12		- [Implementations](implementations.md)
13		- [Filesystem Bundle](bundle.md)
14		- [Runtime and Lifecycle](runtime.md)
15		- [Linux Specific Runtime](runtime-linux.md)
16		- Configuration
17		- [General](config.md)
18		- [Linux-specific](config-linux.md)
19		- [Glossary](glossary.md)
20
21		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).
22
23		An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED requirements for the protocols it implements.
24		An implementation that satisfies all the MUST or REQUIRED and all the SHOULD requirements for its protocols is said to be "unconditionally compliant".
25
26		# Use Cases
27
28		To provide context for users the following section gives example use cases for each part of the spec.
29
30		#### Application Bundle Builders
31
32		Application bundle builders can create a [bundle](bundle.md) directory that includes all of the files required for launching an application as a container.
33		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).
34		Because the configuration includes host-specific settings, application bundle directories copied between two hosts may require configuration adjustments.
35
36		#### Hook Developers
37
38		[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.
39		Example use cases include sophisticated network configuration, volume garbage collection, etc.
40
41		#### Runtime Developers
42
43		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.
44
45		# Releases
46
47		There is a loose [Road Map](./ROADMAP.md).
48		During the `0.x` series of OCI releases we make no backwards compatibility guarantees and intend to break the schema during this series.
49
50		# Contributing
51
52		Development happens on GitHub for the spec.
53		Issues are used for bugs and actionable items and longer discussions can happen on the [mailing list](#mailing-list).
54
55		The specification and code is licensed under the Apache 2.0 license found in the `LICENSE` file of this repository.
56
57		## Code of Conduct
58
59		Participation in the OpenContainers community is governed by [OpenContainer's Code of Conduct](code-of-conduct.md).
60
61		## Discuss your design
62
63		The project welcomes submissions, but please let everyone know what you are working on.
64
65		Before undertaking a nontrivial change to this specification, send mail to the [mailing list](#mailing-list) to discuss what you plan to do.
66		This gives everyone a chance to validate the design, helps prevent duplication of effort, and ensures that the idea fits.
67		It also guarantees that the design is sound before code is written; a GitHub pull-request is not the place for high-level discussions.
68
69		Typos and grammatical errors can go straight to a pull-request.
70		When in doubt, start on the [mailing-list](#mailing-list).
71
72		## Weekly Call
73
74		The contributors and maintainers of the project have a weekly meeting Wednesdays at 10:00 AM PST.
75		Everyone is welcome to participate via [UberConference web][UberConference] or audio-only: 646-494-8704 (no PIN needed.)
76		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.
77		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.
78
79		## Mailing List
80
81		You can subscribe and join the mailing list on [Google Groups](https://groups.google.com/a/opencontainers.org/forum/#!forum/dev).
82
83		## IRC
84
85		OCI discussion happens on #opencontainers on Freenode ([logs][irc-logs]).
86
87		## Git commit
88
89		### Sign your work
90
91		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.
92		The rules are pretty simple: if you can certify the below (from [developercertificate.org](http://developercertificate.org/)):
93
94		```
95		Developer Certificate of Origin
96		Version 1.1
97
98		Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
99		660 York Street, Suite 102,
100		San Francisco, CA 94110 USA
101
102		Everyone is permitted to copy and distribute verbatim copies of this
103		license document, but changing it is not allowed.
104
105
106		Developer's Certificate of Origin 1.1
107
108		By making a contribution to this project, I certify that:
109
110		(a) The contribution was created in whole or in part by me and I
111		have the right to submit it under the open source license
112		indicated in the file; or
113
114		(b) The contribution is based upon previous work that, to the best
115		of my knowledge, is covered under an appropriate open source
116		license and I have the right under that license to submit that
117		work with modifications, whether created in whole or in part
118		by me, under the same open source license (unless I am
119		permitted to submit under a different license), as indicated
120		in the file; or
121
122		(c) The contribution was provided directly to me by some other
123		person who certified (a), (b) or (c) and I have not modified
124		it.
125
126		(d) I understand and agree that this project and the contribution
127		are public and that a record of the contribution (including all
128		personal information I submit with it, including my sign-off) is
129		maintained indefinitely and may be redistributed consistent with
130		this project or the open source license(s) involved.
131		```
132
133		then you just add a line to every git commit message:
134
135		Signed-off-by: Joe Smith <joe@gmail.com>
136
137		using your real name (sorry, no pseudonyms or anonymous contributions.)
138
139		You can add the sign off when creating the git commit via `git commit -s`.
140
141		### Commit Style
142
143		Simple house-keeping for clean git history.
144		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).
145
146		1. Separate the subject from body with a blank line
147		2. Limit the subject line to 50 characters
148		3. Capitalize the subject line
149		4. Do not end the subject line with a period
150		5. Use the imperative mood in the subject line
151		6. Wrap the body at 72 characters
152		7. Use the body to explain what and why vs. how
153		* If there was important/useful/essential conversation or information, copy or include a reference
154		8. When possible, one keyword to scope the change in the subject (i.e. "README: ...", "runtime: ...")
155
156		[UberConference]: https://www.uberconference.com/ssaul
157		[irc-logs]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/

-103

~~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		### Digest and Hashing
13
14		A bundle is designed to be moved between hosts.
15		Although OCI doesn't define a transport method we should have a cryptographic digest of the on-disk bundle that can be used to verify that a bundle is not corrupted and in an expected configuration.
16
17		Owner: philips
18
19		### Define Container Lifecycle
20
21		Containers have a lifecycle and being able to identify and document the lifecycle of a container is very helpful for implementations of the spec.
22		The lifecycle events of a container also help identify areas to implement hooks that are portable across various implementations and platforms.
23
24		Owner: mrunalp
25
26		### Define Standard Container Actions (Target release: v0.3.0)
27
28		Define what type of actions a runtime can perform on a container without imposing hardships on authors of platforms that do not support advanced options.
29
30		Owner: duglin
31
32		### Container Definition
33
34		Define what a software container is and its attributes in a cross platform way.
35
36		Could be solved by lifecycle/ops and create/start split discussions
37
38		Owner: vishh & duglin
39
40		### Live Container Updates
41
42		Should we allow dynamic container updates to runtime options?
43
44		Proposal: make it an optional feature
45
46		Owner: hqhq (was vishh) robdolinms, bcorrie
47
48		### Validation Tooling (Target release: v0.3.0)
49
50		Provide validation tooling for compliance with OCI spec and runtime environment.
51
52		Owner: mrunalp
53
54		### Testing Framework
55
56		Provide a testing framework for compliance with OCI spec and runtime environment.
57
58		Owner: liangchenye
59
60		### Version Schema
61
62		Decide on a robust versioning schema for the spec as it evolves.
63
64		Resolved but release process could evolve. Resolved for v0.2.0, expect to revisit near v1.0.0
65
66		Owner: vbatts
67
68		### Printable/Compiled Spec
69
70		Regardless of how the spec is written, ensure that it is easy to read and follow for first time users.
71
72		Part of this is resolved. Produces an html & pdf.
73		Done
74		Would be nice to publish to the OCI web site as part of our release process.
75
76		Owner: vbatts
77
78		### Base Config Compatibility
79
80		Ensure that the base configuration format is viable for various platforms.
81
82		Systems:
83
84		* Solaris
85		* Windows
86		* Linux
87
88		Owner: robdolinms as lead coordinator
89
90		### Full Lifecycle Hooks
91
92		Ensure that we have lifecycle hooks in the correct places with full coverage over the container lifecycle.
93
94		Will probably go away with Vish's work on splitting create and start, and if we have exec.
95
96		Owner:
97
98		### Distributable Format
99
100		A common format for serializing and distributing bundles.
101
102		Owner: vbatts

-24

~~bundle.md~~ less more

0		# Filesystem Bundle
1
2		## Container Format
3
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.
6
7		The definition of a bundle is only concerned with how a container, and its configuration data, are stored on a local file system so that it can be consumed by a compliant runtime.
8
9		A Standard Container bundle contains all the information needed to load and run a container.
10		This includes the following artifacts which MUST all reside in the same directory on the local filesystem:
11
12		1. `config.json` : contains configuration data.
13		This REQUIRED file, which MUST be named `config.json`.
14		When the bundle is packaged up for distribution, this file MUST be included.
15		See [`config.json`](config.md) for more details.
16
17		2. A directory representing the root filesystem of the container.
18		While the name of this REQUIRED directory may be arbitrary, users should consider using a conventional name, such as `rootfs`.
19		When the bundle is packaged up for distribution, this directory MUST be included.
20		This directory MUST be referenced from within the `config.json` file.
21
22		While these artifacts MUST all be present in a single directory on the local filesystem, that directory itself is not part of the bundle.
23		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.

-37

~~code-of-conduct.md~~ less more

0		# OpenContainers Code of Conduct
1
2		Behave as a community member, follow the code of conduct.
3
4		## Code of Conduct
5
6		The OpenContainers community is made up of a mixture of professionals and volunteers from all over the world.
7
8		When we disagree, we try to understand why.
9		Disagreements, both social and technical, happen all the time and OpenContainers is no exception.
10		It is important that we resolve disagreements and differing views constructively.
11
12		This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
13		Participants should be aware of these concerns.
14
15		We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
16
17		Examples of unacceptable behavior by participants include:
18
19		* The use of sexualized language or imagery
20		* Personal attacks
21		* Trolling or insulting/derogatory comments
22		* Public or private harassment
23		* Publishing other's private information, such as physical or electronic addresses, without explicit permission
24		* Other unethical or unprofessional conduct
25
26		The OpenContainers team does not condone any statements by speakers contrary to these standards.
27		The OpenContainers team reserves the right to deny participation any individual found to be engaging in discriminatory or harassing actions.
28
29		Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct.
30		By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project.
31
32		## Thanks
33
34		Thanks to the [Fedora Code of Conduct](https://getfedora.org/code-of-conduct) and [Contributor Covenant](http://contributor-covenant.org) for inspiration and ideas.
35
36		Portions of this Code of Conduct are adapted from the Contributor Covenant, version 1.2.0, available at http://contributor-covenant.org/version/1/2/0/

-569

~~config-linux.md~~ less more

0		# Linux-specific Container Configuration
1
2		The Linux container specification uses various kernel features like namespaces, cgroups, capabilities, LSM, and file system jails to fulfill the spec.
3		Additional information is needed for Linux over the [default spec configuration](config.md) in order to configure these various kernel features.
4
5		## Default File Systems
6
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 \|
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
20
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		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).
24
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:
29		* `pid` processes inside the container will only be able to see other processes inside the same container
30		* `network` the container will have its own network stack
31		* `mount` the container will have an isolated mount table
32		* `ipc` processes inside the container will only be able to communicate to other processes inside the same container via system level IPC
33		* `uts` the container will be able to have its own hostname and domain name
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
36		* `path` (string, optional) - path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace)
37
38		If a path is specified, that particular file is used to join that type of namespace.
39		Also, when a path is specified, a runtime MUST assume that the setup for that particular namespace has already been done and error out if the config specifies anything else related to that namespace.
40
41		###### Example
42
43		```json
44		"namespaces": [
45		{
46		"type": "pid",
47		"path": "/proc/1234/ns/pid"
48		},
49		{
50		"type": "network",
51		"path": "/var/run/netns/neta"
52		},
53		{
54		"type": "mount"
55		},
56		{
57		"type": "ipc"
58		},
59		{
60		"type": "uts"
61		},
62		{
63		"type": "user"
64		}
65		]
66		```
67
68		## User namespace mappings
69
70		###### Example
71
72		```json
73		"uidMappings": [
74		{
75		"hostID": 1000,
76		"containerID": 0,
77		"size": 10
78		}
79		],
80		"gidMappings": [
81		{
82		"hostID": 1000,
83		"containerID": 0,
84		"size": 10
85		}
86		]
87		```
88
89		uid/gid mappings describe the user namespace mappings from the host to the container.
90		The mappings represent how the bundle `rootfs` expects the user namespace to be setup and the runtime SHOULD NOT modify the permissions on the rootfs to realize the mapping.
91		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.
92		There is a limit of 5 mappings which is the Linux kernel hard limit.
93
94		## Devices
95
96		`devices` is an array specifying the list of devices that MUST be available in the container.
97		The runtime may supply them however it likes (with [mknod][mknod.2], by bind mounting from the runtime mount namespace, etc.).
98
99		The following parameters can be specified:
100
101		* `type` (string, required) - type of device: `c`, `b`, `u` or `p`.
102		More info in [mknod(1)][mknod.1].
103		* `path` (string, required) - full path to device inside container.
104		* `major, minor` (int64, required unless `type`* is `p`)* - [major, minor numbers][devices] for the device.
105		* `fileMode` (uint32, optional) - file mode for the device.
106		You can also control access to devices [with cgroups](#device-whitelist).
107		* `uid` (uint32, optional) - id of device owner.
108		* `gid` (uint32, optional) - id of device group.
109
110		###### Example
111
112		```json
113		"devices": [
114		{
115		"path": "/dev/fuse",
116		"type": "c",
117		"major": 10,
118		"minor": 229,
119		"fileMode": 438,
120		"uid": 0,
121		"gid": 0
122		},
123		{
124		"path": "/dev/sda",
125		"type": "b",
126		"major": 8,
127		"minor": 0,
128		"fileMode": 432,
129		"uid": 0,
130		"gid": 0
131		}
132		]
133		```
134
135		###### Default Devices
136
137		In addition to any devices configured with this setting, the runtime MUST also supply:
138
139		* [`/dev/null`][null.4]
140		* [`/dev/zero`][zero.4]
141		* [`/dev/full`][full.4]
142		* [`/dev/random`][random.4]
143		* [`/dev/urandom`][random.4]
144		* [`/dev/tty`][tty.4]
145		* [`/dev/console`][console.4]
146		* [`/dev/ptmx`][pts.4].
147		A [bind-mount or symlink of the container's `/dev/pts/ptmx`][devpts].
148
149		## Control groups
150
151		Also known as cgroups, they are used to restrict resource usage for a container and handle device access.
152		cgroups provide controls to restrict cpu, memory, IO, pids and network for the container.
153		For more information, see the [kernel cgroups documentation][cgroup-v1].
154
155		The path to the cgroups can be specified in the Spec via `cgroupsPath`.
156		`cgroupsPath` is expected to be relative to the cgroups mount point.
157		If `cgroupsPath` is not specified, implementations can define the default cgroup path.
158		Implementations of the Spec can choose to name cgroups in any manner.
159		The Spec does not include naming schema for cgroups.
160		The Spec does not support [split hierarchy][cgroup-v2].
161		The cgroups will be created if they don't exist.
162
163		###### Example
164
165		```json
166		"cgroupsPath": "/myRuntime/myContainer"
167		```
168
169		`cgroupsPath` can be used to either control the cgroups hierarchy for containers or to run a new process in an existing container.
170
171		You can configure a container's cgroups via the `resources` field of the Linux configuration.
172		Do not specify `resources` unless limits have to be updated.
173		For example, to run a new process in an existing container without updating limits, `resources` need not be specified.
174
175		#### Device whitelist
176
177		`devices` is an array of entries to control the [device whitelist][cgroup-v1-devices].
178		The runtime MUST apply entries in the listed order.
179
180		The following parameters can be specified:
181
182		* `allow` (boolean, required) - whether the entry is allowed or denied.
183		* `type` (string, optional) - type of device: `a` (all), `c` (char), or `b` (block).
184		`null` or unset values mean "all", mapping to `a`.
185		* `major, minor` (int64, optional) - [major, minor numbers][devices] for the device.
186		`null` or unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices].
187		* `access` (string, optional) - cgroup permissions for device.
188		A composition of `r` (read), `w` (write), and `m` (mknod).
189
190		###### Example
191
192		```json
193		"devices": [
194		{
195		"allow": false,
196		"access": "rwm"
197		},
198		{
199		"allow": true,
200		"type": "c",
201		"major": 10,
202		"minor": 229,
203		"access": "rw"
204		},
205		{
206		"allow": true,
207		"type": "b",
208		"major": 8,
209		"minor": 0,
210		"access": "r"
211		}
212		]
213		```
214
215		#### Disable out-of-memory killer
216
217		`disableOOMKiller` contains a boolean (`true` or `false`) that enables or disables the Out of Memory killer for a cgroup.
218		If enabled (`false`), tasks that attempt to consume more memory than they are allowed are immediately killed by the OOM killer.
219		The OOM killer is enabled by default in every cgroup using the `memory` subsystem.
220		To disable it, specify a value of `true`.
221		For more information, see [the memory cgroup man page][cgroup-v1-memory].
222
223		* `disableOOMKiller` (bool, optional) - enables or disables the OOM killer
224
225		###### Example
226
227		```json
228		"disableOOMKiller": false
229		```
230
231		#### Set oom_score_adj
232
233		`oomScoreAdj` sets heuristic regarding how the process is evaluated by the kernel during memory pressure.
234		For more information, see [the proc filesystem documentation section 3.1](https://www.kernel.org/doc/Documentation/filesystems/proc.txt).
235		This is a kernel/system level setting, where as `disableOOMKiller` is scoped for a memory cgroup.
236		For more information on how these two settings work together, see [the memory cgroup documentation section 10. OOM Contol][cgroup-v1-memory].
237
238		* `oomScoreAdj` (int, optional) - adjust the oom-killer score
239
240		###### Example
241
242		```json
243		"oomScoreAdj": 100
244		```
245
246		#### Memory
247
248		`memory` represents the cgroup subsystem `memory` and it's used to set limits on the container's memory usage.
249		For more information, see [the memory cgroup man page][cgroup-v1-memory].
250
251		The following parameters can be specified to setup the controller:
252
253		* `limit` (uint64, optional) - sets limit of memory usage in bytes
254
255		* `reservation` (uint64, optional) - sets soft limit of memory usage in bytes
256
257		* `swap` (uint64, optional) - sets limit of memory+Swap usage
258
259		* `kernel` (uint64, optional) - sets hard limit for kernel memory
260
261		* `kernelTCP` (uint64, optional) - sets hard limit in bytes for kernel TCP buffer memory
262
263		* `swappiness` (uint64, optional) - sets swappiness parameter of vmscan (See sysctl's vm.swappiness)
264
265		###### Example
266
267		```json
268		"memory": {
269		"limit": 536870912,
270		"reservation": 536870912,
271		"swap": 536870912,
272		"kernel": 0,
273		"kernelTCP": 0,
274		"swappiness": 0
275		}
276		```
277
278		#### CPU
279
280		`cpu` represents the cgroup subsystems `cpu` and `cpusets`.
281		For more information, see [the cpusets cgroup man page][cgroup-v1-cpusets].
282
283		The following parameters can be specified to setup the controller:
284
285		* `shares` (uint64, optional) - specifies a relative share of CPU time available to the tasks in a cgroup
286
287		* `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)
288
289		* `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)
290
291		* `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
292
293		* `realtimePeriod` (uint64, optional) - same as `period` but applies to realtime scheduler only
294
295		* `cpus` (string, optional) - list of CPUs the container will run in
296
297		* `mems` (string, optional) - list of Memory Nodes the container will run in
298
299		###### Example
300
301		```json
302		"cpu": {
303		"shares": 1024,
304		"quota": 1000000,
305		"period": 500000,
306		"realtimeRuntime": 950000,
307		"realtimePeriod": 1000000,
308		"cpus": "2-3",
309		"mems": "0-7"
310		}
311		```
312
313		#### Block IO Controller
314
315		`blockIO` represents the cgroup subsystem `blkio` which implements the block io controller.
316		For more information, see [the kernel cgroups documentation about blkio][cgroup-v1-blkio].
317
318		The following parameters can be specified to setup the controller:
319
320		* `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.
321
322		* `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.
323
324		* `blkioWeightDevice` (array, optional) - specifies the list of devices which will be bandwidth rate limited. The following parameters can be specified per-device:
325		* `major, minor` (int64, required) - major, minor numbers for device. More info in `man mknod`.
326		* `weight` (uint16, optional) - bandwidth rate for the device, range is from 10 to 1000
327		* `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
328
329		You must specify at least one of `weight` or `leafWeight` in a given entry, and can specify both.
330
331		* `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:
332		* `major, minor` (int64, required) - major, minor numbers for device. More info in `man mknod`.
333		* `rate` (uint64, required) - IO rate limit for the device
334
335		###### Example
336
337		```json
338		"blockIO": {
339		"blkioWeight": 10,
340		"blkioLeafWeight": 10,
341		"blkioWeightDevice": [
342		{
343		"major": 8,
344		"minor": 0,
345		"weight": 500,
346		"leafWeight": 300
347		},
348		{
349		"major": 8,
350		"minor": 16,
351		"weight": 500
352		}
353		],
354		"blkioThrottleReadBpsDevice": [
355		{
356		"major": 8,
357		"minor": 0,
358		"rate": 600
359		}
360		],
361		"blkioThrottleWriteIOPSDevice": [
362		{
363		"major": 8,
364		"minor": 16,
365		"rate": 300
366		}
367		]
368		}
369		```
370
371		#### Huge page limits
372
373		`hugepageLimits` represents the `hugetlb` controller which allows to limit the
374		HugeTLB usage per control group and enforces the controller limit during page fault.
375		For more information, see the [kernel cgroups documentation about HugeTLB][cgroup-v1-hugetlb].
376
377		`hugepageLimits` is an array of entries, each having the following structure:
378
379		* `pageSize` (string, required) - hugepage size
380
381		* `limit` (uint64, required) - limit in bytes of hugepagesize HugeTLB usage
382
383		###### Example
384
385		```json
386		"hugepageLimits": [
387		{
388		"pageSize": "2MB",
389		"limit": 9223372036854771712
390		}
391		]
392		```
393
394		#### Network
395
396		`network` represents the cgroup subsystems `net_cls` and `net_prio`.
397		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].
398
399		The following parameters can be specified to setup these cgroup controllers:
400
401		* `classID` (uint32, optional) - is the network class identifier the cgroup's network packets will be tagged with
402
403		* `priorities` (array, optional) - specifies a list of objects of the priorities assigned to traffic originating from
404		processes in the group and egressing the system on various interfaces. The following parameters can be specified per-priority:
405		* `name` (string, required) - interface name
406		* `priority` (uint32, required) - priority applied to the interface
407
408		###### Example
409
410		```json
411		"network": {
412		"classID": 1048577,
413		"priorities": [
414		{
415		"name": "eth0",
416		"priority": 500
417		},
418		{
419		"name": "eth1",
420		"priority": 1000
421		}
422		]
423		}
424		```
425
426		#### PIDs
427
428		`pids` represents the cgroup subsystem `pids`.
429		For more information, see [the pids cgroup man page][cgroup-v1-pids].
430
431		The following parameters can be specified to setup the controller:
432
433		* `limit` (int64, required) - specifies the maximum number of tasks in the cgroup
434
435		###### Example
436
437		```json
438		"pids": {
439		"limit": 32771
440		}
441		```
442
443		## Sysctl
444
445		`sysctl` allows kernel parameters to be modified at runtime for the container.
446		For more information, see [the man page](http://man7.org/linux/man-pages/man8/sysctl.8.html)
447
448		###### Example
449
450		```json
451		"sysctl": {
452		"net.ipv4.ip_forward": "1",
453		"net.core.somaxconn": "256"
454		}
455		```
456
457		## seccomp
458
459		Seccomp provides application sandboxing mechanism in the Linux kernel.
460		Seccomp configuration allows one to configure actions to take for matched syscalls and furthermore also allows matching on values passed as arguments to syscalls.
461		For more information about Seccomp, see [Seccomp kernel documentation](https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt)
462		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.
463		A valid list of constants as of Libseccomp v2.2.3 is contained below.
464
465		Architecture Constants
466		* `SCMP_ARCH_X86`
467		* `SCMP_ARCH_X86_64`
468		* `SCMP_ARCH_X32`
469		* `SCMP_ARCH_ARM`
470		* `SCMP_ARCH_AARCH64`
471		* `SCMP_ARCH_MIPS`
472		* `SCMP_ARCH_MIPS64`
473		* `SCMP_ARCH_MIPS64N32`
474		* `SCMP_ARCH_MIPSEL`
475		* `SCMP_ARCH_MIPSEL64`
476		* `SCMP_ARCH_MIPSEL64N32`
477
478		Action Constants:
479		* `SCMP_ACT_KILL`
480		* `SCMP_ACT_TRAP`
481		* `SCMP_ACT_ERRNO`
482		* `SCMP_ACT_TRACE`
483		* `SCMP_ACT_ALLOW`
484
485		Operator Constants:
486		* `SCMP_CMP_NE`
487		* `SCMP_CMP_LT`
488		* `SCMP_CMP_LE`
489		* `SCMP_CMP_EQ`
490		* `SCMP_CMP_GE`
491		* `SCMP_CMP_GT`
492		* `SCMP_CMP_MASKED_EQ`
493
494		###### Example
495
496		```json
497		"seccomp": {
498		"defaultAction": "SCMP_ACT_ALLOW",
499		"architectures": [
500		"SCMP_ARCH_X86"
501		],
502		"syscalls": [
503		{
504		"name": "getcwd",
505		"action": "SCMP_ACT_ERRNO"
506		}
507		]
508		}
509		```
510
511		## Rootfs Mount Propagation
512
513		`rootfsPropagation` sets the rootfs's mount propagation.
514		Its value is either slave, private, or shared.
515		[The kernel doc](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) has more information about mount propagation.
516
517		###### Example
518
519		```json
520		"rootfsPropagation": "slave",
521		```
522
523		## Masked Paths
524
525		`maskedPaths` will mask over the provided paths inside the container so that they cannot be read.
526
527		###### Example
528
529		```json
530		"maskedPaths": [
531		"/proc/kcore"
532		]
533		```
534
535		## Readonly Paths
536
537		`readonlyPaths` will set the provided paths as readonly inside the container.
538
539		###### Example
540
541		```json
542		"readonlyPaths": [
543		"/proc/sys"
544		]
545		```
546
547		[cgroup-v1]: https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt
548		[cgroup-v1-blkio]: https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt
549		[cgroup-v1-cpusets]: https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.txt
550		[cgroup-v1-devices]: https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt
551		[cgroup-v1-hugetlb]: https://www.kernel.org/doc/Documentation/cgroup-v1/hugetlb.txt
552		[cgroup-v1-memory]: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt
553		[cgroup-v1-net-cls]: https://www.kernel.org/doc/Documentation/cgroup-v1/net_cls.txt
554		[cgroup-v1-net-prio]: https://www.kernel.org/doc/Documentation/cgroup-v1/net_prio.txt
555		[cgroup-v1-pids]: https://www.kernel.org/doc/Documentation/cgroup-v1/pids.txt
556		[cgroup-v2]: https://www.kernel.org/doc/Documentation/cgroup-v2.txt
557		[devices]: https://www.kernel.org/doc/Documentation/devices.txt
558		[devpts]: https://www.kernel.org/doc/Documentation/filesystems/devpts.txt
559
560		[mknod.1]: http://man7.org/linux/man-pages/man1/mknod.1.html
561		[mknod.2]: http://man7.org/linux/man-pages/man2/mknod.2.html
562		[console.4]: http://man7.org/linux/man-pages/man4/console.4.html
563		[full.4]: http://man7.org/linux/man-pages/man4/full.4.html
564		[null.4]: http://man7.org/linux/man-pages/man4/null.4.html
565		[pts.4]: http://man7.org/linux/man-pages/man4/pts.4.html
566		[random.4]: http://man7.org/linux/man-pages/man4/random.4.html
567		[tty.4]: http://man7.org/linux/man-pages/man4/tty.4.html
568		[zero.4]: http://man7.org/linux/man-pages/man4/zero.4.html

-616

~~config.md~~ less more

0		# Container Configuration file
1
2		The container's top-level directory MUST contain a configuration file called `config.json`.
3		The canonical schema is defined in this document, but there is a JSON Schema in [`schema/schema.json`](schema/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 OpenContainer specification with which the bundle complies.
13		The OpenContainer spec follows semantic versioning and retains forward and backward compatibility within major versions.
14		For example, if an implementation is compliant with version 1.0.1 of the spec, it is compatible with the complete 1.x series.
15		NOTE that there is no guarantee for forward or backward compatibility for version 0.x.
16
17		Example
18
19		```json
20		"ociVersion": "0.1.0"
21		```
22
23		## Root Configuration
24
25		Each container has exactly one root filesystem, specified in the root object:
26
27		* `path` (string, required) Specifies the path to the root filesystem for the container, relative to the path where the manifest is. A directory MUST exist at the relative path declared by the field.
28		* `readonly` (bool, optional) If true then the root filesystem MUST be read-only inside the container. Defaults to false.
29
30		Example
31
32		```json
33		"root": {
34		"path": "rootfs",
35		"readonly": true
36		}
37		```
38
39		## Mounts
40
41		You can add array of mount points inside container as `mounts`.
42		The runtime MUST mount entries in the listed order.
43		The parameters are similar to the ones in [the Linux mount system call](http://man7.org/linux/man-pages/man2/mount.2.html).
44
45		* `destination` (string, required) Destination of mount point: path inside container.
46		* `type` (string, required) Linux, filesystemtype argument supported by the kernel are listed in /proc/filesystems (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660"). Windows: ntfs
47		* `source` (string, required) a device name, but can also be a directory name or a dummy. Windows, the volume name that is the target of the mount point. \\?\Volume\{GUID}\ (on Windows source is called target)
48		* `options` (list of strings, optional) in the fstab format [https://wiki.archlinux.org/index.php/Fstab](https://wiki.archlinux.org/index.php/Fstab).
49
50		### Linux Example
51
52		```json
53		"mounts": [
54		{
55		"destination": "/tmp",
56		"type": "tmpfs",
57		"source": "tmpfs",
58		"options": ["nosuid","strictatime","mode=755","size=65536k"]
59		},
60		{
61		"destination": "/data",
62		"type": "bind",
63		"source": "/volumes/testing",
64		"options": ["rbind","rw"]
65		}
66		]
67		```
68
69		### Windows Example
70
71		```json
72		"mounts": [
73		"myfancymountpoint": {
74		"destination": "C:\\Users\\crosbymichael\\My Fancy Mount Point\\",
75		"type": "ntfs",
76		"source": "\\\\?\\Volume\\{2eca078d-5cbc-43d3-aff8-7e8511f60d0e}\\",
77		"options": []
78		}
79		]
80		```
81
82		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.
83
84
85		## Process configuration
86
87		* `terminal` (bool, optional) specifies whether you want a terminal attached to that process. Defaults to false.
88		* `cwd` (string, required) is the working directory that will be set for the executable. This value MUST be an absolute path.
89		* `env` (array of strings, optional) contains a list of variables that will be set in the process's environment prior to execution. Elements in the array are specified as Strings in the form "KEY=value". The left hand side must consist solely of letters, digits, and underscores `_` as outlined in [IEEE Std 1003.1-2001](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html).
90		* `args` (string, required) executable to launch and any flags as an array. The executable is the first element and must be available at the given path inside of the rootfs. If the executable path is not an absolute path then the search $PATH is interpreted to find the executable.
91
92		For Linux-based systems the process structure supports the following process specific fields:
93
94		* `capabilities` (array of strings, optional) capabilities is an array that specifies Linux capabilities that can be provided to the process inside the container.
95		Valid values are the strings for capabilities defined in [the man page](http://man7.org/linux/man-pages/man7/capabilities.7.html)
96		* `rlimits` (array of rlimits, optional) rlimits is an array of rlimits that allows setting resource limits for a process inside the container.
97		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.
98		Valid values for the 'type' field are the resources defined in [the man page](http://man7.org/linux/man-pages/man2/setrlimit.2.html).
99		* `apparmorProfile` (string, optional) apparmor profile specifies the name of the apparmor profile that will be used for the container.
100		For more information about Apparmor, see [Apparmor documentation](https://wiki.ubuntu.com/AppArmor)
101		* `selinuxLabel` (string, optional) SELinux process label specifies the label with which the processes in a container are run.
102		For more information about SELinux, see [Selinux documentation](http://selinuxproject.org/page/Main_Page)
103		* `noNewPrivileges` (bool, optional) setting `noNewPrivileges` to true prevents the processes in the container from gaining additional privileges.
104		[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.
105
106		### User
107
108		The user for the process is a platform-specific structure that allows specific control over which user the process runs as.
109
110		#### Linux User
111
112		For Linux-based systems the user structure has the following fields:
113
114		* `uid` (int, required) specifies the user id.
115		* `gid` (int, required) specifies the group id.
116		* `additionalGids` (array of ints, optional) specifies additional group ids to be added to the process.
117
118		_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)_
119
120		Example (Linux)
121
122		```json
123		"process": {
124		"terminal": true,
125		"user": {
126		"uid": 1,
127		"gid": 1,
128		"additionalGids": [5, 6]
129		},
130		"env": [
131		"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
132		"TERM=xterm"
133		],
134		"cwd": "/root",
135		"args": [
136		"sh"
137		],
138		"apparmorProfile": "acme_secure_profile",
139		"selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675",
140		"noNewPrivileges": true,
141		"capabilities": [
142		"CAP_AUDIT_WRITE",
143		"CAP_KILL",
144		"CAP_NET_BIND_SERVICE"
145		],
146		"rlimits": [
147		{
148		"type": "RLIMIT_NOFILE",
149		"hard": 1024,
150		"soft": 1024
151		}
152		]
153		}
154		```
155
156
157		## Hostname
158
159		* `hostname` (string, optional) as it is accessible to processes running inside. On Linux, you can only set this if your bundle creates a new [UTS namespace][uts-namespace].
160
161		Example
162
163		```json
164		"hostname": "mrsdalloway"
165		```
166
167		## Platform-specific configuration
168
169		* `os` (string, required) specifies the operating system family this image must run on. Values for os must be in the list specified by the Go Language document for [`$GOOS`](https://golang.org/doc/install/source#environment).
170		* `arch` (string, required) specifies the instruction set for which the binaries in the image have been compiled. Values for arch must be in the list specified by the Go Language document for [`$GOARCH`](https://golang.org/doc/install/source#environment).
171
172		```json
173		"platform": {
174		"os": "linux",
175		"arch": "amd64"
176		}
177		```
178
179		Interpretation of the platform section of the JSON file is used to find which platform-specific sections may be available in the document.
180		For example, if `os` is set to `linux`, then a JSON object conforming to the [Linux-specific schema](config-linux.md) SHOULD be found at the key `linux` in the `config.json`.
181
182		## Hooks
183
184		Lifecycle hooks allow custom events for different points in a container's runtime.
185		Presently there are `Prestart`, `Poststart` and `Poststop`.
186
187		* [`Prestart`](#prestart) is a list of hooks to be run before the container process is executed
188		* [`Poststart`](#poststart) is a list of hooks to be run immediately after the container process is started
189		* [`Poststop`](#poststop) is a list of hooks to be run after the container process exits
190
191		Hooks allow one to run code before/after various lifecycle events of the container.
192		Hooks MUST be called in the listed order.
193		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.
194
195		Hook paths are absolute and are executed from the host's filesystem.
196
197		### Prestart
198
199		The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed.
200		They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container.
201		In Linux, for e.g., the network namespace could be configured in this hook.
202
203		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.
204
205		### Poststart
206
207		The post-start hooks are called after the user process is started.
208		For example this hook can notify user that real process is spawned.
209
210		If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
211
212		### Poststop
213
214		The post-stop hooks are called after the container process is stopped.
215		Cleanup or debugging could be performed in such a hook.
216		If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.
217
218		Example
219
220		```json
221		"hooks" : {
222		"prestart": [
223		{
224		"path": "/usr/bin/fix-mounts",
225		"args": ["fix-mounts", "arg1", "arg2"],
226		"env": [ "key1=value1"]
227		},
228		{
229		"path": "/usr/bin/setup-network"
230		}
231		],
232		"poststart": [
233		{
234		"path": "/usr/bin/notify-start",
235		"timeout": 5
236		}
237		],
238		"poststop": [
239		{
240		"path": "/usr/sbin/cleanup.sh",
241		"args": ["cleanup.sh", "-f"]
242		}
243		]
244		}
245		```
246
247		`path` is required for a hook.
248		`args` and `env` are optional.
249		`timeout` is the number of seconds before aborting the hook.
250		The semantics are the same as `Path`, `Args` and `Env` in [golang Cmd](https://golang.org/pkg/os/exec/#Cmd).
251
252		## Annotations
253
254		Annotations are optional arbitrary non-identifying metadata that can be attached to containers.
255		This information may be large, may be structured or unstructured.
256		Annotations are key-value maps.
257
258		```json
259		"annotations": {
260		"key1" : "value1",
261		"key2" : "value2"
262		}
263		```
264
265		## Configuration Schema Example
266
267		Here is a full example `config.json` for reference.
268
269		```json
270		{
271		"ociVersion": "0.5.0-dev",
272		"platform": {
273		"os": "linux",
274		"arch": "amd64"
275		},
276		"process": {
277		"terminal": true,
278		"user": {
279		"uid": 1,
280		"gid": 1,
281		"additionalGids": [
282		5,
283		6
284		]
285		},
286		"uidMappings": [
287		{
288		"hostID": 1000,
289		"containerID": 0,
290		"size": 32000
291		}
292		],
293		"gidMappings": [
294		{
295		"hostID": 1000,
296		"containerID": 0,
297		"size": 32000
298		}
299		],
300		"args": [
301		"sh"
302		],
303		"env": [
304		"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
305		"TERM=xterm"
306		],
307		"cwd": "/",
308		"capabilities": [
309		"CAP_AUDIT_WRITE",
310		"CAP_KILL",
311		"CAP_NET_BIND_SERVICE"
312		],
313		"rlimits": [
314		{
315		"type": "RLIMIT_CORE",
316		"hard": 1024,
317		"soft": 1024
318		},
319		{
320		"type": "RLIMIT_NOFILE",
321		"hard": 1024,
322		"soft": 1024
323		}
324		],
325		"apparmorProfile": "acme_secure_profile",
326		"selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675",
327		"noNewPrivileges": true
328		},
329		"root": {
330		"path": "rootfs",
331		"readonly": true
332		},
333		"hostname": "slartibartfast",
334		"mounts": [
335		{
336		"destination": "/proc",
337		"type": "proc",
338		"source": "proc"
339		},
340		{
341		"destination": "/dev",
342		"type": "tmpfs",
343		"source": "tmpfs",
344		"options": [
345		"nosuid",
346		"strictatime",
347		"mode=755",
348		"size=65536k"
349		]
350		},
351		{
352		"destination": "/dev/pts",
353		"type": "devpts",
354		"source": "devpts",
355		"options": [
356		"nosuid",
357		"noexec",
358		"newinstance",
359		"ptmxmode=0666",
360		"mode=0620",
361		"gid=5"
362		]
363		},
364		{
365		"destination": "/dev/shm",
366		"type": "tmpfs",
367		"source": "shm",
368		"options": [
369		"nosuid",
370		"noexec",
371		"nodev",
372		"mode=1777",
373		"size=65536k"
374		]
375		},
376		{
377		"destination": "/dev/mqueue",
378		"type": "mqueue",
379		"source": "mqueue",
380		"options": [
381		"nosuid",
382		"noexec",
383		"nodev"
384		]
385		},
386		{
387		"destination": "/sys",
388		"type": "sysfs",
389		"source": "sysfs",
390		"options": [
391		"nosuid",
392		"noexec",
393		"nodev"
394		]
395		},
396		{
397		"destination": "/sys/fs/cgroup",
398		"type": "cgroup",
399		"source": "cgroup",
400		"options": [
401		"nosuid",
402		"noexec",
403		"nodev",
404		"relatime",
405		"ro"
406		]
407		}
408		],
409		"hooks": {
410		"prestart": [
411		{
412		"path": "/usr/bin/fix-mounts",
413		"args": [
414		"fix-mounts",
415		"arg1",
416		"arg2"
417		],
418		"env": [
419		"key1=value1"
420		]
421		},
422		{
423		"path": "/usr/bin/setup-network"
424		}
425		],
426		"poststart": [
427		{
428		"path": "/usr/bin/notify-start",
429		"timeout": 5
430		}
431		],
432		"poststop": [
433		{
434		"path": "/usr/sbin/cleanup.sh",
435		"args": [
436		"cleanup.sh",
437		"-f"
438		]
439		}
440		]
441		},
442		"linux": {
443		"devices": [
444		{
445		"path": "/dev/fuse",
446		"type": "c",
447		"major": 10,
448		"minor": 229,
449		"fileMode": 438,
450		"uid": 0,
451		"gid": 0
452		},
453		{
454		"path": "/dev/sda",
455		"type": "b",
456		"major": 8,
457		"minor": 0,
458		"fileMode": 432,
459		"uid": 0,
460		"gid": 0
461		}
462		],
463		"sysctl": {
464		"net.ipv4.ip_forward": "1",
465		"net.core.somaxconn": "256"
466		},
467		"cgroupsPath": "/myRuntime/myContainer",
468		"resources": {
469		"network": {
470		"classID": 1048577,
471		"priorities": [
472		{
473		"name": "eth0",
474		"priority": 500
475		},
476		{
477		"name": "eth1",
478		"priority": 1000
479		}
480		]
481		},
482		"pids": {
483		"limit": 32771
484		},
485		"hugepageLimits": [
486		{
487		"pageSize": "2MB",
488		"limit": 9223372036854772000
489		}
490		],
491		"oomScoreAdj": 100,
492		"memory": {
493		"limit": 536870912,
494		"reservation": 536870912,
495		"swap": 536870912,
496		"kernel": 0,
497		"kernelTCP": 0,
498		"swappiness": 0
499		},
500		"cpu": {
501		"shares": 1024,
502		"quota": 1000000,
503		"period": 500000,
504		"realtimeRuntime": 950000,
505		"realtimePeriod": 1000000,
506		"cpus": "2-3",
507		"mems": "0-7"
508		},
509		"disableOOMKiller": false,
510		"devices": [
511		{
512		"allow": false,
513		"access": "rwm"
514		},
515		{
516		"allow": true,
517		"type": "c",
518		"major": 10,
519		"minor": 229,
520		"access": "rw"
521		},
522		{
523		"allow": true,
524		"type": "b",
525		"major": 8,
526		"minor": 0,
527		"access": "r"
528		}
529		],
530		"blockIO": {
531		"blkioWeight": 10,
532		"blkioLeafWeight": 10,
533		"blkioWeightDevice": [
534		{
535		"major": 8,
536		"minor": 0,
537		"weight": 500,
538		"leafWeight": 300
539		},
540		{
541		"major": 8,
542		"minor": 16,
543		"weight": 500
544		}
545		],
546		"blkioThrottleReadBpsDevice": [
547		{
548		"major": 8,
549		"minor": 0,
550		"rate": 600
551		}
552		],
553		"blkioThrottleWriteIOPSDevice": [
554		{
555		"major": 8,
556		"minor": 16,
557		"rate": 300
558		}
559		]
560		}
561		},
562		"rootfsPropagation": "slave",
563		"seccomp": {
564		"defaultAction": "SCMP_ACT_ALLOW",
565		"architectures": [
566		"SCMP_ARCH_X86"
567		],
568		"syscalls": [
569		{
570		"name": "getcwd",
571		"action": "SCMP_ACT_ERRNO"
572		}
573		]
574		},
575		"namespaces": [
576		{
577		"type": "pid"
578		},
579		{
580		"type": "network"
581		},
582		{
583		"type": "ipc"
584		},
585		{
586		"type": "uts"
587		},
588		{
589		"type": "mount"
590		}
591		],
592		"maskedPaths": [
593		"/proc/kcore",
594		"/proc/latency_stats",
595		"/proc/timer_stats",
596		"/proc/sched_debug"
597		],
598		"readonlyPaths": [
599		"/proc/asound",
600		"/proc/bus",
601		"/proc/fs",
602		"/proc/irq",
603		"/proc/sys",
604		"/proc/sysrq-trigger"
605		]
606		},
607		"annotations": {
608		"key1": "value1",
609		"key2": "value2"
610		}
611		}
612		```
613
614
615		[uts-namespace]: http://man7.org/linux/man-pages/man7/namespaces.7.html

+10

-1

debian/gbp.conf less more

0		[DEFAULT]
	0	[buildpackage]
	1	force-create = True
	2	overlay = True
	3	export-dir = ../build-area/
	4
	5	[dch]
	6	id-length = 0
	7
	8	[import-orig]
1	9	pristine-tar = True
	10	merge = False

-36

~~glossary.md~~ less more

0		# Glossary
1
2		## Bundle
3
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
6		## Configuration
7
8		The [`config.json`](config.md) file in a [bundle](#bundle) which defines the intended [container](#container) and container process.
9
10		## Container
11
12		An environment for executing processes with configurable isolation and resource limitations.
13		For example, namespaces, resource limits, and mounts are all part of the container environment.
14
15		## Container namespace
16
17		On Linux, a leaf in the [namespace][namespaces.7] hierarchy in which the [configured process](config.md#process-configuration) executes.
18
19		## JSON
20
21		All configuration [JSON][] MUST be encoded in [UTF-8][].
22
23		## Runtime
24
25		An implementation of this specification.
26		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
28		## Runtime namespace
29
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
33		[JSON]: http://json.org/
34		[UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf
35		[namespaces.7]: http://man7.org/linux/man-pages/man7/namespaces.7.html

-18

~~implementations.md~~ less more

0		# Implementations
1
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		If you know of any associated projects that are not listed here, please file a pull request adding a link to that project.
4
5		## Runtime (Container)
6
7		* [opencontainers/runc](https://github.com/opencontainers/runc) - Reference implementation of OCI runtime
8
9		## Runtime (Virtual Machine)
10
11		* [hyperhq/runv](https://github.com/hyperhq/runv) - Hypervisor-based runtime for OCI
12
13		## Testing & Tools
14
15		* [kunalkushwaha/octool](https://github.com/kunalkushwaha/octool) - A config linter and validator.
16		* [opencontainers/ocitools](https://github.com/opencontainers/ocitools) - A config generator and runtime/bundle testing framework.
17		* [huawei-openlab/oct](https://github.com/huawei-openlab/oct) - Open Container Testing framework for OCI configuration and runtime

-46

~~principles.md~~ less more

0		# The 5 principles of Standard Containers
1
2		Define a unit of software delivery called a Standard Container.
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.
4
5		The specification for Standard Containers defines:
6
7		1. configuration file formats
8		2. a set of standard operations
9		3. an execution environment.
10
11		A great analogy for this is the physical shipping container used by the transportation industry.
12		Shipping containers are a fundamental unit of delivery, they can be lifted, stacked, locked, loaded, unloaded and labelled.
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		For software Standard Containers offer similar functionality by being the fundamental, standardized, unit of delivery for a software package.
15
16		## 1. Standard operations
17
18		Standard Containers define a set of STANDARD OPERATIONS.
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
21		## 2. Content-agnostic
22
23		Standard Containers are CONTENT-AGNOSTIC: all standard operations have the same effect regardless of the contents.
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
26		## 3. Infrastructure-agnostic
27
28		Standard Containers are INFRASTRUCTURE-AGNOSTIC: they can be run in any OCI supported infrastructure.
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
31		## 4. Designed for automation
32
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		In fact, you could say automation is their secret weapon.
35
36		Many things that once required time-consuming and error-prone human effort can now be programmed.
37		Before Standard Containers, by the time a software component ran in production, it had been individually built, configured, bundled, documented, patched, vendored, templated, tweaked and instrumented by 10 different people on 10 different computers.
38		Builds failed, libraries conflicted, mirrors crashed, post-it notes were lost, logs were misplaced, cluster updates were half-broken.
39		The process was slow, inefficient and cost a fortune - and was entirely different depending on the language and infrastructure provider.
40
41		## 5. Industrial-grade delivery
42
43		Standard Containers make INDUSTRIAL-GRADE DELIVERY of software a reality.
44		Leveraging all of the properties listed above, Standard Containers are enabling large and small enterprises to streamline and automate their software delivery pipelines.
45		Whether it is in-house devOps flows, or external customer-based software delivery mechanisms, Standard Containers are changing the way the community thinks about software packaging and delivery.

-10

~~project.md~~ less more

0		# Project docs
1
2		## Release Process
3
4		* Increment version in [`specs-go/version.go`](specs-go/version.go)
5		* `git commit` version increment
6		* `git tag` the prior commit (preferably signed tag)
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.
9

-8

~~runtime-linux.md~~ less more

0		# Linux Runtime
1
2		## File descriptors
3		By default, only the `stdin`, `stdout` and `stderr` file descriptors are kept open for the application by the runtime.
4
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).
6
7		Some of the file descriptors may be redirected to `/dev/null` even though they are open.

-129

~~runtime.md~~ less more

0		# Runtime and Lifecycle
1
2		## Scope of a Container
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.
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
7		## State
8
9		The state of a container MUST include, at least, the following propeties:
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		The ID is provided in the state because hooks will be executed with the state as the payload.
16		This allows the hooks to perform cleanup and teardown logic after the runtime destroys its own state.
17		* `pid`: (int) is the ID of the main process within the container, as seen by the host.
18		* `bundlePath`: (string) is the absolute path to the container's bundle directory.
19		This is provided so that consumers can find the container's configuration and root filesystem on the host.
20
21		When serialized in JSON, the format MUST adhere to the following pattern:
22		```json
23		{
24		"ociVersion": "0.2.0",
25		"id": "oci-container1",
26		"pid": 4422,
27		"bundlePath": "/containers/redis"
28		}
29		```
30
31		See [Query State](#query-state) for information on retrieving the state of a container.
32
33		## Lifecycle
34		The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist.
35
36		1. OCI compliant runtime is invoked with a reference to the location of the bundle.
37		How this reference is passed to the runtime is an implementation detail.
38		2. The container's runtime environment MUST be created according to the configuration in [`config.json`](config.md).
39		Any updates to `config.json` after container is running MUST not affect the container.
40		3. The prestart hooks MUST be invoked by the runtime.
41		If any prestart hook fails, then the container MUST be stopped and the lifecycle continues at step 8.
42		4. The user specified process MUST be executed in the container.
43		5. The poststart hooks MUST be invoked by the runtime.
44		If any poststart hook fails, then the container MUST be stopped and the lifecycle continues at step 8.
45		6. Additional actions such as pausing the container, resuming the container or signaling the container MAY be performed using the runtime interface.
46		The container MAY also error out, exit or crash.
47		7. The container MUST be destroyed by undoing the steps performed during create phase (step 2).
48		8. The poststop hooks MUST be invoked by the runtime and errors, if any, MAY be logged.
49
50		Note: The lifecycle is a WIP and it will evolve as we have more use cases and more information on the viability of a separate create phase.
51
52		## Operations
53
54		OCI compliant runtimes MUST support the following operations, unless the operation is not supported by the base operating system.
55
56		### Errors
57		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.
58		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.
59
60		### Query State
61
62		`state <container-id>`
63
64		This operation MUST generate an error if it is not provided the ID of a container.
65		This operation MUST return the state of a container as specified in the [State](#state) section.
66		In particular, the state MUST be serialized as JSON.
67
68
69		### Start
70
71		`start <container-id> <path-to-bundle>`
72
73		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.
74		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.
75		Using the data in `config.json`, that are in the bundle's directory, this operation MUST create a new container.
76		This includes creating the relevant namespaces, resource limits, etc and configuring the appropriate capabilities for the container.
77		A new process within the scope of the container MUST be created as specified by the `config.json` file otherwise an error MUST be generated.
78
79		Attempting to start an already running container MUST have no effect on the container and MUST generate an error.
80
81		### Stop
82
83		`stop <container-id>`
84
85		This operation MUST generate an error if it is not provided the container ID.
86		This operation MUST stop and delete a running container.
87		Stopping a container MUST stop all of the processes running within the scope of the container.
88		Deleting a container MUST delete the associated namespaces and resources associated with the container.
89		Once a container is deleted, its `id` MAY be used by subsequent containers.
90		Attempting to stop a container that is not running MUST have no effect on the container and MUST generate an error.
91
92		### Exec
93
94		`exec <container-id> <path-to-json>`
95
96		This operation MUST generate an error if it is not provided the container ID and a path to the JSON describing the process to start.
97		The JSON describing the new process MUST adhere to the [Process configuration](config.md#process-configuration) definition.
98		This operation MUST create a new process within the scope of the container.
99		If the container is not running then this operation MUST have no effect on the container and MUST generate an error.
100		Executing this operation multiple times MUST result in a new process each time.
101		Example:
102		```
103		{
104		"terminal": true,
105		"user": {
106		"uid": 0,
107		"gid": 0,
108		"additionalGids": null
109		},
110		"args": [
111		"/bin/sleep",
112		"60"
113		],
114		"env": [
115		"version=1.0"
116		],
117		"cwd": "...",
118		}
119		```
120		This specification does not mandate the name of this JSON file.
121		See the specification of the `config.json` file for the definition of these fields.
122		The stopping, or exiting, of these secondary process MUST have no effect on the state of the container.
123		In other words, a container (and its PID 1 process) MUST NOT be stopped due to the exiting of a secondary process.
124
125		## Hooks
126
127		Many of the operations specified in this specification have "hooks" that allow for additional actions to be taken before or after each operation.
128		See [runtime configuration for hooks](./config.md#hooks) for more information.

-15

~~schema/Makefile~~ less more

0
1		default: help
2
3		help:
4		@echo "Usage: make <target>"
5		@echo
6		@echo " * 'fmt' - format the json with indentation"
7		@echo " * 'validate' - build the validation tool"
8
9		fmt:
10		for i in *.json ; do jq --indent 4 -M . "$${i}" > xx && cat xx > "$${i}" && rm xx ; done
11
12		validate: validate.go
13		go build ./validate.go
14

-241

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

0		{
1		"definitions": {
2		"SeccompArch": {
3		"type": "string",
4		"enum": [
5		"SCMP_ARCH_X86",
6		"SCMP_ARCH_X86_64",
7		"SCMP_ARCH_X32",
8		"SCMP_ARCH_ARM",
9		"SCMP_ARCH_AARCH64",
10		"SCMP_ARCH_MIPS",
11		"SCMP_ARCH_MIPS64",
12		"SCMP_ARCH_MIPS64N32",
13		"SCMP_ARCH_MIPSEL",
14		"SCMP_ARCH_MIPSEL64",
15		"SCMP_ARCH_MIPSEL64N32"
16		]
17		},
18		"SeccompAction": {
19		"type": "string",
20		"enum": [
21		"SCMP_ACT_KILL",
22		"SCMP_ACT_TRAP",
23		"SCMP_ACT_ERRNO",
24		"SCMP_ACT_TRACE",
25		"SCMP_ACT_ALLOW"
26		]
27		},
28		"SeccompOperators": {
29		"type": "string",
30		"enum": [
31		"SCMP_CMP_NE",
32		"SCMP_CMP_LT",
33		"SCMP_CMP_LE",
34		"SCMP_CMP_EQ",
35		"SCMP_CMP_GE",
36		"SCMP_CMP_GT",
37		"SCMP_CMP_MASKED_EQ"
38		]
39		},
40		"SyscallArg": {
41		"properties": {
42		"index": {
43		"$ref": "defs.json#/definitions/uint32"
44		},
45		"value": {
46		"$ref": "defs.json#/definitions/uint64"
47		},
48		"valueTwo": {
49		"$ref": "defs.json#/definitions/uint64"
50		},
51		"op": {
52		"$ref": "#/definitions/SeccompOperators"
53		}
54		}
55		},
56		"Syscall": {
57		"properties": {
58		"name": {
59		"type": "string"
60		},
61		"action": {
62		"$ref": "#/definitions/SeccompAction"
63		},
64		"args": {
65		"type": "array",
66		"items": {
67		"$ref": "#/definitions/SyscallArg"
68		}
69		}
70		}
71		},
72		"Capability": {
73		"description": "Linux process permissions",
74		"type": "string",
75		"pattern": "^CAP_([A-Z]\|_)+$"
76		},
77		"Major": {
78		"description": "major device number",
79		"$ref": "defs.json#/definitions/uint16"
80		},
81		"Minor": {
82		"description": "minor device number",
83		"$ref": "defs.json#/definitions/uint16"
84		},
85		"FileMode": {
86		"description": "File permissions mode (typically an octal value)",
87		"type": "integer",
88		"minimum": 0,
89		"maximum": 512
90		},
91		"FilePermissions": {
92		"type": "string"
93		},
94		"FileType": {
95		"description": "Type of a block or special character device",
96		"type": "string",
97		"pattern": "^[cbup]$"
98		},
99		"Device": {
100		"properties": {
101		"type": {
102		"$ref": "#/definitions/FileType"
103		},
104		"permissions": {
105		"$ref": "#/definitions/FilePermissions"
106		},
107		"path": {
108		"$ref": "defs.json#/definitions/FilePath"
109		},
110		"fileMode": {
111		"$ref": "#/definitions/FileMode"
112		},
113		"major": {
114		"$ref": "#/definitions/Major"
115		},
116		"minor": {
117		"$ref": "#/definitions/Minor"
118		},
119		"uid": {
120		"$ref": "defs.json#/definitions/UID"
121		},
122		"gid": {
123		"$ref": "defs.json#/definitions/GID"
124		}
125		}
126		},
127		"blkioWeight": {
128		"type": "integer",
129		"minimum": 10,
130		"maximum": 1000
131		},
132		"blkioWeightPointer": {
133		"oneOf": [
134		{
135		"$ref": "#/definitions/blkioWeight"
136		},
137		{
138		"type": "null"
139		}
140		]
141		},
142		"blockIODevice": {
143		"properties": {
144		"major": {
145		"$ref": "#/definitions/Major"
146		},
147		"minor": {
148		"$ref": "#/definitions/Minor"
149		}
150		},
151		"required": [
152		"major",
153		"minor"
154		]
155		},
156		"blockIODeviceWeight": {
157		"type": "object",
158		"allOf": [
159		{
160		"$ref": "#/definitions/blockIODevice"
161		},
162		{
163		"properties": {
164		"weight": {
165		"$ref": "#/definitions/blkioWeightPointer"
166		},
167		"leafWeight": {
168		"$ref": "#/definitions/blkioWeightPointer"
169		}
170		}
171		}
172		]
173		},
174		"blockIODeviceWeightPointer": {
175		"oneOf": [
176		{
177		"$ref": "#/definitions/blockIODeviceWeight"
178		},
179		{
180		"type": "null"
181		}
182		]
183		},
184		"blockIODeviceThrottle": {
185		"allOf": [
186		{
187		"$ref": "#/definitions/blockIODevice"
188		},
189		{
190		"properties": {
191		"rate": {
192		"$ref": "defs.json#/definitions/uint64Pointer"
193		}
194		}
195		}
196		]
197		},
198		"blockIODeviceThrottlePointer": {
199		"oneOf": [
200		{
201		"$ref": "#/definitions/blockIODeviceThrottle"
202		},
203		{
204		"type": "null"
205		}
206		]
207		},
208		"NetworkInterfacePriority": {
209		"properties": {
210		"name": {
211		"type": "string"
212		},
213		"priority": {
214		"$ref": "defs.json#/definitions/uint32"
215		}
216		}
217		},
218		"NamespaceType": {
219		"type": "string",
220		"enum": [
221		"mount",
222		"pid",
223		"network",
224		"uts",
225		"ipc",
226		"user"
227		]
228		},
229		"NamespaceReference": {
230		"properties": {
231		"type": {
232		"$ref": "#/definitions/NamespaceType"
233		},
234		"path": {
235		"$ref": "defs.json#/definitions/FilePath"
236		}
237		}
238		}
239		}
240		}

-160

~~schema/defs.json~~ less more

0		{
1		"description": "Definitions used throughout the OpenContainer Specification",
2		"definitions": {
3		"int8": {
4		"type": "integer",
5		"minimum": -128,
6		"maximum": 127
7		},
8		"int16": {
9		"type": "integer",
10		"minimum": -32768,
11		"maximum": 32767
12		},
13		"int32": {
14		"type": "integer",
15		"minimum": -2147483648,
16		"maximum": 2147483647
17		},
18		"int64": {
19		"type": "integer",
20		"minimum": -9223372036854776000,
21		"maximum": 9223372036854776000
22		},
23		"uint8": {
24		"type": "integer",
25		"minimum": 0,
26		"maximum": 255
27		},
28		"uint16": {
29		"type": "integer",
30		"minimum": 0,
31		"maximum": 65535
32		},
33		"uint32": {
34		"type": "integer",
35		"minimum": 0,
36		"maximum": 4294967295
37		},
38		"uint64": {
39		"type": "integer",
40		"minimum": 0,
41		"maximum": 18446744073709552000
42		},
43		"uint16Pointer": {
44		"oneOf": [
45		{
46		"$ref": "#/definitions/uint16"
47		},
48		{
49		"type": "null"
50		}
51		]
52		},
53		"uint64Pointer": {
54		"oneOf": [
55		{
56		"$ref": "#/definitions/uint64"
57		},
58		{
59		"type": "null"
60		}
61		]
62		},
63		"stringPointer": {
64		"oneOf": [
65		{
66		"type": "string"
67		},
68		{
69		"type": "null"
70		}
71		]
72		},
73		"mapStringString": {
74		"type": "object",
75		"patternProperties": {
76		".{1,}": {
77		"type": "string"
78		}
79		}
80		},
81		"UID": {
82		"$ref": "#/definitions/uint32"
83		},
84		"GID": {
85		"$ref": "#/definitions/uint32"
86		},
87		"ArrayOfGIDs": {
88		"type": "array",
89		"items": {
90		"$ref": "#/definitions/GID"
91		}
92		},
93		"ArrayOfStrings": {
94		"type": "array",
95		"items": {
96		"type": "string"
97		}
98		},
99		"FilePath": {
100		"type": "string"
101		},
102		"Env": {
103		"$ref": "#/definitions/ArrayOfStrings"
104		},
105		"Hook": {
106		"properties": {
107		"path": {
108		"$ref": "#/definitions/FilePath"
109		},
110		"args": {
111		"$ref": "#/definitions/ArrayOfStrings"
112		},
113		"env": {
114		"$ref": "#/definitions/Env"
115		}
116		}
117		},
118		"ArrayOfHooks": {
119		"type": "array",
120		"items": {
121		"$ref": "#/definitions/Hook"
122		}
123		},
124		"IDMapping": {
125		"properties": {
126		"hostID": {
127		"$ref": "#/definitions/uint32"
128		},
129		"containerID": {
130		"$ref": "#/definitions/uint32"
131		},
132		"size": {
133		"$ref": "#/definitions/uint32"
134		}
135		}
136		},
137		"Mount": {
138		"properties": {
139		"source": {
140		"$ref": "#/definitions/FilePath"
141		},
142		"destination": {
143		"$ref": "#/definitions/FilePath"
144		},
145		"options": {
146		"$ref": "#/definitions/ArrayOfStrings"
147		},
148		"type": {
149		"type": "string"
150		}
151		},
152		"required": [
153		"destination",
154		"source",
155		"type"
156		]
157		}
158		}
159		}

-336

~~schema/schema-linux.json~~ less more

0		{
1		"linux": {
2		"description": "Linux platform-specific configurations",
3		"id": "https://opencontainers.org/schema/bundle/linux",
4		"type": "object",
5		"properties": {
6		"devices": {
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		]
19		},
20		"uidMappings": {
21		"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		]
33		},
34		"gidMappings": {
35		"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		]
47		},
48		"namespaces": {
49		"id": "https://opencontainers.org/schema/bundle/linux/namespaces",
50		"type": "array",
51		"items": {
52		"anyOf": [
53		{
54		"$ref": "defs-linux.json#/definitions/NamespaceReference"
55		}
56		]
57		}
58		},
59		"resources": {
60		"id": "https://opencontainers.org/schema/bundle/linux/resources",
61		"type": "object",
62		"properties": {
63		"oomScoreAdj": {
64		"id": "https://opencontainers.org/schema/bundle/linux/resources/oomScoreAdj",
65		"type": "integer",
66		"minimum": -1000,
67		"maximum": 1000
68		},
69		"pids": {
70		"id": "https://opencontainers.org/schema/bundle/linux/resources/pids",
71		"properties": {
72		"limit": {
73		"id": "https://opencontainers.org/schema/bundle/linux/resources/pids/limit",
74		"$ref": "defs.json#/definitions/int64"
75		}
76		}
77		},
78		"blockIO": {
79		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO",
80		"type": "object",
81		"properties": {
82		"blkioWeight": {
83		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioWeight",
84		"$ref": "defs-linux.json#/definitions/blkioWeightPointer"
85		},
86		"blkioLeafWeight": {
87		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioLeafWeight",
88		"$ref": "defs-linux.json#/definitions/blkioWeightPointer"
89		},
90		"blkioThrottleReadBpsDevice": {
91		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioThrottleReadBpsDevice",
92		"oneOf": [
93		{
94		"type": "array",
95		"items": [
96		{
97		"$ref": "defs-linux.json#/definitions/blockIODeviceThrottlePointer"
98		}
99		]
100		},
101		{
102		"type": "null"
103		}
104		]
105		},
106		"blkioThrottleWriteBpsDevice": {
107		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioThrottleWriteBpsDevice",
108		"oneOf": [
109		{
110		"type": "array",
111		"items": {
112		"$ref": "defs-linux.json#/definitions/blockIODeviceThrottlePointer"
113		}
114		},
115		{
116		"type": "null"
117		}
118		]
119		},
120		"blkioThrottleReadIopsDevice": {
121		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioThrottleReadIopsDevice",
122		"oneOf": [
123		{
124		"type": "array",
125		"items": {
126		"$ref": "defs-linux.json#/definitions/blockIODeviceThrottlePointer"
127		}
128		},
129		{
130		"type": "null"
131		}
132		]
133		},
134		"blkioThrottleWriteIopsDevice": {
135		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioThrottleWriteIopsDevice",
136		"oneOf": [
137		{
138		"type": "array",
139		"items": {
140		"$ref": "defs-linux.json#/definitions/blockIODeviceThrottlePointer"
141		}
142		},
143		{
144		"type": "null"
145		}
146		]
147		},
148		"blkioWeightDevice": {
149		"id": "https://opencontainers.org/schema/bundle/linux/resources/blockIO/blkioWeightDevice",
150		"type": "array",
151		"items": {
152		"$ref": "defs-linux.json#/definitions/blockIODeviceWeightPointer"
153		}
154		}
155		}
156		},
157		"cpu": {
158		"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu",
159		"properties": {
160		"cpus": {
161		"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/cpus",
162		"$ref": "defs.json#/definitions/stringPointer"
163		},
164		"mems": {
165		"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/mems",
166		"$ref": "defs.json#/definitions/stringPointer"
167		},
168		"period": {
169		"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/period",
170		"$ref": "defs.json#/definitions/uint64Pointer"
171		},
172		"quota": {
173		"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/quota",
174		"$ref": "defs.json#/definitions/uint64Pointer"
175		},
176		"realtimePeriod": {
177		"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/realtimePeriod",
178		"$ref": "defs.json#/definitions/uint64Pointer"
179		},
180		"realtimeRuntime": {
181		"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/realtimeRuntime",
182		"$ref": "defs.json#/definitions/uint64Pointer"
183		},
184		"shares": {
185		"id": "https://opencontainers.org/schema/bundle/linux/resources/cpu/shares",
186		"$ref": "defs.json#/definitions/uint64Pointer"
187		}
188		},
189		"type": "object"
190		},
191		"disableOOMKiller": {
192		"id": "https://opencontainers.org/schema/bundle/linux/resources/disableOOMKiller",
193		"type": "boolean"
194		},
195		"hugepageLimits": {
196		"id": "https://opencontainers.org/schema/bundle/linux/resources/hugepageLimits",
197		"oneOf": [
198		{
199		"type": "array",
200		"items": {
201		"type": "object",
202		"properties": {
203		"pageSize": {
204		"type": "string"
205		},
206		"limit": {
207		"$ref": "defs.json#/definitions/uint64"
208		}
209		}
210		}
211		},
212		{
213		"type": "null"
214		}
215		]
216		},
217		"memory": {
218		"id": "https://opencontainers.org/schema/bundle/linux/resources/memory",
219		"type": "object",
220		"properties": {
221		"kernel": {
222		"id": "https://opencontainers.org/schema/bundle/linux/resources/memory/kernel",
223		"$ref": "defs.json#/definitions/uint64Pointer"
224		},
225		"limit": {
226		"id": "https://opencontainers.org/schema/bundle/linux/resources/memory/limit",
227		"$ref": "defs.json#/definitions/uint64Pointer"
228		},
229		"reservation": {
230		"id": "https://opencontainers.org/schema/bundle/linux/resources/memory/reservation",
231		"$ref": "defs.json#/definitions/uint64Pointer"
232		},
233		"swap": {
234		"id": "https://opencontainers.org/schema/bundle/linux/resources/memory/swap",
235		"$ref": "defs.json#/definitions/uint64Pointer"
236		},
237		"swappiness": {
238		"id": "https://opencontainers.org/schema/bundle/linux/resources/memory/swappiness",
239		"$ref": "defs.json#/definitions/uint64Pointer"
240		}
241		}
242		},
243		"network": {
244		"id": "https://opencontainers.org/schema/bundle/linux/resources/network",
245		"type": "object",
246		"properties": {
247		"classID": {
248		"id": "https://opencontainers.org/schema/bundle/linux/resources/network/classId",
249		"$ref": "defs.json#/definitions/uint32"
250		},
251		"priorities": {
252		"id": "https://opencontainers.org/schema/bundle/linux/resources/network/priorities",
253		"oneOf": [
254		{
255		"type": "array",
256		"items": {
257		"$ref": "defs-linux.json#/definitions/NetworkInterfacePriority"
258		}
259		},
260		{
261		"type": "null"
262		}
263		]
264		}
265		}
266		}
267		}
268		},
269		"cgroupsPath": {
270		"oneOf": [
271		{
272		"type": "null"
273		},
274		{
275		"type": "string"
276		}
277		]
278		},
279		"rootfsPropagation": {
280		"id": "https://opencontainers.org/schema/bundle/linux/rootfsPropagation",
281		"type": "string"
282		},
283		"seccomp": {
284		"id": "https://opencontainers.org/schema/bundle/linux/seccomp",
285		"properties": {
286		"defaultAction": {
287		"id": "https://opencontainers.org/schema/bundle/linux/seccomp/defaultAction",
288		"type": "string"
289		},
290		"architectures": {
291		"id": "https://opencontainers.org/schema/bundle/linux/seccomp/architectures",
292		"oneOf": [
293		{
294		"type": "array",
295		"items": {
296		"$ref": "defs-linux.json#/definitions/SeccompArch"
297		}
298		},
299		{
300		"type": "null"
301		}
302		]
303		},
304		"syscalls": {
305		"id": "https://opencontainers.org/schema/bundle/linux/seccomp/syscalls",
306		"type": "array",
307		"items": {
308		"$ref": "defs-linux.json#/definitions/Syscall"
309		}
310		}
311		},
312		"type": "object"
313		},
314		"sysctl": {
315		"id": "https://opencontainers.org/schema/bundle/linux/sysctl",
316		"oneOf": [
317		{
318		"$ref": "defs.json#/definitions/mapStringString"
319		},
320		{
321		"type": "null"
322		}
323		]
324		},
325		"maskedPaths": {
326		"id": "https://opencontainers.org/schema/bundle/linux/maskedPaths",
327		"$ref": "defs.json#/definitions/ArrayOfStrings"
328		},
329		"readonlyPaths": {
330		"id": "https://opencontainers.org/schema/bundle/linux/readonlyPaths",
331		"$ref": "defs.json#/definitions/ArrayOfStrings"
332		}
333		}
334		}
335		}

-181

~~schema/schema.json~~ less more

0		{
1		"description": "Schema for OpenContainer bundle configuration file",
2		"$schema": "http://json-schema.org/draft-04/schema#",
3		"id": "https://opencontainers.org/schema/bundle",
4		"type": "object",
5		"properties": {
6		"ociVersion": {
7		"description": "The version of OpenContainer specification configuration complies with",
8		"id": "https://opencontainers.org/schema/bundle/ociVersion",
9		"type": "string"
10		},
11		"hooks": {
12		"id": "https://opencontainers.org/schema/bundle/hooks",
13		"type": "object",
14		"properties": {
15		"prestart": {
16		"$ref": "defs.json#/definitions/ArrayOfHooks"
17		},
18		"poststart": {
19		"$ref": "defs.json#/definitions/ArrayOfHooks"
20		},
21		"poststop": {
22		"$ref": "defs.json#/definitions/ArrayOfHooks"
23		}
24		}
25		},
26		"annotations": {
27		"id": "https://opencontainers.org/schema/bundle/annotations",
28		"oneOf": [
29		{
30		"$ref": "defs.json#/definitions/mapStringString"
31		},
32		{
33		"type": "null"
34		}
35		]
36		},
37		"hostname": {
38		"id": "https://opencontainers.org/schema/bundle/hostname",
39		"type": "string"
40		},
41		"mounts": {
42		"id": "https://opencontainers.org/schema/bundle/mounts",
43		"type": "array",
44		"items": {
45		"$ref": "defs.json#/definitions/Mount"
46		}
47		},
48		"platform": {
49		"id": "https://opencontainers.org/schema/bundle/platform",
50		"type": "object",
51		"required": [
52		"arch",
53		"os"
54		],
55		"properties": {
56		"arch": {
57		"id": "https://opencontainers.org/schema/bundle/platform/arch",
58		"type": "string"
59		},
60		"os": {
61		"id": "https://opencontainers.org/schema/bundle/platform/os",
62		"type": "string"
63		}
64		}
65		},
66		"root": {
67		"description": "the root filesystem the container's bundle",
68		"id": "https://opencontainers.org/schema/bundle/root",
69		"type": "object",
70		"properties": {
71		"path": {
72		"id": "https://opencontainers.org/schema/bundle/root/path",
73		"$ref": "defs.json#/definitions/FilePath"
74		},
75		"readonly": {
76		"id": "https://opencontainers.org/schema/bundle/root/readonly",
77		"type": "boolean"
78		}
79		}
80		},
81		"process": {
82		"id": "https://opencontainers.org/schema/bundle/process",
83		"type": "object",
84		"required": [
85		"cwd",
86		"args"
87		],
88		"properties": {
89		"args": {
90		"id": "https://opencontainers.org/schema/bundle/process/args",
91		"$ref": "defs.json#/definitions/ArrayOfStrings"
92		},
93		"cwd": {
94		"id": "https://opencontainers.org/schema/bundle/process/cwd",
95		"type": "string"
96		},
97		"env": {
98		"id": "https://opencontainers.org/schema/bundle/process/env",
99		"$ref": "defs.json#/definitions/Env"
100		},
101		"terminal": {
102		"id": "https://opencontainers.org/schema/bundle/process/terminal",
103		"type": "boolean"
104		},
105		"user": {
106		"id": "https://opencontainers.org/schema/bundle/process/user",
107		"type": "object",
108		"properties": {
109		"uid": {
110		"id": "https://opencontainers.org/schema/bundle/process/user/uid",
111		"$ref": "defs.json#/definitions/UID"
112		},
113		"gid": {
114		"id": "https://opencontainers.org/schema/bundle/process/user/gid",
115		"$ref": "defs.json#/definitions/GID"
116		},
117		"additionalGids": {
118		"id": "https://opencontainers.org/schema/bundle/process/user/additionalGids",
119		"$ref": "defs.json#/definitions/ArrayOfGIDs"
120		}
121		}
122		},
123		"capabilities": {
124		"id": "https://opencontainers.org/schema/bundle/process/linux/capabilities",
125		"type": "array",
126		"items": {
127		"$ref": "defs-linux.json#/definitions/Capability"
128		}
129		},
130		"apparmorProfile": {
131		"id": "https://opencontainers.org/schema/bundle/process/linux/apparmorProfile",
132		"type": "string"
133		},
134		"selinuxProcessLabel": {
135		"id": "https://opencontainers.org/schema/bundle/process/linux/selinuxProcessLabel",
136		"type": "string"
137		},
138		"noNewPrivileges": {
139		"id": "https://opencontainers.org/schema/bundle/process/linux/noNewPrivileges",
140		"type": "boolean"
141		},
142		"rlimits": {
143		"id": "https://opencontainers.org/schema/bundle/linux/rlimits",
144		"type": "array",
145		"items": {
146		"id": "https://opencontainers.org/schema/bundle/linux/rlimits/0",
147		"type": "object",
148		"properties": {
149		"hard": {
150		"id": "https://opencontainers.org/schema/bundle/linux/rlimits/0/hard",
151		"$ref": "defs.json#/definitions/uint64"
152		},
153		"soft": {
154		"id": "https://opencontainers.org/schema/bundle/linux/rlimits/0/soft",
155		"$ref": "defs.json#/definitions/uint64"
156		},
157		"type": {
158		"id": "https://opencontainers.org/schema/bundle/linux/rlimits/0/type",
159		"type": "string",
160		"pattern": "^RLIMIT_[A-Z]+$"
161		}
162		}
163		}
164		}
165		}
166		},
167		"linux": {
168		"$ref": "schema-linux.json#/linux"
169		}
170		},
171		"required": [
172		"ociVersion",
173		"platform",
174		"process",
175		"root",
176		"hostname",
177		"mounts",
178		"hooks"
179		]
180		}

-45

~~schema/validate.go~~ less more

0		package main
1
2		import (
3		"fmt"
4		"os"
5		"path/filepath"
6
7		"github.com/xeipuuv/gojsonschema"
8		)
9
10		func main() {
11		if len(os.Args[1:]) != 2 {
12		fmt.Printf("ERROR: usage is: %s <schema.json> <config.json>", os.Args[0])
13		os.Exit(1)
14		}
15
16		schemaPath, err := filepath.Abs(os.Args[1])
17		if err != nil {
18		fmt.Println(err)
19		os.Exit(1)
20		}
21		documentPath, err := filepath.Abs(os.Args[2])
22		if err != nil {
23		fmt.Println(err)
24		os.Exit(1)
25		}
26
27		schemaLoader := gojsonschema.NewReferenceLoader("file://" + schemaPath)
28		documentLoader := gojsonschema.NewReferenceLoader("file://" + documentPath)
29
30		result, err := gojsonschema.Validate(schemaLoader, documentLoader)
31		if err != nil {
32		panic(err.Error())
33		}
34
35		if result.Valid() {
36		fmt.Printf("The document is valid\n")
37		} else {
38		fmt.Printf("The document is not valid. see errors :\n")
39		for _, desc := range result.Errors() {
40		fmt.Printf("- %s\n", desc)
41		}
42		os.Exit(1)
43		}
44		}

-417

~~specs-go/config.go~~ less more

0		package specs
1
2		import "os"
3
4		// Spec is the base configuration for the container. It specifies platform
5		// independent configuration. This information must be included when the
6		// bundle is packaged for distribution.
7		type Spec struct {
8		// Version is the version of the specification that is supported.
9		Version string `json:"ociVersion"`
10		// Platform is the host information for OS and Arch.
11		Platform Platform `json:"platform"`
12		// Process is the container's main process.
13		Process Process `json:"process"`
14		// Root is the root information for the container's filesystem.
15		Root Root `json:"root"`
16		// Hostname is the container's host name.
17		Hostname string `json:"hostname,omitempty"`
18		// Mounts profile configuration for adding mounts to the container's filesystem.
19		Mounts []Mount `json:"mounts"`
20		// Hooks are the commands run at various lifecycle events of the container.
21		Hooks Hooks `json:"hooks"`
22		// Annotations is an unstructured key value map that may be set by external tools to store and retrieve arbitrary metadata.
23		Annotations map[string]string `json:"annotations,omitempty"`
24
25		// Linux is platform specific configuration for Linux based containers.
26		Linux Linux `json:"linux" platform:"linux"`
27		}
28
29		// Process contains information to start a specific application inside the container.
30		type Process struct {
31		// Terminal creates an interactive terminal for the container.
32		Terminal bool `json:"terminal"`
33		// User specifies user information for the process.
34		User User `json:"user"`
35		// Args specifies the binary and arguments for the application to execute.
36		Args []string `json:"args"`
37		// Env populates the process environment for the process.
38		Env []string `json:"env,omitempty"`
39		// Cwd is the current working directory for the process and must be
40		// relative to the container's root.
41		Cwd string `json:"cwd"`
42		// Capabilities are Linux capabilities that are kept for the container.
43		Capabilities []string `json:"capabilities,omitempty" platform:"linux"`
44		// Rlimits specifies rlimit options to apply to the process.
45		Rlimits []Rlimit `json:"rlimits,omitempty"`
46		// NoNewPrivileges controls whether additional privileges could be gained by processes in the container.
47		NoNewPrivileges bool `json:"noNewPrivileges,omitempty"`
48
49		// ApparmorProfile specified the apparmor profile for the container. (this field is platform dependent)
50		ApparmorProfile string `json:"apparmorProfile,omitempty" platform:"linux"`
51		// SelinuxProcessLabel specifies the selinux context that the container process is run as. (this field is platform dependent)
52		SelinuxLabel string `json:"selinuxLabel,omitempty" platform:"linux"`
53		}
54
55		// User specifies Linux specific user and group information for the container's
56		// main process.
57		type User struct {
58		// UID is the user id. (this field is platform dependent)
59		UID uint32 `json:"uid,omitempty" platform:"linux"`
60		// GID is the group id. (this field is platform dependent)
61		GID uint32 `json:"gid,omitempty" platform:"linux"`
62		// AdditionalGids are additional group ids set for the container's process. (this field is platform dependent)
63		AdditionalGids []uint32 `json:"additionalGids,omitempty" platform:"linux"`
64		}
65
66		// Root contains information about the container's root filesystem on the host.
67		type Root struct {
68		// Path is the absolute path to the container's root filesystem.
69		Path string `json:"path"`
70		// Readonly makes the root filesystem for the container readonly before the process is executed.
71		Readonly bool `json:"readonly"`
72		}
73
74		// Platform specifies OS and arch information for the host system that the container
75		// is created for.
76		type Platform struct {
77		// OS is the operating system.
78		OS string `json:"os"`
79		// Arch is the architecture
80		Arch string `json:"arch"`
81		}
82
83		// Mount specifies a mount for a container.
84		type Mount struct {
85		// 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.
86		Destination string `json:"destination"`
87		// Type specifies the mount kind.
88		Type string `json:"type"`
89		// Source specifies the source path of the mount. In the case of bind mounts on
90		// Linux based systems this would be the file on the host.
91		Source string `json:"source"`
92		// Options are fstab style mount options.
93		Options []string `json:"options,omitempty"`
94		}
95
96		// Hook specifies a command that is run at a particular event in the lifecycle of a container
97		type Hook struct {
98		Path string `json:"path"`
99		Args []string `json:"args,omitempty"`
100		Env []string `json:"env,omitempty"`
101		Timeout *int `json:"timeout,omitempty"`
102		}
103
104		// Hooks for container setup and teardown
105		type Hooks struct {
106		// Prestart is a list of hooks to be run before the container process is executed.
107		// On Linux, they are run after the container namespaces are created.
108		Prestart []Hook `json:"prestart,omitempty"`
109		// Poststart is a list of hooks to be run after the container process is started.
110		Poststart []Hook `json:"poststart,omitempty"`
111		// Poststop is a list of hooks to be run after the container process exits.
112		Poststop []Hook `json:"poststop,omitempty"`
113		}
114
115		// Linux contains platform specific configuration for Linux based containers.
116		type Linux struct {
117		// UIDMapping specifies user mappings for supporting user namespaces on Linux.
118		UIDMappings []IDMapping `json:"uidMappings,omitempty"`
119		// GIDMapping specifies group mappings for supporting user namespaces on Linux.
120		GIDMappings []IDMapping `json:"gidMappings,omitempty"`
121		// Sysctl are a set of key value pairs that are set for the container on start
122		Sysctl map[string]string `json:"sysctl,omitempty"`
123		// Resources contain cgroup information for handling resource constraints
124		// for the container
125		Resources *Resources `json:"resources,omitempty"`
126		// CgroupsPath specifies the path to cgroups that are created and/or joined by the container.
127		// The path is expected to be relative to the cgroups mountpoint.
128		// If resources are specified, the cgroups at CgroupsPath will be updated based on resources.
129		CgroupsPath *string `json:"cgroupsPath,omitempty"`
130		// Namespaces contains the namespaces that are created and/or joined by the container
131		Namespaces []Namespace `json:"namespaces,omitempty"`
132		// Devices are a list of device nodes that are created for the container
133		Devices []Device `json:"devices,omitempty"`
134		// Seccomp specifies the seccomp security settings for the container.
135		Seccomp *Seccomp `json:"seccomp,omitempty"`
136		// RootfsPropagation is the rootfs mount propagation mode for the container.
137		RootfsPropagation string `json:"rootfsPropagation,omitempty"`
138		// MaskedPaths masks over the provided paths inside the container.
139		MaskedPaths []string `json:"maskedPaths,omitempty"`
140		// ReadonlyPaths sets the provided paths as RO inside the container.
141		ReadonlyPaths []string `json:"readonlyPaths,omitempty"`
142		}
143
144		// Namespace is the configuration for a Linux namespace
145		type Namespace struct {
146		// Type is the type of Linux namespace
147		Type NamespaceType `json:"type"`
148		// Path is a path to an existing namespace persisted on disk that can be joined
149		// and is of the same type
150		Path string `json:"path,omitempty"`
151		}
152
153		// NamespaceType is one of the Linux namespaces
154		type NamespaceType string
155
156		const (
157		// PIDNamespace for isolating process IDs
158		PIDNamespace NamespaceType = "pid"
159		// NetworkNamespace for isolating network devices, stacks, ports, etc
160		NetworkNamespace = "network"
161		// MountNamespace for isolating mount points
162		MountNamespace = "mount"
163		// IPCNamespace for isolating System V IPC, POSIX message queues
164		IPCNamespace = "ipc"
165		// UTSNamespace for isolating hostname and NIS domain name
166		UTSNamespace = "uts"
167		// UserNamespace for isolating user and group IDs
168		UserNamespace = "user"
169		)
170
171		// IDMapping specifies UID/GID mappings
172		type IDMapping struct {
173		// HostID is the UID/GID of the host user or group
174		HostID uint32 `json:"hostID"`
175		// ContainerID is the UID/GID of the container's user or group
176		ContainerID uint32 `json:"containerID"`
177		// Size is the length of the range of IDs mapped between the two namespaces
178		Size uint32 `json:"size"`
179		}
180
181		// Rlimit type and restrictions
182		type Rlimit struct {
183		// Type of the rlimit to set
184		Type string `json:"type"`
185		// Hard is the hard limit for the specified type
186		Hard uint64 `json:"hard"`
187		// Soft is the soft limit for the specified type
188		Soft uint64 `json:"soft"`
189		}
190
191		// HugepageLimit structure corresponds to limiting kernel hugepages
192		type HugepageLimit struct {
193		// Pagesize is the hugepage size
194		Pagesize *string `json:"pageSize,omitempty"`
195		// Limit is the limit of "hugepagesize" hugetlb usage
196		Limit *uint64 `json:"limit,omitempty"`
197		}
198
199		// InterfacePriority for network interfaces
200		type InterfacePriority struct {
201		// Name is the name of the network interface
202		Name string `json:"name"`
203		// Priority for the interface
204		Priority uint32 `json:"priority"`
205		}
206
207		// blockIODevice holds major:minor format supported in blkio cgroup
208		type blockIODevice struct {
209		// Major is the device's major number.
210		Major int64 `json:"major"`
211		// Minor is the device's minor number.
212		Minor int64 `json:"minor"`
213		}
214
215		// WeightDevice struct holds a `major:minor weight` pair for blkioWeightDevice
216		type WeightDevice struct {
217		blockIODevice
218		// Weight is the bandwidth rate for the device, range is from 10 to 1000
219		Weight *uint16 `json:"weight,omitempty"`
220		// 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
221		LeafWeight *uint16 `json:"leafWeight,omitempty"`
222		}
223
224		// ThrottleDevice struct holds a `major:minor rate_per_second` pair
225		type ThrottleDevice struct {
226		blockIODevice
227		// Rate is the IO rate limit per cgroup per device
228		Rate *uint64 `json:"rate,omitempty"`
229		}
230
231		// BlockIO for Linux cgroup 'blkio' resource management
232		type BlockIO struct {
233		// Specifies per cgroup weight, range is from 10 to 1000
234		Weight *uint16 `json:"blkioWeight,omitempty"`
235		// Specifies tasks' weight in the given cgroup while competing with the cgroup's child cgroups, range is from 10 to 1000, CFQ scheduler only
236		LeafWeight *uint16 `json:"blkioLeafWeight,omitempty"`
237		// Weight per cgroup per device, can override BlkioWeight
238		WeightDevice []WeightDevice `json:"blkioWeightDevice,omitempty"`
239		// IO read rate limit per cgroup per device, bytes per second
240		ThrottleReadBpsDevice []ThrottleDevice `json:"blkioThrottleReadBpsDevice,omitempty"`
241		// IO write rate limit per cgroup per device, bytes per second
242		ThrottleWriteBpsDevice []ThrottleDevice `json:"blkioThrottleWriteBpsDevice,omitempty"`
243		// IO read rate limit per cgroup per device, IO per second
244		ThrottleReadIOPSDevice []ThrottleDevice `json:"blkioThrottleReadIOPSDevice,omitempty"`
245		// IO write rate limit per cgroup per device, IO per second
246		ThrottleWriteIOPSDevice []ThrottleDevice `json:"blkioThrottleWriteIOPSDevice,omitempty"`
247		}
248
249		// Memory for Linux cgroup 'memory' resource management
250		type Memory struct {
251		// Memory limit (in bytes).
252		Limit *uint64 `json:"limit,omitempty"`
253		// Memory reservation or soft_limit (in bytes).
254		Reservation *uint64 `json:"reservation,omitempty"`
255		// Total memory limit (memory + swap).
256		Swap *uint64 `json:"swap,omitempty"`
257		// Kernel memory limit (in bytes).
258		Kernel *uint64 `json:"kernel,omitempty"`
259		// Kernel memory limit for tcp (in bytes)
260		KernelTCP *uint64 `json:"kernelTCP"`
261		// How aggressive the kernel will swap memory pages. Range from 0 to 100.
262		Swappiness *uint64 `json:"swappiness,omitempty"`
263		}
264
265		// CPU for Linux cgroup 'cpu' resource management
266		type CPU struct {
267		// CPU shares (relative weight (ratio) vs. other cgroups with cpu shares).
268		Shares *uint64 `json:"shares,omitempty"`
269		// CPU hardcap limit (in usecs). Allowed cpu time in a given period.
270		Quota *uint64 `json:"quota,omitempty"`
271		// CPU period to be used for hardcapping (in usecs).
272		Period *uint64 `json:"period,omitempty"`
273		// How much time realtime scheduling may use (in usecs).
274		RealtimeRuntime *uint64 `json:"realtimeRuntime,omitempty"`
275		// CPU period to be used for realtime scheduling (in usecs).
276		RealtimePeriod *uint64 `json:"realtimePeriod,omitempty"`
277		// CPUs to use within the cpuset. Default is to use any CPU available.
278		Cpus *string `json:"cpus,omitempty"`
279		// List of memory nodes in the cpuset. Default is to use any available memory node.
280		Mems *string `json:"mems,omitempty"`
281		}
282
283		// Pids for Linux cgroup 'pids' resource management (Linux 4.3)
284		type Pids struct {
285		// Maximum number of PIDs. Default is "no limit".
286		Limit *int64 `json:"limit,omitempty"`
287		}
288
289		// Network identification and priority configuration
290		type Network struct {
291		// Set class identifier for container's network packets
292		ClassID *uint32 `json:"classID"`
293		// Set priority of network traffic for container
294		Priorities []InterfacePriority `json:"priorities,omitempty"`
295		}
296
297		// Resources has container runtime resource constraints
298		type Resources struct {
299		// Devices are a list of device rules for the whitelist controller
300		Devices []DeviceCgroup `json:"devices"`
301		// DisableOOMKiller disables the OOM killer for out of memory conditions
302		DisableOOMKiller *bool `json:"disableOOMKiller,omitempty"`
303		// Specify an oom_score_adj for the container.
304		OOMScoreAdj *int `json:"oomScoreAdj,omitempty"`
305		// Memory restriction configuration
306		Memory *Memory `json:"memory,omitempty"`
307		// CPU resource restriction configuration
308		CPU *CPU `json:"cpu,omitempty"`
309		// Task resource restriction configuration.
310		Pids *Pids `json:"pids,omitempty"`
311		// BlockIO restriction configuration
312		BlockIO *BlockIO `json:"blockIO,omitempty"`
313		// Hugetlb limit (in bytes)
314		HugepageLimits []HugepageLimit `json:"hugepageLimits,omitempty"`
315		// Network restriction configuration
316		Network *Network `json:"network,omitempty"`
317		}
318
319		// Device represents the mknod information for a Linux special device file
320		type Device struct {
321		// Path to the device.
322		Path string `json:"path"`
323		// Device type, block, char, etc.
324		Type string `json:"type"`
325		// Major is the device's major number.
326		Major int64 `json:"major"`
327		// Minor is the device's minor number.
328		Minor int64 `json:"minor"`
329		// FileMode permission bits for the device.
330		FileMode *os.FileMode `json:"fileMode,omitempty"`
331		// UID of the device.
332		UID *uint32 `json:"uid,omitempty"`
333		// Gid of the device.
334		GID *uint32 `json:"gid,omitempty"`
335		}
336
337		// DeviceCgroup represents a device rule for the whitelist controller
338		type DeviceCgroup struct {
339		// Allow or deny
340		Allow bool `json:"allow"`
341		// Device type, block, char, etc.
342		Type *string `json:"type,omitempty"`
343		// Major is the device's major number.
344		Major *int64 `json:"major,omitempty"`
345		// Minor is the device's minor number.
346		Minor *int64 `json:"minor,omitempty"`
347		// Cgroup access permissions format, rwm.
348		Access *string `json:"access,omitempty"`
349		}
350
351		// Seccomp represents syscall restrictions
352		type Seccomp struct {
353		DefaultAction Action `json:"defaultAction"`
354		Architectures []Arch `json:"architectures"`
355		Syscalls []Syscall `json:"syscalls,omitempty"`
356		}
357
358		// Arch used for additional architectures
359		type Arch string
360
361		// Additional architectures permitted to be used for system calls
362		// By default only the native architecture of the kernel is permitted
363		const (
364		ArchX86 Arch = "SCMP_ARCH_X86"
365		ArchX86_64 Arch = "SCMP_ARCH_X86_64"
366		ArchX32 Arch = "SCMP_ARCH_X32"
367		ArchARM Arch = "SCMP_ARCH_ARM"
368		ArchAARCH64 Arch = "SCMP_ARCH_AARCH64"
369		ArchMIPS Arch = "SCMP_ARCH_MIPS"
370		ArchMIPS64 Arch = "SCMP_ARCH_MIPS64"
371		ArchMIPS64N32 Arch = "SCMP_ARCH_MIPS64N32"
372		ArchMIPSEL Arch = "SCMP_ARCH_MIPSEL"
373		ArchMIPSEL64 Arch = "SCMP_ARCH_MIPSEL64"
374		ArchMIPSEL64N32 Arch = "SCMP_ARCH_MIPSEL64N32"
375		)
376
377		// Action taken upon Seccomp rule match
378		type Action string
379
380		// Define actions for Seccomp rules
381		const (
382		ActKill Action = "SCMP_ACT_KILL"
383		ActTrap Action = "SCMP_ACT_TRAP"
384		ActErrno Action = "SCMP_ACT_ERRNO"
385		ActTrace Action = "SCMP_ACT_TRACE"
386		ActAllow Action = "SCMP_ACT_ALLOW"
387		)
388
389		// Operator used to match syscall arguments in Seccomp
390		type Operator string
391
392		// Define operators for syscall arguments in Seccomp
393		const (
394		OpNotEqual Operator = "SCMP_CMP_NE"
395		OpLessThan Operator = "SCMP_CMP_LT"
396		OpLessEqual Operator = "SCMP_CMP_LE"
397		OpEqualTo Operator = "SCMP_CMP_EQ"
398		OpGreaterEqual Operator = "SCMP_CMP_GE"
399		OpGreaterThan Operator = "SCMP_CMP_GT"
400		OpMaskedEqual Operator = "SCMP_CMP_MASKED_EQ"
401		)
402
403		// Arg used for matching specific syscall arguments in Seccomp
404		type Arg struct {
405		Index uint `json:"index"`
406		Value uint64 `json:"value"`
407		ValueTwo uint64 `json:"valueTwo"`
408		Op Operator `json:"op"`
409		}
410
411		// Syscall is used to match a syscall in Seccomp
412		type Syscall struct {
413		Name string `json:"name"`
414		Action Action `json:"action"`
415		Args []Arg `json:"args,omitempty"`
416		}

-13

~~specs-go/state.go~~ less more

0		package specs
1
2		// State holds information about the runtime state of the container.
3		type State struct {
4		// Version is the version of the specification that is supported.
5		Version string `json:"version"`
6		// ID is the container ID
7		ID string `json:"id"`
8		// Pid is the process id for the container's main process.
9		Pid int `json:"pid"`
10		// BundlePath is the path to the container's bundle directory.
11		BundlePath string `json:"bundlePath"`
12		}

-18

~~specs-go/version.go~~ less more

0		package specs
1
2		import "fmt"
3
4		const (
5		// VersionMajor is for an API incompatible changes
6		VersionMajor = 0
7		// VersionMinor is for functionality in a backwards-compatible manner
8		VersionMinor = 5
9		// VersionPatch is for backwards-compatible bug fixes
10		VersionPatch = 0
11
12		// VersionDev indicates development branch. Releases will be empty string.
13		VersionDev = ""
14		)
15
16		// Version is the specification version that the package types support.
17		var Version = fmt.Sprintf("%d.%d.%d%s", VersionMajor, VersionMinor, VersionPatch, VersionDev)

-32

~~style.md~~ less more

0		# Style and conventions
1
2		## One sentence per line
3
4		To keep consistency throughout the Markdown files in the Open Container spec all files should be formatted one sentence per line.
5		This fixes two things: it makes diffing easier with git and it resolves fights about line wrapping length.
6		For example, this paragraph will span three lines in the Markdown source.
7
8		## Traditionally hex settings should use JSON integers, not JSON strings
9
10		For example, [`"classID": 1048577`][class-id] instead of `"classID": "0x100001"`.
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
13		## Constant names should keep redundant prefixes
14
15		For example, `CAP_KILL` instead of `KILL` in [`linux.capabilities`][capabilities].
16		The redundancy reduction from removing the namespacing prefix is not useful enough to be worth trimming the upstream identifier ([source][keep-prefix]).
17
18		## Optional settings should have pointer Go types
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]).
22
23
24		[capabilities]: config-linux.md#capabilities
25		[class-id]: config-linux.md#network
26		[integer-over-hex]: https://github.com/opencontainers/runtime-spec/pull/267#discussion_r48360013
27		[keep-prefix]: https://github.com/opencontainers/runtime-spec/pull/159#issuecomment-138728337
28		[no-pointer-for-boolean]: https://github.com/opencontainers/runtime-spec/pull/290#discussion_r50296396
29		[no-pointer-for-slices]: https://github.com/opencontainers/runtime-spec/pull/316/files#r50782982
30		[optional-pointer]: https://github.com/opencontainers/runtime-spec/pull/233#discussion_r47829711
31		[pointer-when-updates-require-changes]: https://github.com/opencontainers/runtime-spec/pull/317/files#r50932706