Commit 69051f315f51369f0943cc8bb0525dabd8127836 - golang-github-opencontainers-specs

Merge tag 'upstream/0.4.0' Upstream version 0.4.0 Dmitry Smirnov 8 years ago

19 changed file(s) with 1772 addition(s) and 561 deletion(s). Raw diff Collapse all Expand all

+37

-5

ChangeLog less more

0	0	OpenContainers Specifications
	1
	2	Changes with v0.4.0:
	3	Breaking changes:
	4
	5	* config: Move capabilities, selinuxProcessLabel, apparmorProfile,
	6	and noNewPrivileges from the linux setting to the process setting
	7	and make them optional, renaming selinuxProcessLabel to
	8	selinuxLabel, #329, #330, #339
	9	* runtime: Rename version to ociVerison in the state JSON, #225
	10	* runtime: Remove the directory requirement for storing state, now
	11	that there is a 'state' operation, #225, #334
	12	* go: Shift .go to specs-go/.go, #276
	13	* config: Move rlimits to process, #341
	14	* go: Move config_linux.go content into config.go, removing
	15	LinuxSpec, #310
	16
	17	Additions:
	18
	19	* schema: Add JSON Schema (and validator) for `config.json`, #313
	20	* config: Add annotations for opaque-to-the-runtime data, #331
	21	* config-linux: Make seccomp optional, #333
	22	* runtime: Added additional operations: state, stop, and exec.
	23	#225
	24
	25	Minor fixes and documentation:
	26
	27	* config-linux: Change mount type from rune to string and fix
	28	octal fileMode examples, #323
	29	* runtime: RFC 2119 phrasing for the lifecycle, #225
	30	* README: Add a full example of config.json, #276
	31	* README: Replace BlueJeans with UberConference, #326, #338
	32	* style: Document Go-pointer exceptions, #317
1	33
2	34	Changes with v0.3.0:
3	35	Breaking changes:
4
	36
5	37	* config: Single, unified config file, #284
6	38	* config: cwd is a required default, and must be absolute, #286,
7	39	#307, #308, #312
8	40	* config: qualify the name of the version field, #309
9	41	* config-linux: Convert classID from hex to uint32, #296
10	42	* config-linux: Separate mknod from cgroups, #298
11
	43
12	44	Additions:
13
	45
14	46	* config-linux: Add NoNewPrivileges setting for linux, #290
15
	47
16	48	Minor fixes and documentation:
17
	49
18	50	* config-linux: clarify oom_score_adj, #236, #292
19	51	* config-linux: Update links to cgroups documentation, #318
20	52	* config-linux: Remove pointers for slices preferring omitempty

+10

-7

README.md less more

4	4
5	5	Table of Contents
6	6
7		- [Container Principles](principles.md)
8		- [Specification Style](style.md)
	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)
9	13	- [Filesystem Bundle](bundle.md)
	14	- [Runtime and Lifecycle](runtime.md)
	15	- [Linux Specific Runtime](runtime-linux.md)
10	16	- Configuration
11	17	- [General](config.md)
12	18	- [Linux-specific](config-linux.md)
13		- [Runtime and Lifecycle](runtime.md)
14		- [Linux Specific Runtime](runtime-linux.md)
15		- [Implementations](implementations.md)
16	19	- [Glossary](glossary.md)
17	20
18	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).

66	69	## Weekly Call
67	70
68	71	The contributors and maintainers of the project have a weekly meeting Wednesdays at 10:00 AM PST.
69		Everyone is welcome to participate in the [BlueJeans call][BlueJeans].
	72	Everyone is welcome to participate via [UberConference web][UberConference] or audio-only: 646-494-8704 (no PIN needed.)
70	73	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.
71	74	Minutes are posted to the [mailing list](#mailing-list) and minutes from past calls are archived to the [wiki](https://github.com/opencontainers/specs/wiki) for those who are unable to join the call.
72	75

153	156	* If there was important/useful/essential conversation or information, copy or include a reference
154	157	8. When possible, one keyword to scope the change in the subject (i.e. "README: ...", "runtime: ...")
155	158
156		[BlueJeans]: https://bluejeans.com/1771332256/
	159	[UberConference]: https://www.uberconference.com/ssaul

-68

config-linux.md less more

1	1
2	2	The Linux container specification uses various kernel features like namespaces, cgroups, capabilities, LSM, and file system jails to fulfill the spec.
3	3	Additional information is needed for Linux over the [default spec configuration](config.md) in order to configure these various kernel features.
4
5		## Capabilities
6
7		Capabilities is an array that specifies Linux capabilities that can be provided to the process inside the container.
8		Valid values are the strings for capabilities defined in [the man page](http://man7.org/linux/man-pages/man7/capabilities.7.html)
9
10		```json
11		"capabilities": [
12		"CAP_AUDIT_WRITE",
13		"CAP_KILL",
14		"CAP_NET_BIND_SERVICE"
15		]
16		```
17	4
18	5	## Default File Systems
19	6

111	98
112	99	The following parameters can be specified:
113	100
114		* `type` (char, required) - type of device: `c`, `b`, `u` or `p`.
	101	* `type` (string, required) - type of device: `c`, `b`, `u` or `p`.
115	102	More info in [mknod(1)][mknod.1].
116	103	* `path` (string, required) - full path to device inside container.
117	104	* `major, minor` (int64, required unless `type`* is `p`)* - [major, minor numbers][devices] for the device.

129	116	"type": "c",
130	117	"major": 10,
131	118	"minor": 229,
132		"fileMode": 0666,
	119	"fileMode": 438,
133	120	"uid": 0,
134	121	"gid": 0
135	122	},

138	125	"type": "b",
139	126	"major": 8,
140	127	"minor": 0,
141		"fileMode": 0660,
	128	"fileMode": 432,
142	129	"uid": 0,
143	130	"gid": 0
144	131	}

193	180	The following parameters can be specified:
194	181
195	182	* `allow` (boolean, required) - whether the entry is allowed or denied.
196		* `type` (char, optional) - type of device: `a` (all), `c` (char), or `b` (block).
	183	* `type` (string, optional) - type of device: `a` (all), `c` (char), or `b` (block).
197	184	`null` or unset values mean "all", mapping to `a`.
198	185	* `major, minor` (int64, optional) - [major, minor numbers][devices] for the device.
199	186	`null` or unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices].

467	454	}
468	455	```
469	456
470		## Rlimits
471
472		rlimits allow setting resource limits.
473		`type` is a string with a value from those defined in [the man page](http://man7.org/linux/man-pages/man2/setrlimit.2.html).
474		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.
475
476		###### Example
477
478		```json
479		"rlimits": [
480		{
481		"type": "RLIMIT_NPROC",
482		"soft": 1024,
483		"hard": 102400
484		}
485		]
486		```
487
488		## SELinux process label
489
490		SELinux process label specifies the label with which the processes in a container are run.
491		For more information about SELinux, see [Selinux documentation](http://selinuxproject.org/page/Main_Page)
492
493		###### Example
494
495		```json
496		"selinuxProcessLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675"
497		```
498
499		## Apparmor profile
500
501		Apparmor profile specifies the name of the apparmor profile that will be used for the container.
502		For more information about Apparmor, see [Apparmor documentation](https://wiki.ubuntu.com/AppArmor)
503
504		###### Example
505
506		```json
507		"apparmorProfile": "acme_secure_profile"
508		```
509
510	457	## seccomp
511	458
512	459	Seccomp provides application sandboxing mechanism in the Linux kernel.

573	520	"rootfsPropagation": "slave",
574	521	```
575	522
576		## No new privileges
577
578		Setting `noNewPrivileges` to true prevents the processes in the container from gaining additional privileges.
579		[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.
580
581		###### Example
582
583		```json
584		"noNewPrivileges": true,
585		```
586
587	523	[cgroup-v1]: https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt
588	524	[cgroup-v1-blkio]: https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt
589	525	[cgroup-v1-cpusets]: https://www.kernel.org/doc/Documentation/cgroup-v1/cpusets.txt

-84

~~config.go~~ less more

0		package specs
1
2		// Spec is the base configuration for the container. It specifies platform
3		// independent configuration. This information must be included when the
4		// bundle is packaged for distribution.
5		type Spec struct {
6		// Version is the version of the specification that is supported.
7		Version string `json:"ociVersion"`
8		// Platform is the host information for OS and Arch.
9		Platform Platform `json:"platform"`
10		// Process is the container's main process.
11		Process Process `json:"process"`
12		// Root is the root information for the container's filesystem.
13		Root Root `json:"root"`
14		// Hostname is the container's host name.
15		Hostname string `json:"hostname,omitempty"`
16		// Mounts profile configuration for adding mounts to the container's filesystem.
17		Mounts []Mount `json:"mounts"`
18		// Hooks are the commands run at various lifecycle events of the container.
19		Hooks Hooks `json:"hooks"`
20		}
21
22		// Process contains information to start a specific application inside the container.
23		type Process struct {
24		// Terminal creates an interactive terminal for the container.
25		Terminal bool `json:"terminal"`
26		// User specifies user information for the process.
27		User User `json:"user"`
28		// Args specifies the binary and arguments for the application to execute.
29		Args []string `json:"args"`
30		// Env populates the process environment for the process.
31		Env []string `json:"env,omitempty"`
32		// Cwd is the current working directory for the process and must be
33		// relative to the container's root.
34		Cwd string `json:"cwd"`
35		}
36
37		// Root contains information about the container's root filesystem on the host.
38		type Root struct {
39		// Path is the absolute path to the container's root filesystem.
40		Path string `json:"path"`
41		// Readonly makes the root filesystem for the container readonly before the process is executed.
42		Readonly bool `json:"readonly"`
43		}
44
45		// Platform specifies OS and arch information for the host system that the container
46		// is created for.
47		type Platform struct {
48		// OS is the operating system.
49		OS string `json:"os"`
50		// Arch is the architecture
51		Arch string `json:"arch"`
52		}
53
54		// Mount specifies a mount for a container.
55		type Mount struct {
56		// 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.
57		Destination string `json:"destination"`
58		// Type specifies the mount kind.
59		Type string `json:"type"`
60		// Source specifies the source path of the mount. In the case of bind mounts on
61		// linux based systems this would be the file on the host.
62		Source string `json:"source"`
63		// Options are fstab style mount options.
64		Options []string `json:"options,omitempty"`
65		}
66
67		// Hook specifies a command that is run at a particular event in the lifecycle of a container
68		type Hook struct {
69		Path string `json:"path"`
70		Args []string `json:"args,omitempty"`
71		Env []string `json:"env,omitempty"`
72		}
73
74		// Hooks for container setup and teardown
75		type Hooks struct {
76		// Prestart is a list of hooks to be run before the container process is executed.
77		// On Linux, they are run after the container namespaces are created.
78		Prestart []Hook `json:"prestart,omitempty"`
79		// Poststart is a list of hooks to be run after the container process is started.
80		Poststart []Hook `json:"poststart,omitempty"`
81		// Poststop is a list of hooks to be run after the container process exits.
82		Poststop []Hook `json:"poststop,omitempty"`
83		}

+213

-0

config.md less more

89	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	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	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
92	106	The user for the process is a platform-specific structure that allows specific control over which user the process runs as.
93	107	For Linux-based systems the user structure has the following fields:
94	108

113	127	"cwd": "/root",
114	128	"args": [
115	129	"sh"
	130	],
	131	"apparmorProfile": "acme_secure_profile",
	132	"selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675",
	133	"noNewPrivileges": true,
	134	"capabilities": [
	135	"CAP_AUDIT_WRITE",
	136	"CAP_KILL",
	137	"CAP_NET_BIND_SERVICE"
	138	],
	139	"rlimits": [
	140	{
	141	"type": "RLIMIT_NOFILE",
	142	"hard": 1024,
	143	"soft": 1024
	144	}
116	145	]
117	146	}
118	147	```

211	240	`args` and `env` are optional.
212	241	The semantics are the same as `Path`, `Args` and `Env` in [golang Cmd](https://golang.org/pkg/os/exec/#Cmd).
213	242
	243	## Annotations
	244
	245	Annotations are optional arbitrary non-identifying metadata that can be attached to containers.
	246	This information may be large, may be structured or unstructured.
	247	Annotations are key-value maps.
	248
	249	```json
	250	"annotations": {
	251	"key1" : "value1",
	252	"key2" : "value2"
	253	}
	254	```
	255
	256	## Configuration Schema Example
	257
	258	Here is a full example `config.json` for reference.
	259
	260	```json
	261	{
	262	"ociVersion": "0.3.0",
	263	"platform": {
	264	"os": "linux",
	265	"arch": "amd64"
	266	},
	267	"process": {
	268	"terminal": true,
	269	"user": {
	270	"uid": 1,
	271	"gid": 1,
	272	"additionalGids": [
	273	5,
	274	6
	275	]
	276	},
	277	"args": [
	278	"sh"
	279	],
	280	"env": [
	281	"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
	282	"TERM=xterm"
	283	],
	284	"cwd": "/",
	285	"capabilities": [
	286	"CAP_AUDIT_WRITE",
	287	"CAP_KILL",
	288	"CAP_NET_BIND_SERVICE"
	289	],
	290	"rlimits": [
	291	{
	292	"type": "RLIMIT_NOFILE",
	293	"hard": 1024,
	294	"soft": 1024
	295	}
	296	],
	297	"apparmorProfile": "",
	298	"selinuxLabel": ""
	299	},
	300	"root": {
	301	"path": "rootfs",
	302	"readonly": true
	303	},
	304	"hostname": "slartibartfast",
	305	"mounts": [
	306	{
	307	"destination": "/proc",
	308	"type": "proc",
	309	"source": "proc"
	310	},
	311	{
	312	"destination": "/dev",
	313	"type": "tmpfs",
	314	"source": "tmpfs",
	315	"options": [
	316	"nosuid",
	317	"strictatime",
	318	"mode=755",
	319	"size=65536k"
	320	]
	321	},
	322	{
	323	"destination": "/dev/pts",
	324	"type": "devpts",
	325	"source": "devpts",
	326	"options": [
	327	"nosuid",
	328	"noexec",
	329	"newinstance",
	330	"ptmxmode=0666",
	331	"mode=0620",
	332	"gid=5"
	333	]
	334	},
	335	{
	336	"destination": "/dev/shm",
	337	"type": "tmpfs",
	338	"source": "shm",
	339	"options": [
	340	"nosuid",
	341	"noexec",
	342	"nodev",
	343	"mode=1777",
	344	"size=65536k"
	345	]
	346	},
	347	{
	348	"destination": "/dev/mqueue",
	349	"type": "mqueue",
	350	"source": "mqueue",
	351	"options": [
	352	"nosuid",
	353	"noexec",
	354	"nodev"
	355	]
	356	},
	357	{
	358	"destination": "/sys",
	359	"type": "sysfs",
	360	"source": "sysfs",
	361	"options": [
	362	"nosuid",
	363	"noexec",
	364	"nodev"
	365	]
	366	},
	367	{
	368	"destination": "/sys/fs/cgroup",
	369	"type": "cgroup",
	370	"source": "cgroup",
	371	"options": [
	372	"nosuid",
	373	"noexec",
	374	"nodev",
	375	"relatime",
	376	"ro"
	377	]
	378	}
	379	],
	380	"hooks": {
	381	"prestart": [
	382	{
	383	"path": "/usr/bin/uptime",
	384	"args": [
	385	"/usr/bin/uptime"
	386	],
	387	"env": []
	388	}
	389	]
	390	},
	391	"linux": {
	392	"resources": {
	393	"devices": [
	394	{
	395	"allow": false,
	396	"access": "rwm"
	397	}
	398	]
	399	},
	400	"namespaces": [
	401	{
	402	"type": "pid"
	403	},
	404	{
	405	"type": "network"
	406	},
	407	{
	408	"type": "ipc"
	409	},
	410	{
	411	"type": "uts"
	412	},
	413	{
	414	"type": "mount"
	415	}
	416	],
	417	"devices": null,
	418	"seccomp": {
	419	"defaultAction": "",
	420	"architectures": null
	421	}
	422	}
	423	}
	424	```
	425
	426
214	427	[uts-namespace]: http://man7.org/linux/man-pages/man7/namespaces.7.html

-333

~~config_linux.go~~ less more

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

+100

-30

runtime.md less more

0	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.
1	6
2	7	## State
3	8
4		Runtime MUST store container metadata on disk so that external tools can consume and act on this information.
5		It is recommended that this data be stored in a temporary filesystem so that it can be removed on a system reboot.
6		On Linux/Unix based systems the metadata MUST be stored under `/run/opencontainer/containers`.
7		For non-Linux/Unix based systems the location of the root metadata directory is currently undefined.
8		Within that directory there MUST be one directory for each container created, where the name of the directory MUST be the ID of the container.
9		For example: for a Linux container with an ID of `173975398351`, there will be a corresponding directory: `/run/opencontainer/containers/173975398351`.
10		Within each container's directory, there MUST be a JSON encoded file called `state.json` that contains the runtime state of the container.
11		For example: `/run/opencontainer/containers/173975398351/state.json`.
	9	The state of a container MUST include, at least, the following propeties:
12	10
13		The `state.json` file MUST contain all of the following properties:
14
15		* `version`: (string) is the OCF specification version used when creating the container.
	11	* `ociVersion`: (string) is the OCI specification version used when creating the container.
16	12	* `id`: (string) is the container's ID.
17	13	This MUST be unique across all containers on this host.
18	14	There is no requirement that it be unique across hosts.

22	18	* `bundlePath`: (string) is the absolute path to the container's bundle directory.
23	19	This is provided so that consumers can find the container's configuration and root filesystem on the host.
24	20
25		Example
26
	21	When serialized in JSON, the format MUST adhere to the following pattern:
27	22	```json
28	23	{
29		"version": "0.2.0",
30		"id": "oc-container",
	24	"ociVersion": "0.2.0",
	25	"id": "oci-container1",
31	26	"pid": 4422,
32	27	"bundlePath": "/containers/redis"
33	28	}
34	29	```
35	30
	31	See [Query State](#query-state) for information on retrieving the state of a container.
	32
36	33	## Lifecycle
37	34	The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist.
38	35
39		1. OCI compliant runtime is invoked by passing the bundle path as argument.
40		2. The container's runtime environment is created according to the configuration in [`config.json`](config.md).
41		Any updates to `config.json` after container is running do not affect the container.
42		3. The container's state.json file is written to the filesystem.
43		4. The prestart hooks are invoked by the runtime.
44		If any prestart hook fails, then the container is stopped and the lifecycle continues at step 8.
45		5. The user specified process is executed in the container.
46		6. The poststart hooks are invoked by the runtime.
47		If any poststart hook fails, then the container is stopped and the lifecycle continues at step 8.
48		7. Additional actions such as pausing the container, resuming the container or signaling the container may be performed using the runtime interface.
49		The container could also error out or crash.
50		8. The container is destroyed by undoing the steps performed during create phase (step 2).
51		9. The poststop hooks are invoked by the runtime and errors, if any, are logged.
52		10. The state.json file associated with the container is removed and the return code of the container's user specified process is returned or logged.
	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.
53	49
54	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.
55	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 manadate 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
56	125	## Hooks
57	126
58		See [runtime configuration for hooks](./config.md#hooks)
	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

-0

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

+239

-0

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	"type": "integer"
	96	},
	97	"Device": {
	98	"properties": {
	99	"type": {
	100	"$ref": "#/definitions/FileType"
	101	},
	102	"permissions": {
	103	"$ref": "#/definitions/FilePermissions"
	104	},
	105	"path": {
	106	"$ref": "defs.json#/definitions/FilePath"
	107	},
	108	"fileMode": {
	109	"$ref": "#/definitions/FileMode"
	110	},
	111	"major": {
	112	"$ref": "#/definitions/Major"
	113	},
	114	"minor": {
	115	"$ref": "#/definitions/Minor"
	116	},
	117	"uid": {
	118	"$ref": "defs.json#/definitions/UID"
	119	},
	120	"gid": {
	121	"$ref": "defs.json#/definitions/GID"
	122	}
	123	}
	124	},
	125	"blkioWeight": {
	126	"type": "integer",
	127	"minimum": 10,
	128	"maximum": 1000
	129	},
	130	"blkioWeightPointer": {
	131	"oneOf": [
	132	{
	133	"$ref": "#/definitions/blkioWeight"
	134	},
	135	{
	136	"type": "null"
	137	}
	138	]
	139	},
	140	"blockIODevice": {
	141	"properties": {
	142	"major": {
	143	"$ref": "#/definitions/Major"
	144	},
	145	"minor": {
	146	"$ref": "#/definitions/Minor"
	147	}
	148	},
	149	"required": [
	150	"major",
	151	"minor"
	152	]
	153	},
	154	"blockIODeviceWeight": {
	155	"type": "object",
	156	"allOf": [
	157	{
	158	"$ref": "#/definitions/blockIODevice"
	159	},
	160	{
	161	"properties": {
	162	"weight": {
	163	"$ref": "#/definitions/blkioWeightPointer"
	164	},
	165	"leafWeight": {
	166	"$ref": "#/definitions/blkioWeightPointer"
	167	}
	168	}
	169	}
	170	]
	171	},
	172	"blockIODeviceWeightPointer": {
	173	"oneOf": [
	174	{
	175	"$ref": "#/definitions/blockIODeviceWeight"
	176	},
	177	{
	178	"type": "null"
	179	}
	180	]
	181	},
	182	"blockIODeviceThrottle": {
	183	"allOf": [
	184	{
	185	"$ref": "#/definitions/blockIODevice"
	186	},
	187	{
	188	"properties": {
	189	"rate": {
	190	"$ref": "defs.json#/definitions/uint64Pointer"
	191	}
	192	}
	193	}
	194	]
	195	},
	196	"blockIODeviceThrottlePointer": {
	197	"oneOf": [
	198	{
	199	"$ref": "#/definitions/blockIODeviceThrottle"
	200	},
	201	{
	202	"type": "null"
	203	}
	204	]
	205	},
	206	"NetworkInterfacePriority": {
	207	"properties": {
	208	"name": {
	209	"type": "string"
	210	},
	211	"priority": {
	212	"$ref": "defs.json#/definitions/uint32"
	213	}
	214	}
	215	},
	216	"NamespaceType": {
	217	"type": "string",
	218	"enum": [
	219	"mount",
	220	"pid",
	221	"network",
	222	"uts",
	223	"ipc",
	224	"user"
	225	]
	226	},
	227	"NamespaceReference": {
	228	"properties": {
	229	"type": {
	230	"$ref": "#/definitions/NamespaceType"
	231	},
	232	"path": {
	233	"$ref": "defs.json#/definitions/FilePath"
	234	}
	235	}
	236	}
	237	}
	238	}

+160

-0

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	}

+343

-0

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

+158

-0

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/linux/sysctl",
	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	}
	143	},
	144	"linux": {
	145	"$ref": "schema-linux.json#/linux"
	146	}
	147	},
	148	"required": [
	149	"ociVersion",
	150	"platform",
	151	"process",
	152	"root",
	153	"hostname",
	154	"mounts",
	155	"hooks"
	156	]
	157	}

+45

-0

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	}

+412

-0

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	}
	102
	103	// Hooks for container setup and teardown
	104	type Hooks struct {
	105	// Prestart is a list of hooks to be run before the container process is executed.
	106	// On Linux, they are run after the container namespaces are created.
	107	Prestart []Hook `json:"prestart,omitempty"`
	108	// Poststart is a list of hooks to be run after the container process is started.
	109	Poststart []Hook `json:"poststart,omitempty"`
	110	// Poststop is a list of hooks to be run after the container process exits.
	111	Poststop []Hook `json:"poststop,omitempty"`
	112	}
	113
	114	// Linux contains platform specific configuration for Linux based containers.
	115	type Linux struct {
	116	// UIDMapping specifies user mappings for supporting user namespaces on Linux.
	117	UIDMappings []IDMapping `json:"uidMappings,omitempty"`
	118	// GIDMapping specifies group mappings for supporting user namespaces on Linux.
	119	GIDMappings []IDMapping `json:"gidMappings,omitempty"`
	120	// Sysctl are a set of key value pairs that are set for the container on start
	121	Sysctl map[string]string `json:"sysctl,omitempty"`
	122	// Resources contain cgroup information for handling resource constraints
	123	// for the container
	124	Resources *Resources `json:"resources,omitempty"`
	125	// CgroupsPath specifies the path to cgroups that are created and/or joined by the container.
	126	// The path is expected to be relative to the cgroups mountpoint.
	127	// If resources are specified, the cgroups at CgroupsPath will be updated based on resources.
	128	CgroupsPath *string `json:"cgroupsPath,omitempty"`
	129	// Namespaces contains the namespaces that are created and/or joined by the container
	130	Namespaces []Namespace `json:"namespaces"`
	131	// Devices are a list of device nodes that are created for the container
	132	Devices []Device `json:"devices"`
	133	// Seccomp specifies the seccomp security settings for the container.
	134	Seccomp *Seccomp `json:"seccomp,omitempty"`
	135	// RootfsPropagation is the rootfs mount propagation mode for the container.
	136	RootfsPropagation string `json:"rootfsPropagation,omitempty"`
	137	}
	138
	139	// Namespace is the configuration for a Linux namespace
	140	type Namespace struct {
	141	// Type is the type of Linux namespace
	142	Type NamespaceType `json:"type"`
	143	// Path is a path to an existing namespace persisted on disk that can be joined
	144	// and is of the same type
	145	Path string `json:"path,omitempty"`
	146	}
	147
	148	// NamespaceType is one of the Linux namespaces
	149	type NamespaceType string
	150
	151	const (
	152	// PIDNamespace for isolating process IDs
	153	PIDNamespace NamespaceType = "pid"
	154	// NetworkNamespace for isolating network devices, stacks, ports, etc
	155	NetworkNamespace = "network"
	156	// MountNamespace for isolating mount points
	157	MountNamespace = "mount"
	158	// IPCNamespace for isolating System V IPC, POSIX message queues
	159	IPCNamespace = "ipc"
	160	// UTSNamespace for isolating hostname and NIS domain name
	161	UTSNamespace = "uts"
	162	// UserNamespace for isolating user and group IDs
	163	UserNamespace = "user"
	164	)
	165
	166	// IDMapping specifies UID/GID mappings
	167	type IDMapping struct {
	168	// HostID is the UID/GID of the host user or group
	169	HostID uint32 `json:"hostID"`
	170	// ContainerID is the UID/GID of the container's user or group
	171	ContainerID uint32 `json:"containerID"`
	172	// Size is the length of the range of IDs mapped between the two namespaces
	173	Size uint32 `json:"size"`
	174	}
	175
	176	// Rlimit type and restrictions
	177	type Rlimit struct {
	178	// Type of the rlimit to set
	179	Type string `json:"type"`
	180	// Hard is the hard limit for the specified type
	181	Hard uint64 `json:"hard"`
	182	// Soft is the soft limit for the specified type
	183	Soft uint64 `json:"soft"`
	184	}
	185
	186	// HugepageLimit structure corresponds to limiting kernel hugepages
	187	type HugepageLimit struct {
	188	// Pagesize is the hugepage size
	189	Pagesize *string `json:"pageSize,omitempty"`
	190	// Limit is the limit of "hugepagesize" hugetlb usage
	191	Limit *uint64 `json:"limit,omitempty"`
	192	}
	193
	194	// InterfacePriority for network interfaces
	195	type InterfacePriority struct {
	196	// Name is the name of the network interface
	197	Name string `json:"name"`
	198	// Priority for the interface
	199	Priority uint32 `json:"priority"`
	200	}
	201
	202	// blockIODevice holds major:minor format supported in blkio cgroup
	203	type blockIODevice struct {
	204	// Major is the device's major number.
	205	Major int64 `json:"major"`
	206	// Minor is the device's minor number.
	207	Minor int64 `json:"minor"`
	208	}
	209
	210	// WeightDevice struct holds a `major:minor weight` pair for blkioWeightDevice
	211	type WeightDevice struct {
	212	blockIODevice
	213	// Weight is the bandwidth rate for the device, range is from 10 to 1000
	214	Weight *uint16 `json:"weight,omitempty"`
	215	// 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
	216	LeafWeight *uint16 `json:"leafWeight,omitempty"`
	217	}
	218
	219	// ThrottleDevice struct holds a `major:minor rate_per_second` pair
	220	type ThrottleDevice struct {
	221	blockIODevice
	222	// Rate is the IO rate limit per cgroup per device
	223	Rate *uint64 `json:"rate,omitempty"`
	224	}
	225
	226	// BlockIO for Linux cgroup 'blkio' resource management
	227	type BlockIO struct {
	228	// Specifies per cgroup weight, range is from 10 to 1000
	229	Weight *uint16 `json:"blkioWeight,omitempty"`
	230	// Specifies tasks' weight in the given cgroup while competing with the cgroup's child cgroups, range is from 10 to 1000, CFQ scheduler only
	231	LeafWeight *uint16 `json:"blkioLeafWeight,omitempty"`
	232	// Weight per cgroup per device, can override BlkioWeight
	233	WeightDevice []WeightDevice `json:"blkioWeightDevice,omitempty"`
	234	// IO read rate limit per cgroup per device, bytes per second
	235	ThrottleReadBpsDevice []ThrottleDevice `json:"blkioThrottleReadBpsDevice,omitempty"`
	236	// IO write rate limit per cgroup per device, bytes per second
	237	ThrottleWriteBpsDevice []ThrottleDevice `json:"blkioThrottleWriteBpsDevice,omitempty"`
	238	// IO read rate limit per cgroup per device, IO per second
	239	ThrottleReadIOPSDevice []ThrottleDevice `json:"blkioThrottleReadIOPSDevice,omitempty"`
	240	// IO write rate limit per cgroup per device, IO per second
	241	ThrottleWriteIOPSDevice []ThrottleDevice `json:"blkioThrottleWriteIOPSDevice,omitempty"`
	242	}
	243
	244	// Memory for Linux cgroup 'memory' resource management
	245	type Memory struct {
	246	// Memory limit (in bytes).
	247	Limit *uint64 `json:"limit,omitempty"`
	248	// Memory reservation or soft_limit (in bytes).
	249	Reservation *uint64 `json:"reservation,omitempty"`
	250	// Total memory limit (memory + swap).
	251	Swap *uint64 `json:"swap,omitempty"`
	252	// Kernel memory limit (in bytes).
	253	Kernel *uint64 `json:"kernel,omitempty"`
	254	// Kernel memory limit for tcp (in bytes)
	255	KernelTCP *uint64 `json:"kernelTCP"`
	256	// How aggressive the kernel will swap memory pages. Range from 0 to 100.
	257	Swappiness *uint64 `json:"swappiness,omitempty"`
	258	}
	259
	260	// CPU for Linux cgroup 'cpu' resource management
	261	type CPU struct {
	262	// CPU shares (relative weight (ratio) vs. other cgroups with cpu shares).
	263	Shares *uint64 `json:"shares,omitempty"`
	264	// CPU hardcap limit (in usecs). Allowed cpu time in a given period.
	265	Quota *uint64 `json:"quota,omitempty"`
	266	// CPU period to be used for hardcapping (in usecs).
	267	Period *uint64 `json:"period,omitempty"`
	268	// How much time realtime scheduling may use (in usecs).
	269	RealtimeRuntime *uint64 `json:"realtimeRuntime,omitempty"`
	270	// CPU period to be used for realtime scheduling (in usecs).
	271	RealtimePeriod *uint64 `json:"realtimePeriod,omitempty"`
	272	// CPUs to use within the cpuset. Default is to use any CPU available.
	273	Cpus *string `json:"cpus,omitempty"`
	274	// List of memory nodes in the cpuset. Default is to use any available memory node.
	275	Mems *string `json:"mems,omitempty"`
	276	}
	277
	278	// Pids for Linux cgroup 'pids' resource management (Linux 4.3)
	279	type Pids struct {
	280	// Maximum number of PIDs. Default is "no limit".
	281	Limit *int64 `json:"limit,omitempty"`
	282	}
	283
	284	// Network identification and priority configuration
	285	type Network struct {
	286	// Set class identifier for container's network packets
	287	ClassID *uint32 `json:"classID"`
	288	// Set priority of network traffic for container
	289	Priorities []InterfacePriority `json:"priorities,omitempty"`
	290	}
	291
	292	// Resources has container runtime resource constraints
	293	type Resources struct {
	294	// Devices are a list of device rules for the whitelist controller
	295	Devices []DeviceCgroup `json:"devices"`
	296	// DisableOOMKiller disables the OOM killer for out of memory conditions
	297	DisableOOMKiller *bool `json:"disableOOMKiller,omitempty"`
	298	// Specify an oom_score_adj for the container.
	299	OOMScoreAdj *int `json:"oomScoreAdj,omitempty"`
	300	// Memory restriction configuration
	301	Memory *Memory `json:"memory,omitempty"`
	302	// CPU resource restriction configuration
	303	CPU *CPU `json:"cpu,omitempty"`
	304	// Task resource restriction configuration.
	305	Pids *Pids `json:"pids,omitempty"`
	306	// BlockIO restriction configuration
	307	BlockIO *BlockIO `json:"blockIO,omitempty"`
	308	// Hugetlb limit (in bytes)
	309	HugepageLimits []HugepageLimit `json:"hugepageLimits,omitempty"`
	310	// Network restriction configuration
	311	Network *Network `json:"network,omitempty"`
	312	}
	313
	314	// Device represents the mknod information for a Linux special device file
	315	type Device struct {
	316	// Path to the device.
	317	Path string `json:"path"`
	318	// Device type, block, char, etc.
	319	Type string `json:"type"`
	320	// Major is the device's major number.
	321	Major int64 `json:"major"`
	322	// Minor is the device's minor number.
	323	Minor int64 `json:"minor"`
	324	// FileMode permission bits for the device.
	325	FileMode *os.FileMode `json:"fileMode,omitempty"`
	326	// UID of the device.
	327	UID *uint32 `json:"uid,omitempty"`
	328	// Gid of the device.
	329	GID *uint32 `json:"gid,omitempty"`
	330	}
	331
	332	// DeviceCgroup represents a device rule for the whitelist controller
	333	type DeviceCgroup struct {
	334	// Allow or deny
	335	Allow bool `json:"allow"`
	336	// Device type, block, char, etc.
	337	Type *string `json:"type,omitempty"`
	338	// Major is the device's major number.
	339	Major *int64 `json:"major,omitempty"`
	340	// Minor is the device's minor number.
	341	Minor *int64 `json:"minor,omitempty"`
	342	// Cgroup access permissions format, rwm.
	343	Access *string `json:"access,omitempty"`
	344	}
	345
	346	// Seccomp represents syscall restrictions
	347	type Seccomp struct {
	348	DefaultAction Action `json:"defaultAction"`
	349	Architectures []Arch `json:"architectures"`
	350	Syscalls []Syscall `json:"syscalls,omitempty"`
	351	}
	352
	353	// Arch used for additional architectures
	354	type Arch string
	355
	356	// Additional architectures permitted to be used for system calls
	357	// By default only the native architecture of the kernel is permitted
	358	const (
	359	ArchX86 Arch = "SCMP_ARCH_X86"
	360	ArchX86_64 Arch = "SCMP_ARCH_X86_64"
	361	ArchX32 Arch = "SCMP_ARCH_X32"
	362	ArchARM Arch = "SCMP_ARCH_ARM"
	363	ArchAARCH64 Arch = "SCMP_ARCH_AARCH64"
	364	ArchMIPS Arch = "SCMP_ARCH_MIPS"
	365	ArchMIPS64 Arch = "SCMP_ARCH_MIPS64"
	366	ArchMIPS64N32 Arch = "SCMP_ARCH_MIPS64N32"
	367	ArchMIPSEL Arch = "SCMP_ARCH_MIPSEL"
	368	ArchMIPSEL64 Arch = "SCMP_ARCH_MIPSEL64"
	369	ArchMIPSEL64N32 Arch = "SCMP_ARCH_MIPSEL64N32"
	370	)
	371
	372	// Action taken upon Seccomp rule match
	373	type Action string
	374
	375	// Define actions for Seccomp rules
	376	const (
	377	ActKill Action = "SCMP_ACT_KILL"
	378	ActTrap Action = "SCMP_ACT_TRAP"
	379	ActErrno Action = "SCMP_ACT_ERRNO"
	380	ActTrace Action = "SCMP_ACT_TRACE"
	381	ActAllow Action = "SCMP_ACT_ALLOW"
	382	)
	383
	384	// Operator used to match syscall arguments in Seccomp
	385	type Operator string
	386
	387	// Define operators for syscall arguments in Seccomp
	388	const (
	389	OpNotEqual Operator = "SCMP_CMP_NE"
	390	OpLessThan Operator = "SCMP_CMP_LT"
	391	OpLessEqual Operator = "SCMP_CMP_LE"
	392	OpEqualTo Operator = "SCMP_CMP_EQ"
	393	OpGreaterEqual Operator = "SCMP_CMP_GE"
	394	OpGreaterThan Operator = "SCMP_CMP_GT"
	395	OpMaskedEqual Operator = "SCMP_CMP_MASKED_EQ"
	396	)
	397
	398	// Arg used for matching specific syscall arguments in Seccomp
	399	type Arg struct {
	400	Index uint `json:"index"`
	401	Value uint64 `json:"value"`
	402	ValueTwo uint64 `json:"valueTwo"`
	403	Op Operator `json:"op"`
	404	}
	405
	406	// Syscall is used to match a syscall in Seccomp
	407	type Syscall struct {
	408	Name string `json:"name"`
	409	Action Action `json:"action"`
	410	Args []Arg `json:"args,omitempty"`
	411	}

+13

-0

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

-0

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 = 4
	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)

-16

~~state.go~~ less more

0		package specs
1
2		// State holds information about the runtime state of the container.
3		// This information will be stored in a file called `state.json`.
4		// The location of this file will be operating system specific. On Linux
5		// it will be in `/run/opencontainers/runc/<containerID>/state.json`
6		type State struct {
7		// Version is the version of the specification that is supported.
8		Version string `json:"version"`
9		// ID is the container ID
10		ID string `json:"id"`
11		// Pid is the process id for the container's main process.
12		Pid int `json:"pid"`
13		// BundlePath is the path to the container's bundle directory.
14		BundlePath string `json:"bundlePath"`
15		}

-0

style.md less more

12	12	## Optional settings should have pointer Go types
13	13
14	14	So we have a consistent way to identify unset values ([source][optional-pointer]).
	15	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]).
	16
15	17
16	18	[capabilities]: config-linux.md#capabilities
17	19	[class-id]: config-linux.md#network
18	20	[integer-over-hex]: https://github.com/opencontainers/specs/pull/267#discussion_r48360013
19	21	[keep-prefix]: https://github.com/opencontainers/specs/pull/159#issuecomment-138728337
	22	[no-pointer-for-boolean]: https://github.com/opencontainers/specs/pull/290#discussion_r50296396
	23	[no-pointer-for-slices]: https://github.com/opencontainers/specs/pull/316/files#r50782982
20	24	[optional-pointer]: https://github.com/opencontainers/specs/pull/233#discussion_r47829711
	25	[pointer-when-updates-require-changes]: https://github.com/opencontainers/specs/pull/317/files#r50932706

-18

~~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 = 3
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)