Commit e7813e03d7adfabfd76edb60016a90842795bde6 - golang-github-opencontainers-specs

Imported Upstream version 0.0~git20150829.0.e9cb564 aviau 8 years ago

13 changed file(s) with 601 addition(s) and 570 deletion(s). Raw diff Collapse all Expand all

-6

README.md less more

56	56	Development happens on GitHub for the spec.
57	57	Issues are used for bugs and actionable items and longer discussions can happen on the [mailing list](#mailing-list).
58	58
59		The specification and code is licensed under the Apache 2.0 license found in the `LICENSE` file of this repository.
	59	The specification and code is licensed under the Apache 2.0 license found in the `LICENSE` file of this repository.
60	60
61	61	## Discuss your design
62	62

72	72	## Weekly Call
73	73
74	74	The contributors and maintainers of the project have a weekly meeting Wednesdays at 10:00 AM PST.
75		The link to the call will be posted on the mailing list each week along with set topics for discussion.
76		Everyone is welcome to participate in the call, although there can only be speaking members on the Google Hangout.
77		Participants who don't get a speaking slot can watch the live broadcast on [this YouTube channel][youtube] and post feedback and questions on [the IRC channel](#irc).
78		Everyone is welcome to propose additional topics, suggest other agenda alterations, or request a speaking slot via the [mailing list](#mailing-list).
	75	Everyone is welcome to participate in the [BlueJeans call][BlueJeans].
	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.
79	77	Minutes for the call will be posted to the [mailing list](#mailing-list) for those who are unable to join the call.
80	78
81	79	## Mailing List

147	145
148	146	You can add the sign off when creating the git commit via `git commit -s`.
149	147
150		[youtube]: https://www.youtube.com/channel/UC1wmLdEYmwWcsFg7bt1s5nw
	148	[BlueJeans]: https://bluejeans.com/1771332256/

+10

-10

bundle.md less more

11	11
12	12	# Directory layout
13	13
14		A Standard Container bundle is a directory containing all the content needed to load and run a container. This includes its configuration file (`config.json`) and content directories. The main property of this directory layout is that it can be moved as a unit to another machine and run the same container.
	14	A Standard Container bundle is a directory containing all the content needed to load and run a container.
	15	This includes two configuration files `config.json` and `runtime.json`, and a rootfs directory.
	16	The `config.json` file contains settings that are host independent and application specific such as security permissions, environment variables and arguments.
	17	The `runtime.json` file contains settings that are host specific such as memory limits, local device access and mount points.
	18	The goal is that the bundle can be moved as a unit to another machine and run the same application if `runtime.json` is removed or reconfigured.
15	19
16	20	The syntax and semantics for `config.json` are described in [this specification](config.md).
17	21
18		One or more content directories may be adjacent to the configuration file. This must include at least the root filesystem (referenced in the configuration file by the root field) and may include other related content (signatures, other configs, etc.). The interpretation of these resources is specified in the configuration. The names of the directories may be arbitrary, but users should consider using conventional names as in the example below.
	22	A single `rootfs` directory MUST be in the same directory as the `config.json`.
	23	The names of the directories may be arbitrary, but users should consider using conventional names as in the example below.
19	24
20	25	```
21		/
22		!
23		--- config.json
24		!
25		--- rootfs
26		!
27		--- signatures
	26	config.json
	27	runtime.json
	28	rootfs/
28	29	```
29

-203

config-linux.md less more

4	4	Additional information is needed for Linux over the [default spec configuration](config.md)
5	5	in order to configure these various kernel features.
6	6
7		## Linux namespaces
8
9		A namespace wraps a global system resource in an abstraction that makes it
10		appear to the processes within the namespace that they have their own isolated
11		instance of the global resource. Changes to the global resource are visible to
12		other processes that are members of the namespace, but are invisible to other
13		processes. For more information, see [the man page](http://man7.org/linux/man-pages/man7/namespaces.7.html)
14
15		Namespaces are specified in the spec as an array of entries. Each entry has a
16		type field with possible values described below and an optional path element.
17		If a path is specified, that particular file is used to join that type of namespace.
18
19		```json
20		"namespaces": [
21		{
22		"type": "pid",
23		"path": "/proc/1234/ns/pid"
24		},
25		{
26		"type": "net",
27		"path": "/var/run/netns/neta"
28		},
29		{
30		"type": "mnt",
31		},
32		{
33		"type": "ipc",
34		},
35		{
36		"type": "uts",
37		},
38		{
39		"type": "user",
40		},
41		]
42		```
43
44		#### Namespace types
45
46		* pid processes inside the container will only be able to see other processes inside the same container.
47		* network the container will have it's own network stack.
48		* mnt the container will have an isolated mount table.
49		* ipc processes inside the container will only be able to communicate to other processes inside the same
50		container via system level IPC.
51		* uts the container will be able to have it's own hostname and domain name.
52		* user the container will be able to remap user and group IDs from the host to local users and groups
53		within the container.
54
55		### Access to devices
56
57		Devices is an array specifying the list of devices to be created in the container.
58		Next parameters can be specified:
59
60		* type - type of device: 'c', 'b', 'u' or 'p'. More info in `man mknod`
61		* path - full path to device inside container
62		* major, minor - major, minor numbers for device. More info in `man mknod`.
63		There is special value: `-1`, which means `*` for `device`
64		cgroup setup.
65		* permissions - cgroup permissions for device. A composition of 'r'
66		(read), 'w' (write), and 'm' (mknod).
67		* fileMode - file mode for device file
68		* uid - uid of device owner
69		* gid - gid of device owner
70
71		```json
72		"devices": [
73		{
74		"path": "/dev/random",
75		"type": "c",
76		"major": 1,
77		"minor": 8,
78		"permissions": "rwm",
79		"fileMode": 0666,
80		"uid": 0,
81		"gid": 0
82		},
83		{
84		"path": "/dev/urandom",
85		"type": "c",
86		"major": 1,
87		"minor": 9,
88		"permissions": "rwm",
89		"fileMode": 0666,
90		"uid": 0,
91		"gid": 0
92		},
93		{
94		"path": "/dev/null",
95		"type": "c",
96		"major": 1,
97		"minor": 3,
98		"permissions": "rwm",
99		"fileMode": 0666,
100		"uid": 0,
101		"gid": 0
102		},
103		{
104		"path": "/dev/zero",
105		"type": "c",
106		"major": 1,
107		"minor": 5,
108		"permissions": "rwm",
109		"fileMode": 0666,
110		"uid": 0,
111		"gid": 0
112		},
113		{
114		"path": "/dev/tty",
115		"type": "c",
116		"major": 5,
117		"minor": 0,
118		"permissions": "rwm",
119		"fileMode": 0666,
120		"uid": 0,
121		"gid": 0
122		},
123		{
124		"path": "/dev/full",
125		"type": "c",
126		"major": 1,
127		"minor": 7,
128		"permissions": "rwm",
129		"fileMode": 0666,
130		"uid": 0,
131		"gid": 0
132		}
133		]
134		```
135
136		## Linux control groups
137
138		Also known as cgroups, they are used to restrict resource usage for a container and handle
139		device access. cgroups provide controls to restrict cpu, memory, IO, and network for
140		the container. For more information, see the [kernel cgroups documentation](https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt)
141
142		## Linux capabilities
	7	## Capabilities
143	8
144	9	Capabilities is an array that specifies Linux capabilities that can be provided to the process
145	10	inside the container. Valid values are the string after `CAP_` for capabilities defined

153	18	]
154	19	```
155	20
156		## Linux sysctl
	21	## Rootfs Mount Propagation
157	22
158		sysctl allows kernel parameters to be modified at runtime for the container.
159		For more information, see [the man page](http://man7.org/linux/man-pages/man8/sysctl.8.html)
	23	rootfsPropagation sets the rootfs's mount propagation. Its value is either slave, private, or shared. [The kernel doc](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) has more information about mount propagation.
160	24
161	25	```json
162		"sysctl": {
163		"net.ipv4.ip_forward": "1",
164		"net.core.somaxconn": "256"
165		}
	26	"rootfsPropagation": "slave",
166	27	```
167	28
168		## Linux rlimits
169
170		```json
171		"rlimits": [
172		{
173		"type": "RLIMIT_NPROC",
174		"soft": 1024,
175		"hard": 102400
176		}
177		]
178		```
179
180		rlimits allow setting resource limits. The type is from the values defined in [the man page](http://man7.org/linux/man-pages/man2/setrlimit.2.html). The kernel enforces the soft limit for a resource while the hard limit acts as a ceiling for that value that could be set by an unprivileged process.
181
182		## Linux user namespace mappings
	29	## User namespace mappings
183	30
184	31	```json
185	32	"uidMappings": [

198	45	]
199	46	```
200	47
201		uid/gid mappings describe the user namespace mappings from the host to the container. 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. The Linux kernel has a limit of 5 such mappings that can be specified.
202
203		## Rootfs Mount Propagation
204		rootfsPropagation sets the rootfs's mount propagation. Its value is either slave, private, or shared. [The kernel doc](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) has more information about mount propagation.
205
206		```json
207		"rootfsPropagation": "slave",
208		```
209
210		## Selinux process label
211
212		Selinux process label specifies the label with which the processes in a container are run.
213		For more information about SELinux, see [Selinux documentation](http://selinuxproject.org/page/Main_Page)
214		```json
215		"selinuxProcessLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675"
216		```
217
218		## Apparmor profile
219
220		Apparmor profile specifies the name of the apparmor profile that will be used for the container.
221		For more information about Apparmor, see [Apparmor documentation](https://wiki.ubuntu.com/AppArmor)
222
223		```json
224		"apparmorProfile": "acme_secure_profile"
225		```
226
227		## Seccomp
228
229		Seccomp provides application sandboxing mechanism in the Linux kernel.
230		Seccomp configuration allows one to configure actions to take for matched syscalls and furthermore also allows
231		matching on values passed as arguments to syscalls.
232		For more information about Seccomp, see [Seccomp kernel documentation](https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt)
233		The actions and operators are strings that match the definitions in seccomp.h from [libseccomp](https://github.com/seccomp/libseccomp) and are translated to corresponding values.
234
235		```json
236		"seccomp": {
237		"defaultAction": "SCMP_ACT_ALLOW",
238		"syscalls": [
239		{
240		"name": "getcwd",
241		"action": "SCMP_ACT_ERRNO"
242		}
243		]
244		}
245		```
	48	uid/gid mappings describe the user namespace mappings from the host to the container.
	49	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.
	50	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.
	51	There is a limit of 5 mappings which is the Linux kernel hard limit.

+58

-0

config.go less more

	0	package specs
	1
	2	// Spec is the base configuration for the container. It specifies platform
	3	// independent configuration.
	4	type Spec struct {
	5	// Version is the version of the specification that is supported.
	6	Version string `json:"version"`
	7	// Platform is the host information for OS and Arch.
	8	Platform Platform `json:"platform"`
	9	// Process is the container's main process.
	10	Process Process `json:"process"`
	11	// Root is the root information for the container's filesystem.
	12	Root Root `json:"root"`
	13	// Hostname is the container's host name.
	14	Hostname string `json:"hostname"`
	15	// Mounts profile configuration for adding mounts to the container's filesystem.
	16	MountPoints []MountPoint `json:"mounts"`
	17	}
	18
	19	// Process contains information to start a specific application inside the container.
	20	type Process struct {
	21	// Terminal creates an interactive terminal for the container.
	22	Terminal bool `json:"terminal"`
	23	// User specifies user information for the process.
	24	User User `json:"user"`
	25	// Args specifies the binary and arguments for the application to execute.
	26	Args []string `json:"args"`
	27	// Env populates the process environment for the process.
	28	Env []string `json:"env"`
	29	// Cwd is the current working directory for the process and must be
	30	// relative to the container's root.
	31	Cwd string `json:"cwd"`
	32	}
	33
	34	// Root contains information about the container's root filesystem on the host.
	35	type Root struct {
	36	// Path is the absolute path to the container's root filesystem.
	37	Path string `json:"path"`
	38	// Readonly makes the root filesystem for the container readonly before the process is executed.
	39	Readonly bool `json:"readonly"`
	40	}
	41
	42	// Platform specifies OS and arch information for the host system that the container
	43	// is created for.
	44	type Platform struct {
	45	// OS is the operating system.
	46	OS string `json:"os"`
	47	// Arch is the architecture
	48	Arch string `json:"arch"`
	49	}
	50
	51	// MountPoint describes a directory that may be fullfilled by a mount in the runtime.json.
	52	type MountPoint struct {
	53	// Name is a unique descriptive identifier for this mount point.
	54	Name string `json:"name"`
	55	// Path specifies the path of the mount. The path and child directories MUST exist, a runtime MUST NOT create directories automatically to a mount point.
	56	Path string `json:"path"`
	57	}

-58

config.md less more

0	0	# Configuration file
1	1
2		The container’s top-level directory MUST contain a configuration file called `config.json`.
	2	The container's top-level directory MUST contain a configuration file called `config.json`.
3	3	For now the canonical schema is defined in [spec.go](spec.go) and [spec_linux.go](spec_linux.go), but this will be moved to a formal JSON schema over time.
4	4
5	5	The configuration file contains metadata necessary to implement standard operations against the container.

33	33	}
34	34	```
35	35
36		## Mount Configuration
37
38		Additional filesystems can be declared as "mounts", specified in the mounts array. The parameters are similar to the ones in Linux mount system call. [http://linux.die.net/man/2/mount](http://linux.die.net/man/2/mount)
39
40		* 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
41		* 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)
42		* destination (string, required) where the source filesystem is mounted relative to the container rootfs.
43		* options (string, optional) in the fstab format [https://wiki.archlinux.org/index.php/Fstab](https://wiki.archlinux.org/index.php/Fstab).
44
45		Example (Linux)
46
47		```json
48		"mounts": [
49		{
50		"type": "proc",
51		"source": "proc",
52		"destination": "/proc",
53		"options": ""
54		},
55		{
56		"type": "tmpfs",
57		"source": "tmpfs",
58		"destination": "/dev",
59		"options": "nosuid,strictatime,mode=755,size=65536k"
60		},
61		{
62		"type": "devpts",
63		"source": "devpts",
64		"destination": "/dev/pts",
65		"options": "nosuid,noexec,newinstance,ptmxmode=0666,mode=0620,gid=5"
66		},
67		{
68		"type": "bind",
69		"source": "/volumes/testing",
70		"destination": "/data",
71		"options": "rbind,rw"
72		}
73		]
74		```
75
76		Example (Windows)
77
78		```json
79		"mounts": [
80		{
81		"type": "ntfs",
82		"source": "\\\\?\\Volume\\{2eca078d-5cbc-43d3-aff8-7e8511f60d0e}\\",
83		"destination": "C:\\Users\\crosbymichael\\My Fancy Mount Point\\",
84		"options": ""
85		}
86		]
87		```
88
89		See links for details about [mountvol](http://ss64.com/nt/mountvol.html) and [SetVolumeMountPoint](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365561(v=vs.85).aspx) in Windows.
90
91	36	## Process configuration
92	37
93	38	* terminal (bool, optional) specifies whether you want a terminal attached to that process. Defaults to false.

110	55	"user": {
111	56	"uid": 1,
112	57	"gid": 1,
113		"additionalGids": []
	58	"additionalGids": [5, 6]
114	59	},
115	60	"env": [
116	61	"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
117	62	"TERM=xterm"
118	63	],
119		"cwd": "",
	64	"cwd": "/root",
120	65	"args": [
121	66	"sh"
122	67	]

+29

-0

config_linux.go less more

	0	// +build linux
	1
	2	package specs
	3
	4	// LinuxSpec is the full specification for linux containers.
	5	type LinuxSpec struct {
	6	Spec
	7	// Linux is platform specific configuration for linux based containers.
	8	Linux Linux `json:"linux"`
	9	}
	10
	11	// Linux contains platform specific configuration for linux based containers.
	12	type Linux struct {
	13	// Capabilities are linux capabilities that are kept for the container.
	14	Capabilities []string `json:"capabilities"`
	15	// RootfsPropagation is the rootfs mount propagation mode for the container.
	16	RootfsPropagation string `json:"rootfsPropagation"`
	17	}
	18
	19	// User specifies linux specific user and group information for the container's
	20	// main process.
	21	type User struct {
	22	// Uid is the user id.
	23	Uid int32 `json:"uid"`
	24	// Gid is the group id.
	25	Gid int32 `json:"gid"`
	26	// AdditionalGids are additional group ids set for the container's process.
	27	AdditionalGids []int32 `json:"additionalGids"`
	28	}

+195

-0

runtime-config-linux.md less more

	0	## Namespaces
	1
	2	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.
	3	Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes.
	4	For more information, see [the man page](http://man7.org/linux/man-pages/man7/namespaces.7.html).
	5
	6	Namespaces are specified in the spec as an array of entries.
	7	Each entry has a type field with possible values described below and an optional path element.
	8	If a path is specified, that particular file is used to join that type of namespace.
	9
	10	```json
	11	"namespaces": [
	12	{
	13	"type": "pid",
	14	"path": "/proc/1234/ns/pid"
	15	},
	16	{
	17	"type": "net",
	18	"path": "/var/run/netns/neta"
	19	},
	20	{
	21	"type": "mnt",
	22	},
	23	{
	24	"type": "ipc",
	25	},
	26	{
	27	"type": "uts",
	28	},
	29	{
	30	"type": "user",
	31	},
	32	]
	33	```
	34
	35	#### Namespace types
	36
	37	* pid processes inside the container will only be able to see other processes inside the same container.
	38	* network the container will have its own network stack.
	39	* mnt the container will have an isolated mount table.
	40	* ipc processes inside the container will only be able to communicate to other processes inside the same
	41	container via system level IPC.
	42	* uts the container will be able to have its own hostname and domain name.
	43	* user the container will be able to remap user and group IDs from the host to local users and groups
	44	within the container.
	45
	46	### Access to devices
	47
	48	Devices is an array specifying the list of devices to be created in the container.
	49	Next parameters can be specified:
	50
	51	* type - type of device: 'c', 'b', 'u' or 'p'. More info in `man mknod`
	52	* path - full path to device inside container
	53	* major, minor - major, minor numbers for device. More info in `man mknod`.
	54	There is special value: `-1`, which means `*` for `device`
	55	cgroup setup.
	56	* permissions - cgroup permissions for device. A composition of 'r'
	57	(read), 'w' (write), and 'm' (mknod).
	58	* fileMode - file mode for device file
	59	* uid - uid of device owner
	60	* gid - gid of device owner
	61
	62	```json
	63	"devices": [
	64	{
	65	"path": "/dev/random",
	66	"type": "c",
	67	"major": 1,
	68	"minor": 8,
	69	"permissions": "rwm",
	70	"fileMode": 0666,
	71	"uid": 0,
	72	"gid": 0
	73	},
	74	{
	75	"path": "/dev/urandom",
	76	"type": "c",
	77	"major": 1,
	78	"minor": 9,
	79	"permissions": "rwm",
	80	"fileMode": 0666,
	81	"uid": 0,
	82	"gid": 0
	83	},
	84	{
	85	"path": "/dev/null",
	86	"type": "c",
	87	"major": 1,
	88	"minor": 3,
	89	"permissions": "rwm",
	90	"fileMode": 0666,
	91	"uid": 0,
	92	"gid": 0
	93	},
	94	{
	95	"path": "/dev/zero",
	96	"type": "c",
	97	"major": 1,
	98	"minor": 5,
	99	"permissions": "rwm",
	100	"fileMode": 0666,
	101	"uid": 0,
	102	"gid": 0
	103	},
	104	{
	105	"path": "/dev/tty",
	106	"type": "c",
	107	"major": 5,
	108	"minor": 0,
	109	"permissions": "rwm",
	110	"fileMode": 0666,
	111	"uid": 0,
	112	"gid": 0
	113	},
	114	{
	115	"path": "/dev/full",
	116	"type": "c",
	117	"major": 1,
	118	"minor": 7,
	119	"permissions": "rwm",
	120	"fileMode": 0666,
	121	"uid": 0,
	122	"gid": 0
	123	}
	124	]
	125	```
	126
	127	## Control groups
	128
	129	Also known as cgroups, they are used to restrict resource usage for a container and handle
	130	device access. cgroups provide controls to restrict cpu, memory, IO, and network for
	131	the container. For more information, see the [kernel cgroups documentation](https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt).
	132
	133	## Sysctl
	134
	135	sysctl allows kernel parameters to be modified at runtime for the container.
	136	For more information, see [the man page](http://man7.org/linux/man-pages/man8/sysctl.8.html)
	137
	138	```json
	139	"sysctl": {
	140	"net.ipv4.ip_forward": "1",
	141	"net.core.somaxconn": "256"
	142	}
	143	```
	144
	145	## Rlimits
	146
	147	```json
	148	"rlimits": [
	149	{
	150	"type": "RLIMIT_NPROC",
	151	"soft": 1024,
	152	"hard": 102400
	153	}
	154	]
	155	```
	156
	157	rlimits allow setting resource limits. The type is from the values defined in [the man page](http://man7.org/linux/man-pages/man2/setrlimit.2.html). The kernel enforces the soft limit for a resource while the hard limit acts as a ceiling for that value that could be set by an unprivileged process.
	158
	159	## SELinux process label
	160
	161	SELinux process label specifies the label with which the processes in a container are run.
	162	For more information about SELinux, see [Selinux documentation](http://selinuxproject.org/page/Main_Page)
	163	```json
	164	"selinuxProcessLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675"
	165	```
	166
	167	## Apparmor profile
	168
	169	Apparmor profile specifies the name of the apparmor profile that will be used for the container.
	170	For more information about Apparmor, see [Apparmor documentation](https://wiki.ubuntu.com/AppArmor)
	171
	172	```json
	173	"apparmorProfile": "acme_secure_profile"
	174	```
	175
	176	## seccomp
	177
	178	Seccomp provides application sandboxing mechanism in the Linux kernel.
	179	Seccomp configuration allows one to configure actions to take for matched syscalls and furthermore also allows
	180	matching on values passed as arguments to syscalls.
	181	For more information about Seccomp, see [Seccomp kernel documentation](https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt)
	182	The actions and operators are strings that match the definitions in seccomp.h from [libseccomp](https://github.com/seccomp/libseccomp) and are translated to corresponding values.
	183
	184	```json
	185	"seccomp": {
	186	"defaultAction": "SCMP_ACT_ALLOW",
	187	"syscalls": [
	188	{
	189	"name": "getcwd",
	190	"action": "SCMP_ACT_ERRNO"
	191	}
	192	]
	193	}
	194	```

+54

-0

runtime-config.md less more

	0	## Mount Configuration
	1
	2	Additional filesystems can be declared as "mounts", specified in the mounts array. The parameters are similar to the ones in Linux mount system call. [http://linux.die.net/man/2/mount](http://linux.die.net/man/2/mount)
	3
	4	* 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
	5	* 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)
	6	* destination (string, required) where the source filesystem is mounted relative to the container rootfs.
	7	* options (list of strings, optional) in the fstab format [https://wiki.archlinux.org/index.php/Fstab](https://wiki.archlinux.org/index.php/Fstab).
	8
	9	Example (Linux)
	10
	11	```json
	12	"mounts": [
	13	{
	14	"type": "proc",
	15	"source": "proc",
	16	"destination": "/proc",
	17	"options": []
	18	},
	19	{
	20	"type": "tmpfs",
	21	"source": "tmpfs",
	22	"destination": "/dev",
	23	"options": ["nosuid","strictatime","mode=755","size=65536k"]
	24	},
	25	{
	26	"type": "devpts",
	27	"source": "devpts",
	28	"destination": "/dev/pts",
	29	"options": ["nosuid","noexec","newinstance","ptmxmode=0666","mode=0620","gid=5"]
	30	},
	31	{
	32	"type": "bind",
	33	"source": "/volumes/testing",
	34	"destination": "/data",
	35	"options": ["rbind","rw"]
	36	}
	37	]
	38	```
	39
	40	Example (Windows)
	41
	42	```json
	43	"mounts": [
	44	{
	45	"type": "ntfs",
	46	"source": "\\\\?\\Volume\\{2eca078d-5cbc-43d3-aff8-7e8511f60d0e}\\",
	47	"destination": "C:\\Users\\crosbymichael\\My Fancy Mount Point\\",
	48	"options": []
	49	}
	50	]
	51	```
	52
	53	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.

-0

runtime-linux.md less more

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

+36

-0

runtime_config.go less more

	0	package specs
	1
	2	type RuntimeSpec struct {
	3	// Mounts profile configuration for adding mounts to the container's filesystem.
	4	Mounts []Mount `json:"mounts"`
	5	// Hooks are the commands run at various lifecycle events of the container.
	6	Hooks Hooks `json:"hooks"`
	7	}
	8
	9	// Hook specifies a command that is run at a particular event in the lifecycle of a container.
	10	type Hook struct {
	11	Path string `json:"path"`
	12	Args []string `json:"args"`
	13	Env []string `json:"env"`
	14	}
	15
	16	type Hooks struct {
	17	// Prestart is a list of hooks to be run before the container process is executed.
	18	// On Linux, they are run after the container namespaces are created.
	19	Prestart []Hook `json:"prestart"`
	20	// Poststop is a list of hooks to be run after the container process exits.
	21	Poststop []Hook `json:"poststop"`
	22	}
	23
	24	// Mount specifies a mount for a container.
	25	type Mount struct {
	26	// Type specifies the mount kind.
	27	Type string `json:"type"`
	28	// Source specifies the source path of the mount. In the case of bind mounts on
	29	// linux based systems this would be the file on the host.
	30	Source string `json:"source"`
	31	// Destination is the path where the mount will be placed relative to the container's root.
	32	Destination string `json:"destination"`
	33	// Options are fstab style mount options.
	34	Options []string `json:"options"`
	35	}

+197

-0

runtime_config_linux.go less more

	0	package specs
	1
	2	import "os"
	3
	4	// LinuxRuntimeSpec is the full specification for linux containers.
	5	type LinuxRuntimeSpec struct {
	6	RuntimeSpec
	7	// Linux is platform specific configuration for linux based containers.
	8	LinuxRuntime Linux `json:"linux"`
	9	}
	10
	11	type LinuxRuntime struct {
	12	// UidMapping specifies user mappings for supporting user namespaces on linux.
	13	UidMappings []IDMapping `json:"uidMappings"`
	14	// UidMapping specifies group mappings for supporting user namespaces on linux.
	15	GidMappings []IDMapping `json:"gidMappings"`
	16	// Rlimits specifies rlimit options to apply to the container's process.
	17	Rlimits []Rlimit `json:"rlimits"`
	18	// Sysctl are a set of key value pairs that are set for the container on start
	19	Sysctl map[string]string `json:"sysctl"`
	20	// Resources contain cgroup information for handling resource constraints
	21	// for the container
	22	Resources Resources `json:"resources"`
	23	// Namespaces contains the namespaces that are created and/or joined by the container
	24	Namespaces []Namespace `json:"namespaces"`
	25	// Devices are a list of device nodes that are created and enabled for the container
	26	Devices []Device `json:"devices"`
	27	// ApparmorProfile specified the apparmor profile for the container.
	28	ApparmorProfile string `json:"apparmorProfile"`
	29	// SelinuxProcessLabel specifies the selinux context that the container process is run as.
	30	SelinuxProcessLabel string `json:"selinuxProcessLabel"`
	31	// Seccomp specifies the seccomp security settings for the container.
	32	Seccomp Seccomp `json:"seccomp"`
	33	// RootfsPropagation is the rootfs mount propagation mode for the container
	34	RootfsPropagation string `json:"rootfsPropagation"`
	35	}
	36
	37	// Namespace is the configuration for a linux namespace.
	38	type Namespace struct {
	39	// Type is the type of Linux namespace
	40	Type string `json:"type"`
	41	// Path is a path to an existing namespace persisted on disk that can be joined
	42	// and is of the same type
	43	Path string `json:"path"`
	44	}
	45
	46	// IDMapping specifies UID/GID mappings
	47	type IDMapping struct {
	48	// HostID is the UID/GID of the host user or group
	49	HostID int32 `json:"hostID"`
	50	// ContainerID is the UID/GID of the container's user or group
	51	ContainerID int32 `json:"containerID"`
	52	// Size is the length of the range of IDs mapped between the two namespaces
	53	Size int32 `json:"size"`
	54	}
	55
	56	// Rlimit type and restrictions
	57	type Rlimit struct {
	58	// Type of the rlimit to set
	59	Type int `json:"type"`
	60	// Hard is the hard limit for the specified type
	61	Hard uint64 `json:"hard"`
	62	// Soft is the soft limit for the specified type
	63	Soft uint64 `json:"soft"`
	64	}
	65
	66	// HugepageLimit structure corresponds to limiting kernel hugepages
	67	type HugepageLimit struct {
	68	Pagesize string `json:"pageSize"`
	69	Limit int `json:"limit"`
	70	}
	71
	72	// InterfacePriority for network interfaces
	73	type InterfacePriority struct {
	74	// Name is the name of the network interface
	75	Name string `json:"name"`
	76	// Priority for the interface
	77	Priority int64 `json:"priority"`
	78	}
	79
	80	// BlockIO for Linux cgroup 'blockio' resource management
	81	type BlockIO struct {
	82	// Specifies per cgroup weight, range is from 10 to 1000
	83	Weight int64 `json:"blkioWeight"`
	84	// Weight per cgroup per device, can override BlkioWeight
	85	WeightDevice string `json:"blkioWeightDevice"`
	86	// IO read rate limit per cgroup per device, bytes per second
	87	ThrottleReadBpsDevice string `json:"blkioThrottleReadBpsDevice"`
	88	// IO write rate limit per cgroup per divice, bytes per second
	89	ThrottleWriteBpsDevice string `json:"blkioThrottleWriteBpsDevice"`
	90	// IO read rate limit per cgroup per device, IO per second
	91	ThrottleReadIOpsDevice string `json:"blkioThrottleReadIopsDevice"`
	92	// IO write rate limit per cgroup per device, IO per second
	93	ThrottleWriteIOpsDevice string `json:"blkioThrottleWriteIopsDevice"`
	94	}
	95
	96	// Memory for Linux cgroup 'memory' resource management
	97	type Memory struct {
	98	// Memory limit (in bytes)
	99	Limit int64 `json:"limit"`
	100	// Memory reservation or soft_limit (in bytes)
	101	Reservation int64 `json:"reservation"`
	102	// Total memory usage (memory + swap); set `-1' to disable swap
	103	Swap int64 `json:"swap"`
	104	// Kernel memory limit (in bytes)
	105	Kernel int64 `json:"kernel"`
	106	// How aggressive the kernel will swap memory pages. Range from 0 to 100. Set -1 to use system default
	107	Swappiness int64 `json:"swappiness"`
	108	}
	109
	110	// CPU for Linux cgroup 'cpu' resource management
	111	type CPU struct {
	112	// CPU shares (relative weight vs. other cgroups with cpu shares)
	113	Shares int64 `json:"shares"`
	114	// CPU hardcap limit (in usecs). Allowed cpu time in a given period
	115	Quota int64 `json:"quota"`
	116	// CPU period to be used for hardcapping (in usecs). 0 to use system default
	117	Period int64 `json:"period"`
	118	// How many time CPU will use in realtime scheduling (in usecs)
	119	RealtimeRuntime int64 `json:"realtimeRuntime"`
	120	// CPU period to be used for realtime scheduling (in usecs)
	121	RealtimePeriod int64 `json:"realtimePeriod"`
	122	// CPU to use within the cpuset
	123	Cpus string `json:"cpus"`
	124	// MEM to use within the cpuset
	125	Mems string `json:"mems"`
	126	}
	127
	128	// Network identification and priority configuration
	129	type Network struct {
	130	// Set class identifier for container's network packets
	131	ClassID string `json:"classId"`
	132	// Set priority of network traffic for container
	133	Priorities []InterfacePriority `json:"priorities"`
	134	}
	135
	136	// Resources has container runtime resource constraints
	137	type Resources struct {
	138	// DisableOOMKiller disables the OOM killer for out of memory conditions
	139	DisableOOMKiller bool `json:"disableOOMKiller"`
	140	// Memory restriction configuration
	141	Memory Memory `json:"memory"`
	142	// CPU resource restriction configuration
	143	CPU CPU `json:"cpu"`
	144	// BlockIO restriction configuration
	145	BlockIO BlockIO `json:"blockIO"`
	146	// Hugetlb limit (in bytes)
	147	HugepageLimits []HugepageLimit `json:"hugepageLimits"`
	148	// Network restriction configuration
	149	Network Network `json:"network"`
	150	}
	151
	152	type Device struct {
	153	// Path to the device.
	154	Path string `json:"path"`
	155	// Device type, block, char, etc.
	156	Type rune `json:"type"`
	157	// Major is the device's major number.
	158	Major int64 `json:"major"`
	159	// Minor is the device's minor number.
	160	Minor int64 `json:"minor"`
	161	// Cgroup permissions format, rwm.
	162	Permissions string `json:"permissions"`
	163	// FileMode permission bits for the device.
	164	FileMode os.FileMode `json:"fileMode"`
	165	// UID of the device.
	166	UID uint32 `json:"uid"`
	167	// Gid of the device.
	168	GID uint32 `json:"gid"`
	169	}
	170
	171	// Seccomp represents syscall restrictions
	172	type Seccomp struct {
	173	DefaultAction Action `json:"defaultAction"`
	174	Syscalls []*Syscall `json:"syscalls"`
	175	}
	176
	177	// Action taken upon Seccomp rule match
	178	type Action string
	179
	180	// Operator used to match syscall arguments in Seccomp
	181	type Operator string
	182
	183	// Arg used for matching specific syscall arguments in Seccomp
	184	type Arg struct {
	185	Index uint `json:"index"`
	186	Value uint64 `json:"value"`
	187	ValueTwo uint64 `json:"valueTwo"`
	188	Op Operator `json:"op"`
	189	}
	190
	191	// Syscall is used to match a syscall in Seccomp
	192	type Syscall struct {
	193	Name string `json:"name"`
	194	Action Action `json:"action"`
	195	Args []*Arg `json:"args"`
	196	}

-80

~~spec.go~~ less more

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

-213

~~spec_linux.go~~ less more

0		// +build linux
1
2		package specs
3
4		import "os"
5
6		// LinuxSpec is the full specification for Linux containers
7		type LinuxSpec struct {
8		Spec
9		// Linux is platform specific configuration for Linux based containers
10		Linux Linux `json:"linux"`
11		}
12
13		// Linux contains platform specific configuration for Linux based containers
14		type Linux struct {
15		// UIDMapping specifies user mappings for supporting user namespaces on Linux
16		UIDMappings []IDMapping `json:"uidMappings"`
17		// GIDMapping specifies group mappings for supporting user namespaces on Linux
18		GIDMappings []IDMapping `json:"gidMappings"`
19		// Rlimits specifies rlimit options to apply to the container's process
20		Rlimits []Rlimit `json:"rlimits"`
21		// Sysctl are a set of key value pairs that are set for the container on start
22		Sysctl map[string]string `json:"sysctl"`
23		// Resources contain cgroup information for handling resource constraints
24		// for the container
25		Resources Resources `json:"resources"`
26		// Namespaces contains the namespaces that are created and/or joined by the container
27		Namespaces []Namespace `json:"namespaces"`
28		// Capabilities are Linux capabilities that are kept for the container
29		Capabilities []string `json:"capabilities"`
30		// Devices are a list of device nodes that are created and enabled for the container
31		Devices []Device `json:"devices"`
32		// ApparmorProfile specified the apparmor profile for the container.
33		ApparmorProfile string `json:"apparmorProfile"`
34		// SelinuxProcessLabel specifies the selinux context that the container process is run as.
35		SelinuxProcessLabel string `json:"selinuxProcessLabel"`
36		// Seccomp specifies the seccomp security settings for the container.
37		Seccomp Seccomp `json:"seccomp"`
38		// RootfsPropagation is the rootfs mount propagation mode for the container
39		RootfsPropagation string `json:"rootfsPropagation"`
40		}
41
42		// User specifies Linux specific user and group information for the container's
43		// main process
44		type User struct {
45		// Uid is the user id
46		UID int32 `json:"uid"`
47		// Gid is the group id
48		GID int32 `json:"gid"`
49		// AdditionalGids are additional group ids set for the container's process
50		AdditionalGids []int32 `json:"additionalGids"`
51		}
52
53		// Namespace is the configuration for a Linux namespace
54		type Namespace struct {
55		// Type is the type of Linux namespace
56		Type string `json:"type"`
57		// Path is a path to an existing namespace persisted on disk that can be joined
58		// and is of the same type
59		Path string `json:"path"`
60		}
61
62		// IDMapping specifies UID/GID mappings
63		type IDMapping struct {
64		// HostID is the UID/GID of the host user or group
65		HostID int32 `json:"hostID"`
66		// ContainerID is the UID/GID of the container's user or group
67		ContainerID int32 `json:"containerID"`
68		// Size is the length of the range of IDs mapped between the two namespaces
69		Size int32 `json:"size"`
70		}
71
72		// Rlimit type and restrictions
73		type Rlimit struct {
74		// Type of the rlimit to set
75		Type int `json:"type"`
76		// Hard is the hard limit for the specified type
77		Hard uint64 `json:"hard"`
78		// Soft is the soft limit for the specified type
79		Soft uint64 `json:"soft"`
80		}
81
82		// HugepageLimit structure corresponds to limiting kernel hugepages
83		type HugepageLimit struct {
84		Pagesize string `json:"pageSize"`
85		Limit int `json:"limit"`
86		}
87
88		// InterfacePriority for network interfaces
89		type InterfacePriority struct {
90		// Name is the name of the network interface
91		Name string `json:"name"`
92		// Priority for the interface
93		Priority int64 `json:"priority"`
94		}
95
96		// BlockIO for Linux cgroup 'blockio' resource management
97		type BlockIO struct {
98		// Specifies per cgroup weight, range is from 10 to 1000
99		Weight int64 `json:"blkioWeight"`
100		// Weight per cgroup per device, can override BlkioWeight
101		WeightDevice string `json:"blkioWeightDevice"`
102		// IO read rate limit per cgroup per device, bytes per second
103		ThrottleReadBpsDevice string `json:"blkioThrottleReadBpsDevice"`
104		// IO write rate limit per cgroup per divice, bytes per second
105		ThrottleWriteBpsDevice string `json:"blkioThrottleWriteBpsDevice"`
106		// IO read rate limit per cgroup per device, IO per second
107		ThrottleReadIOpsDevice string `json:"blkioThrottleReadIopsDevice"`
108		// IO write rate limit per cgroup per device, IO per second
109		ThrottleWriteIOpsDevice string `json:"blkioThrottleWriteIopsDevice"`
110		}
111
112		// Memory for Linux cgroup 'memory' resource management
113		type Memory struct {
114		// Memory limit (in bytes)
115		Limit int64 `json:"limit"`
116		// Memory reservation or soft_limit (in bytes)
117		Reservation int64 `json:"reservation"`
118		// Total memory usage (memory + swap); set `-1' to disable swap
119		Swap int64 `json:"swap"`
120		// Kernel memory limit (in bytes)
121		Kernel int64 `json:"kernel"`
122		// How aggressive the kernel will swap memory pages. Range from 0 to 100. Set -1 to use system default
123		Swappiness int64 `json:"swappiness"`
124		}
125
126		// CPU for Linux cgroup 'cpu' resource management
127		type CPU struct {
128		// CPU shares (relative weight vs. other cgroups with cpu shares)
129		Shares int64 `json:"shares"`
130		// CPU hardcap limit (in usecs). Allowed cpu time in a given period
131		Quota int64 `json:"quota"`
132		// CPU period to be used for hardcapping (in usecs). 0 to use system default
133		Period int64 `json:"period"`
134		// How many time CPU will use in realtime scheduling (in usecs)
135		RealtimeRuntime int64 `json:"realtimeRuntime"`
136		// CPU period to be used for realtime scheduling (in usecs)
137		RealtimePeriod int64 `json:"realtimePeriod"`
138		// CPU to use within the cpuset
139		Cpus string `json:"cpus"`
140		// MEM to use within the cpuset
141		Mems string `json:"mems"`
142		}
143
144		// Network identification and priority configuration
145		type Network struct {
146		// Set class identifier for container's network packets
147		ClassID string `json:"classId"`
148		// Set priority of network traffic for container
149		Priorities []InterfacePriority `json:"priorities"`
150		}
151
152		// Resources has container runtime resource constraints
153		type Resources struct {
154		// DisableOOMKiller disables the OOM killer for out of memory conditions
155		DisableOOMKiller bool `json:"disableOOMKiller"`
156		// Memory restriction configuration
157		Memory Memory `json:"memory"`
158		// CPU resource restriction configuration
159		CPU CPU `json:"cpu"`
160		// BlockIO restriction configuration
161		BlockIO BlockIO `json:"blockIO"`
162		// Hugetlb limit (in bytes)
163		HugepageLimits []HugepageLimit `json:"hugepageLimits"`
164		// Network restriction configuration
165		Network Network `json:"network"`
166		}
167
168		type Device struct {
169		// Path to the device.
170		Path string `json:"path"`
171		// Device type, block, char, etc.
172		Type rune `json:"type"`
173		// Major is the device's major number.
174		Major int64 `json:"major"`
175		// Minor is the device's minor number.
176		Minor int64 `json:"minor"`
177		// Cgroup permissions format, rwm.
178		Permissions string `json:"permissions"`
179		// FileMode permission bits for the device.
180		FileMode os.FileMode `json:"fileMode"`
181		// UID of the device.
182		UID uint32 `json:"uid"`
183		// Gid of the device.
184		GID uint32 `json:"gid"`
185		}
186
187		// Seccomp represents syscall restrictions
188		type Seccomp struct {
189		DefaultAction Action `json:"defaultAction"`
190		Syscalls []*Syscall `json:"syscalls"`
191		}
192
193		// Action taken upon Seccomp rule match
194		type Action string
195
196		// Operator used to match syscall arguments in Seccomp
197		type Operator string
198
199		// Arg used for matching specific syscall arguments in Seccomp
200		type Arg struct {
201		Index uint `json:"index"`
202		Value uint64 `json:"value"`
203		ValueTwo uint64 `json:"valueTwo"`
204		Op Operator `json:"op"`
205		}
206
207		// Syscall is used to match a syscall in Seccomp
208		type Syscall struct {
209		Name string `json:"name"`
210		Action Action `json:"action"`
211		Args []*Arg `json:"args"`
212		}