1# <a name="configuration" />Configuration
2
3This configuration file contains metadata necessary to implement [standard operations](runtime.md#operations) against the container.
4This includes the process to run, environment variables to inject, sandboxing features to use, etc.
5
6The canonical schema is defined in this document, but there is a JSON Schema in [`schema/config-schema.json`](schema/config-schema.json) and Go bindings in [`specs-go/config.go`](specs-go/config.go).
7[Platform](spec.md#platforms)-specific configuration schema are defined in the [platform-specific documents](#platform-specific-configuration) linked below.
8For properties that are only defined for some [platforms](spec.md#platforms), the Go property has a `platform` tag listing those protocols (e.g. `platform:"linux,solaris"`).
9
10Below is a detailed description of each field defined in the configuration format and valid values are specified.
11Platform-specific fields are identified as such.
12For all platform-specific configuration values, the scope defined below in the [Platform-specific configuration](#platform-specific-configuration) section applies.
13
14
15## <a name="configSpecificationVersion" />Specification version
16
17* **`ociVersion`** (string, REQUIRED) MUST be in [SemVer v2.0.0][semver-v2.0.0] format and specifies the version of the Open Container Initiative Runtime Specification with which the bundle complies.
18 The Open Container Initiative Runtime Specification follows semantic versioning and retains forward and backward compatibility within major versions.
19 For example, if a configuration is compliant with version 1.1 of this specification, it is compatible with all runtimes that support any 1.1 or later release of this specification, but is not compatible with a runtime that supports 1.0 and not 1.1.
20
21### Example
22
23```json
24"ociVersion": "0.1.0"
25```
26
27## <a name="configRoot" />Root
28
29**`root`** (object, OPTIONAL) specifies the container's root filesystem.
30On Windows, for Windows Server Containers, this field is REQUIRED.
31For [Hyper-V Containers](config-windows.md#hyperv), this field MUST NOT be set.
32
33On all other platforms, this field is REQUIRED.
34
35* **`path`** (string, REQUIRED) Specifies the path to the root filesystem for the container.
36 * On Windows, `path` MUST be a [volume GUID path][naming-a-volume].
37 * On POSIX platforms, `path` is either an absolute path or a relative path to the bundle.
38 For example, with a bundle at `/to/bundle` and a root filesystem at `/to/bundle/rootfs`, the `path` value can be either `/to/bundle/rootfs` or `rootfs`.
39 The value SHOULD be the conventional `rootfs`.
40
41 A directory MUST exist at the path declared by the field.
42
43* **`readonly`** (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container, defaults to false.
44 * On Windows, this field MUST be omitted or false.
45
46### Example (POSIX platforms)
47
48```json
49"root": {
50 "path": "rootfs",
51 "readonly": true
52}
53```
54
55### Example (Windows)
56
57```json
58"root": {
59 "path": "\\\\?\\Volume{ec84d99e-3f02-11e7-ac6c-00155d7682cf}\\"
60}
61```
62
63## <a name="configMounts" />Mounts
64
65**`mounts`** (array of objects, OPTIONAL) specifies additional mounts beyond [`root`](#root).
66The runtime MUST mount entries in the listed order.
67For Linux, the parameters are as documented in [mount(2)][mount.2] system call man page.
68For Solaris, the mount entry corresponds to the 'fs' resource in the [zonecfg(1M)][zonecfg.1m] man page.
69
70* **`destination`** (string, REQUIRED) Destination of mount point: path inside container.
71 This value MUST be an absolute path.
72 * Windows: one mount destination MUST NOT be nested within another mount (e.g., c:\\foo and c:\\foo\\bar).
73 * Solaris: corresponds to "dir" of the fs resource in [zonecfg(1M)][zonecfg.1m].
74* **`source`** (string, OPTIONAL) A device name, but can also be a file or directory name for bind mounts or a dummy.
75 Path values for bind mounts are either absolute or relative to the bundle.
76 A mount is a bind mount if it has either `bind` or `rbind` in the options.
77 * Windows: a local directory on the filesystem of the container host. UNC paths and mapped drives are not supported.
78 * Solaris: corresponds to "special" of the fs resource in [zonecfg(1M)][zonecfg.1m].
79* **`options`** (array of strings, OPTIONAL) Mount options of the filesystem to be used.
80 * Linux: See [Linux mount options](#configLinuxMountOptions) below.
81 * Solaris: corresponds to "options" of the fs resource in [zonecfg(1M)][zonecfg.1m].
82 * Windows: runtimes MUST support `ro`, mounting the filesystem read-only when `ro` is given.
83
84### <a name="configLinuxMountOptions" />Linux mount options
85
86Runtimes MUST/SHOULD/MAY implement the following option strings for Linux:
87
88 Option name | Requirement | Description
89------------------|-------------|-----------------------------------------------------
90 `async` | MUST | [^1]
91 `atime` | MUST | [^1]
92 `bind` | MUST | [^2] (bind mounts)
93 `defaults` | MUST | [^1]
94 `dev` | MUST | [^1]
95 `diratime` | MUST | [^1]
96 `dirsync` | MUST | [^1]
97 `exec` | MUST | [^1]
98 `iversion` | MUST | [^1]
99 `lazytime` | MUST | [^1]
100 `loud` | MUST | [^1]
101 `mand` | MAY | [^1] (Deprecated in kernel 5.15, util-linux 2.38)
102 `noatime` | MUST | [^1]
103 `nodev` | MUST | [^1]
104 `nodiratime` | MUST | [^1]
105 `noexec` | MUST | [^1]
106 `noiversion` | MUST | [^1]
107 `nolazytime` | MUST | [^1]
108 `nomand` | MAY | [^1]
109 `norelatime` | MUST | [^1]
110 `nostrictatime` | MUST | [^1]
111 `nosuid` | MUST | [^1]
112 `nosymfollow` | SHOULD | [^1] (Introduced in kernel 5.10, util-linux 2.38)
113 `private` | MUST | [^2] (bind mounts)
114 `ratime` | SHOULD | Recursive `atime` [^3]
115 `rbind` | MUST | [^2] (bind mounts)
116 `rdev` | SHOULD | Recursive `dev` [^3]
117 `rdiratime` | SHOULD | Recursive `diratime` [^3]
118 `relatime` | MUST | [^1]
119 `remount` | MUST | [^1]
120 `rexec` | SHOULD | Recursive `dev` [^3]
121 `rnoatime` | SHOULD | Recursive `noatime` [^3]
122 `rnodiratime` | SHOULD | Recursive `nodiratime` [^3]
123 `rnoexec` | SHOULD | Recursive `noexec` [^3]
124 `rnorelatime` | SHOULD | Recursive `norelatime` [^3]
125 `rnostrictatime` | SHOULD | Recursive `nostrictatime` [^3]
126 `rnosuid` | SHOULD | Recursive `nosuid` [^3]
127 `rnosymfollow` | SHOULD | Recursive `nosymfollow` [^3]
128 `ro` | MUST | [^1]
129 `rprivate` | MUST | [^2] (bind mounts)
130 `rrelatime ` | SHOULD | Recursive `relatime` [^3]
131 `rro` | SHOULD | Recursive `ro` [^3]
132 `rrw` | SHOULD | Recursive `rw` [^3]
133 `rshared` | MUST | [^2] (bind mounts)
134 `rslave` | MUST | [^2] (bind mounts)
135 `rstrictatime` | SHOULD | Recursive `strictatime` [^3]
136 `rsuid` | SHOULD | Recursive `suid` [^3]
137 `rsymfollow` | SHOULD | Recursive `symfollow` [^3]
138 `runbindable` | MUST | [^2] (bind mounts)
139 `rw` | MUST | [^1]
140 `shared` | MUST | [^1]
141 `silent` | MUST | [^1]
142 `slave` | MUST | [^2] (bind mounts)
143 `strictatime` | MUST | [^1]
144 `suid` | MUST | [^1]
145 `symfollow` | SHOULD | Opposite of `nosymfollow`
146 `sync` | MUST | [^1]
147 `tmpcopyup` | MAY | copy up the contents to a tmpfs
148 `unbindable` | MUST | [^2] (bind mounts)
149
150[^1]: Corresponds to [`mount(8)` (filesystem-independent)][mount.8-filesystem-independent].
151[^2]: Corresponds to [`mount(8)` (filesystem-specific)][mount.8-filesystem-specific].
152[^3]: These `AT_RECURSIVE` options need kernel 5.12 or later. See [`mount_setattr(2)`][mount_setattr.2]
153
154The "MUST" options correspond to [`mount(8)`][mount.8].
155
156Runtimes MAY also implement custom option strings that are not listed in the table above.
157If a custom option string is already recognized by [`mount(8)`][mount.8], the runtime SHOULD follow the behavior of [`mount(8)`][mount.8].
158
159Runtimes SHOULD pass unknown options to [`mount(2)`][mount.2] via the fifth argument (`const void *data`).
160
161### Example (Windows)
162
163```json
164"mounts": [
165 {
166 "destination": "C:\\folder-inside-container",
167 "source": "C:\\folder-on-host",
168 "options": ["ro"]
169 }
170]
171```
172
173### <a name="configPOSIXMounts" />POSIX-platform Mounts
174
175For POSIX platforms the `mounts` structure has the following fields:
176
177* **`type`** (string, OPTIONAL) The type of the filesystem to be mounted.
178 * Linux: filesystem types supported by the kernel as listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660"). For bind mounts (when `options` include either `bind` or `rbind`), the type is a dummy, often "none" (not listed in */proc/filesystems*).
179 * Solaris: corresponds to "type" of the fs resource in [zonecfg(1M)][zonecfg.1m].
180* **`uidMappings`** (array of type LinuxIDMapping, OPTIONAL) The mapping to convert UIDs from the source file system to the destination mount point.\
181The format is the same as [user namespace mappings](config-linux.md#user-namespace-mappings).
182* **`gidMappings`** (array of type LinuxIDMapping, OPTIONAL) The mapping to convert GIDs from the source file system to the destination mount point.
183For more details see `uidMappings`.
184
185
186### Example (Linux)
187
188```json
189"mounts": [
190 {
191 "destination": "/tmp",
192 "type": "tmpfs",
193 "source": "tmpfs",
194 "options": ["nosuid","strictatime","mode=755","size=65536k"]
195 },
196 {
197 "destination": "/data",
198 "type": "none",
199 "source": "/volumes/testing",
200 "options": ["rbind","rw"]
201 }
202]
203```
204
205### Example (Solaris)
206
207```json
208"mounts": [
209 {
210 "destination": "/opt/local",
211 "type": "lofs",
212 "source": "/usr/local",
213 "options": ["ro","nodevices"]
214 },
215 {
216 "destination": "/opt/sfw",
217 "type": "lofs",
218 "source": "/opt/sfw"
219 }
220]
221```
222
223## <a name="configProcess" />Process
224
225**`process`** (object, OPTIONAL) specifies the container process.
226This property is REQUIRED when [`start`](runtime.md#start) is called.
227
228* **`terminal`** (bool, OPTIONAL) specifies whether a terminal is attached to the process, defaults to false.
229 As an example, if set to true on Linux a pseudoterminal pair is allocated for the process and the pseudoterminal pty is duplicated on the process's [standard streams][stdin.3].
230* **`consoleSize`** (object, OPTIONAL) specifies the console size in characters of the terminal.
231 Runtimes MUST ignore `consoleSize` if `terminal` is `false` or unset.
232 * **`height`** (uint, REQUIRED)
233 * **`width`** (uint, REQUIRED)
234* **`cwd`** (string, REQUIRED) is the working directory that will be set for the executable.
235 This value MUST be an absolute path.
236* **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008's `environ`][ieee-1003.1-2008-xbd-c8.1].
237* **`args`** (array of strings, OPTIONAL) with similar semantics to [IEEE Std 1003.1-2008 `execvp`'s *argv*][ieee-1003.1-2008-functions-exec].
238 This specification extends the IEEE standard in that at least one entry is REQUIRED (non-Windows), and that entry is used with the same semantics as `execvp`'s *file*. This field is OPTIONAL on Windows, and `commandLine` is REQUIRED if this field is omitted.
239* **`commandLine`** (string, OPTIONAL) specifies the full command line to be executed on Windows.
240 This is the preferred means of supplying the command line on Windows. If omitted, the runtime will fall back to escaping and concatenating fields from `args` before making the system call into Windows.
241
242
243### <a name="configPOSIXProcess" />POSIX process
244
245For systems that support POSIX rlimits (for example Linux and Solaris), the `process` object supports the following process-specific properties:
246
247* **`rlimits`** (array of objects, OPTIONAL) allows setting resource limits for the process.
248 Each entry has the following structure:
249
250 * **`type`** (string, REQUIRED) the platform resource being limited.
251 * Linux: valid values are defined in the [`getrlimit(2)`][getrlimit.2] man page, such as `RLIMIT_MSGQUEUE`.
252 * Solaris: valid values are defined in the [`getrlimit(3)`][getrlimit.3] man page, such as `RLIMIT_CORE`.
253
254 The runtime MUST [generate an error](runtime.md#errors) for any values which cannot be mapped to a relevant kernel interface.
255 For each entry in `rlimits`, a [`getrlimit(3)`][getrlimit.3] on `type` MUST succeed.
256 For the following properties, `rlim` refers to the status returned by the `getrlimit(3)` call.
257
258 * **`soft`** (uint64, REQUIRED) the value of the limit enforced for the corresponding resource.
259 `rlim.rlim_cur` MUST match the configured value.
260 * **`hard`** (uint64, REQUIRED) the ceiling for the soft limit that could be set by an unprivileged process.
261 `rlim.rlim_max` MUST match the configured value.
262 Only a privileged process (e.g. one with the `CAP_SYS_RESOURCE` capability) can raise a hard limit.
263
264 If `rlimits` contains duplicated entries with same `type`, the runtime MUST [generate an error](runtime.md#errors).
265
266### <a name="configLinuxProcess" />Linux Process
267
268For Linux-based systems, the `process` object supports the following process-specific properties.
269
270* **`apparmorProfile`** (string, OPTIONAL) specifies the name of the AppArmor profile for the process.
271 For more information about AppArmor, see [AppArmor documentation][apparmor].
272* **`capabilities`** (object, OPTIONAL) is an object containing arrays that specifies the sets of capabilities for the process.
273 Valid values are defined in the [capabilities(7)][capabilities.7] man page, such as `CAP_CHOWN`.
274 Any value which cannot be mapped to a relevant kernel interface, or cannot
275 be granted otherwise MUST be [logged as a warning](runtime.md#warnings) by
276 the runtime. Runtimes SHOULD NOT fail if the container configuration requests
277 capabilities that cannot be granted, for example, if the runtime operates in
278 a restricted environment with a limited set of capabilities.
279 `capabilities` contains the following properties:
280
281 * **`effective`** (array of strings, OPTIONAL) the `effective` field is an array of effective capabilities that are kept for the process.
282 * **`bounding`** (array of strings, OPTIONAL) the `bounding` field is an array of bounding capabilities that are kept for the process.
283 * **`inheritable`** (array of strings, OPTIONAL) the `inheritable` field is an array of inheritable capabilities that are kept for the process.
284 * **`permitted`** (array of strings, OPTIONAL) the `permitted` field is an array of permitted capabilities that are kept for the process.
285 * **`ambient`** (array of strings, OPTIONAL) the `ambient` field is an array of ambient capabilities that are kept for the process.
286* **`noNewPrivileges`** (bool, OPTIONAL) setting `noNewPrivileges` to true prevents the process from gaining additional privileges.
287 As an example, the [`no_new_privs`][no-new-privs] article in the kernel documentation has information on how this is achieved using a `prctl` system call on Linux.
288* **`oomScoreAdj`** *(int, OPTIONAL)* adjusts the oom-killer score in `[pid]/oom_score_adj` for the process's `[pid]` in a [proc pseudo-filesystem][proc_2].
289 If `oomScoreAdj` is set, the runtime MUST set `oom_score_adj` to the given value.
290 If `oomScoreAdj` is not set, the runtime MUST NOT change the value of `oom_score_adj`.
291
292 This is a per-process setting, where as [`disableOOMKiller`](config-linux.md#memory) is scoped for a memory cgroup.
293 For more information on how these two settings work together, see [the memory cgroup documentation section 10. OOM Contol][cgroup-v1-memory_2].
294* **`scheduler`** (object, OPTIONAL) is an object describing the scheduler properties for the process. The `scheduler` contains the following properties:
295
296 * **`policy`** (string, REQUIRED) represents the scheduling policy. A valid list of values is:
297
298 * `SCHED_OTHER`
299 * `SCHED_FIFO`
300 * `SCHED_RR`
301 * `SCHED_BATCH`
302 * `SCHED_ISO`
303 * `SCHED_IDLE`
304 * `SCHED_DEADLINE`
305
306 * **`nice`** (int32, OPTIONAL) is the nice value for the process, affecting its priority. A lower nice value corresponds to a higher priority. If not set, the runtime must use the value 0.
307 * **`priority`** (int32, OPTIONAL) represents the static priority of the process, used by real-time policies like SCHED_FIFO and SCHED_RR. If not set, the runtime must use the value 0.
308 * **`flags`** (array of strings, OPTIONAL) is an array of strings representing scheduling flags. A valid list of values is:
309
310 * `SCHED_FLAG_RESET_ON_FORK`
311 * `SCHED_FLAG_RECLAIM`
312 * `SCHED_FLAG_DL_OVERRUN`
313 * `SCHED_FLAG_KEEP_POLICY`
314 * `SCHED_FLAG_KEEP_PARAMS`
315 * `SCHED_FLAG_UTIL_CLAMP_MIN`
316 * `SCHED_FLAG_UTIL_CLAMP_MAX`
317
318 * **`runtime`** (uint64, OPTIONAL) represents the amount of time in nanoseconds during which the process is allowed to run in a given period, used by the deadline scheduler. If not set, the runtime must use the value 0.
319 * **`deadline`** (uint64, OPTIONAL) represents the absolute deadline for the process to complete its execution, used by the deadline scheduler. If not set, the runtime must use the value 0.
320 * **`period`** (uint64, OPTIONAL) represents the length of the period in nanoseconds used for determining the process runtime, used by the deadline scheduler. If not set, the runtime must use the value 0.
321* **`selinuxLabel`** (string, OPTIONAL) specifies the SELinux label for the process.
322 For more information about SELinux, see [SELinux documentation][selinux].
323* **`ioPriority`** (object, OPTIONAL) configures the I/O priority settings for the container's processes within the process group.
324 The I/O priority settings will be automatically applied to the entire process group, affecting all processes within the container.
325 The following properties are available:
326
327 * **`class`** (string, REQUIRED) specifies the I/O scheduling class. Possible values are `IOPRIO_CLASS_RT`, `IOPRIO_CLASS_BE`, and `IOPRIO_CLASS_IDLE`.
328 * **`priority`** (int, REQUIRED) specifies the priority level within the class. The value should be an integer ranging from 0 (highest) to 7 (lowest).
329
330### <a name="configUser" />User
331
332The user for the process is a platform-specific structure that allows specific control over which user the process runs as.
333
334#### <a name="configPOSIXUser" />POSIX-platform User
335
336For POSIX platforms the `user` structure has the following fields:
337
338* **`uid`** (int, REQUIRED) specifies the user ID in the [container namespace](glossary.md#container-namespace).
339* **`gid`** (int, REQUIRED) specifies the group ID in the [container namespace](glossary.md#container-namespace).
340* **`umask`** (int, OPTIONAL) specifies the [umask][umask_2] of the user. If unspecified, the umask should not be changed from the calling process' umask.
341* **`additionalGids`** (array of ints, OPTIONAL) specifies additional group IDs in the [container namespace](glossary.md#container-namespace) to be added to the process.
342
343_Note: symbolic name for uid and gid, such as uname and gname respectively, are left to upper levels to derive (i.e. `/etc/passwd` parsing, NSS, etc)_
344
345### Example (Linux)
346
347```json
348"process": {
349 "terminal": true,
350 "consoleSize": {
351 "height": 25,
352 "width": 80
353 },
354 "user": {
355 "uid": 1,
356 "gid": 1,
357 "umask": 63,
358 "additionalGids": [5, 6]
359 },
360 "env": [
361 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
362 "TERM=xterm"
363 ],
364 "cwd": "/root",
365 "args": [
366 "sh"
367 ],
368 "apparmorProfile": "acme_secure_profile",
369 "selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675",
370 "ioPriority": {
371 "class": "IOPRIO_CLASS_IDLE",
372 "priority": 4
373 },
374 "noNewPrivileges": true,
375 "capabilities": {
376 "bounding": [
377 "CAP_AUDIT_WRITE",
378 "CAP_KILL",
379 "CAP_NET_BIND_SERVICE"
380 ],
381 "permitted": [
382 "CAP_AUDIT_WRITE",
383 "CAP_KILL",
384 "CAP_NET_BIND_SERVICE"
385 ],
386 "inheritable": [
387 "CAP_AUDIT_WRITE",
388 "CAP_KILL",
389 "CAP_NET_BIND_SERVICE"
390 ],
391 "effective": [
392 "CAP_AUDIT_WRITE",
393 "CAP_KILL"
394 ],
395 "ambient": [
396 "CAP_NET_BIND_SERVICE"
397 ]
398 },
399 "rlimits": [
400 {
401 "type": "RLIMIT_NOFILE",
402 "hard": 1024,
403 "soft": 1024
404 }
405 ]
406}
407```
408### Example (Solaris)
409
410```json
411"process": {
412 "terminal": true,
413 "consoleSize": {
414 "height": 25,
415 "width": 80
416 },
417 "user": {
418 "uid": 1,
419 "gid": 1,
420 "umask": 7,
421 "additionalGids": [2, 8]
422 },
423 "env": [
424 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
425 "TERM=xterm"
426 ],
427 "cwd": "/root",
428 "args": [
429 "/usr/bin/bash"
430 ]
431}
432```
433
434#### <a name="configWindowsUser" />Windows User
435
436For Windows based systems the user structure has the following fields:
437
438* **`username`** (string, OPTIONAL) specifies the user name for the process.
439
440### Example (Windows)
441
442```json
443"process": {
444 "terminal": true,
445 "user": {
446 "username": "containeradministrator"
447 },
448 "env": [
449 "VARIABLE=1"
450 ],
451 "cwd": "c:\\foo",
452 "args": [
453 "someapp.exe",
454 ]
455}
456```
457
458
459## <a name="configHostname" />Hostname
460
461* **`hostname`** (string, OPTIONAL) specifies the container's hostname as seen by processes running inside the container.
462 On Linux, for example, this will change the hostname in the [container](glossary.md#container-namespace) [UTS namespace][uts-namespace.7].
463 Depending on your [namespace configuration](config-linux.md#namespaces), the container UTS namespace may be the [runtime](glossary.md#runtime-namespace) [UTS namespace][uts-namespace.7].
464
465### Example
466
467```json
468"hostname": "mrsdalloway"
469```
470
471## <a name="configDomainname" />Domainname
472
473* **`domainname`** (string, OPTIONAL) specifies the container's domainname as seen by processes running inside the container.
474 On Linux, for example, this will change the domainname in the [container](glossary.md#container-namespace) [UTS namespace][uts-namespace.7].
475 Depending on your [namespace configuration](config-linux.md#namespaces), the container UTS namespace may be the [runtime](glossary.md#runtime-namespace) [UTS namespace][uts-namespace.7].
476
477### Example
478
479```json
480"domainname": "foobarbaz.test"
481```
482
483## <a name="configPlatformSpecificConfiguration" />Platform-specific configuration
484
485* **`linux`** (object, OPTIONAL) [Linux-specific configuration](config-linux.md).
486 This MAY be set if the target platform of this spec is `linux`.
487* **`windows`** (object, OPTIONAL) [Windows-specific configuration](config-windows.md).
488 This MUST be set if the target platform of this spec is `windows`.
489* **`solaris`** (object, OPTIONAL) [Solaris-specific configuration](config-solaris.md).
490 This MAY be set if the target platform of this spec is `solaris`.
491* **`vm`** (object, OPTIONAL) [Virtual-machine-specific configuration](config-vm.md).
492 This MAY be set if the target platform and architecture of this spec support hardware virtualization.
493* **`zos`** (object, OPTIONAL) [z/OS-specific configuration](config-zos.md).
494 This MAY be set if the target platform of this spec is `zos`.
495
496### Example (Linux)
497
498```json
499{
500 "linux": {
501 "namespaces": [
502 {
503 "type": "pid"
504 }
505 ]
506 }
507}
508```
509
510## <a name="configHooks" />POSIX-platform Hooks
511
512For POSIX platforms, the configuration structure supports `hooks` for configuring custom actions related to the [lifecycle](runtime.md#lifecycle) of the container.
513
514* **`hooks`** (object, OPTIONAL) MAY contain any of the following properties:
515 * **`prestart`** (array of objects, OPTIONAL, **DEPRECATED**) is an array of [`prestart` hooks](#prestart).
516 * Entries in the array contain the following properties:
517 * **`path`** (string, REQUIRED) with similar semantics to [IEEE Std 1003.1-2008 `execv`'s *path*][ieee-1003.1-2008-functions-exec].
518 This specification extends the IEEE standard in that **`path`** MUST be absolute.
519 * **`args`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008 `execv`'s *argv*][ieee-1003.1-2008-functions-exec].
520 * **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008's `environ`][ieee-1003.1-2008-xbd-c8.1].
521 * **`timeout`** (int, OPTIONAL) is the number of seconds before aborting the hook.
522 If set, `timeout` MUST be greater than zero.
523 * The value of `path` MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
524 * The `prestart` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
525 * **`createRuntime`** (array of objects, OPTIONAL) is an array of [`createRuntime` hooks](#createRuntime-hooks).
526 * Entries in the array contain the following properties (the entries are identical to the entries in the deprecated `prestart` hooks):
527 * **`path`** (string, REQUIRED) with similar semantics to [IEEE Std 1003.1-2008 `execv`'s *path*][ieee-1003.1-2008-functions-exec].
528 This specification extends the IEEE standard in that **`path`** MUST be absolute.
529 * **`args`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008 `execv`'s *argv*][ieee-1003.1-2008-functions-exec].
530 * **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008's `environ`][ieee-1003.1-2008-xbd-c8.1].
531 * **`timeout`** (int, OPTIONAL) is the number of seconds before aborting the hook.
532 If set, `timeout` MUST be greater than zero.
533 * The value of `path` MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
534 * The `createRuntime` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
535 * **`createContainer`** (array of objects, OPTIONAL) is an array of [`createContainer` hooks](#createContainer-hooks).
536 * Entries in the array have the same schema as `createRuntime` entries.
537 * The value of `path` MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
538 * The `createContainer` hooks MUST be executed in the [container namespace](glossary.md#container-namespace).
539 * **`startContainer`** (array of objects, OPTIONAL) is an array of [`startContainer` hooks](#startContainer-hooks).
540 * Entries in the array have the same schema as `createRuntime` entries.
541 * The value of `path` MUST resolve in the [container namespace](glossary.md#container-namespace).
542 * The `startContainer` hooks MUST be executed in the [container namespace](glossary.md#container-namespace).
543 * **`poststart`** (array of objects, OPTIONAL) is an array of [`poststart` hooks](#poststart).
544 * Entries in the array have the same schema as `createRuntime` entries.
545 * The value of `path` MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
546 * The `poststart` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
547 * **`poststop`** (array of objects, OPTIONAL) is an array of [`poststop` hooks](#poststop).
548 * Entries in the array have the same schema as `createRuntime` entries.
549 * The value of `path` MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
550 * The `poststop` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
551
552Hooks allow users to specify programs to run before or after various lifecycle events.
553Hooks MUST be called in the listed order.
554The [state](runtime.md#state) of the container MUST be passed to hooks over stdin so that they may do work appropriate to the current state of the container.
555
556### <a name="configHooksPrestart" />Prestart
557
558The `prestart` hooks MUST be called as part of the [`create`](runtime.md#create) operation after the runtime environment has been created (according to the configuration in config.json) but before the `pivot_root` or any equivalent operation has been executed.
559On Linux, for example, they are called after the container namespaces are created, so they provide an opportunity to customize the container (e.g. the network namespace could be specified in this hook).
560The `prestart` hooks MUST be called before the `createRuntime` hooks.
561
562Note: `prestart` hooks were deprecated in favor of `createRuntime`, `createContainer` and `startContainer` hooks, which allow more granular hook control during the create and start phase.
563
564The `prestart` hooks' path MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
565The `prestart` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
566
567### <a name="configHooksCreateRuntime" />CreateRuntime Hooks
568
569The `createRuntime` hooks MUST be called as part of the [`create`](runtime.md#create) operation after the runtime environment has been created (according to the configuration in config.json) but before the `pivot_root` or any equivalent operation has been executed.
570
571The `createRuntime` hooks' path MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
572The `createRuntime` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
573
574On Linux, for example, they are called after the container namespaces are created, so they provide an opportunity to customize the container (e.g. the network namespace could be specified in this hook).
575
576The definition of `createRuntime` hooks is currently underspecified and hooks authors, should only expect from the runtime that the mount namespace have been created and the mount operations performed. Other operations such as cgroups and SELinux/AppArmor labels might not have been performed by the runtime.
577
578### <a name="configHooksCreateContainer" />CreateContainer Hooks
579
580The `createContainer` hooks MUST be called as part of the [`create`](runtime.md#create) operation after the runtime environment has been created (according to the configuration in config.json) but before the `pivot_root` or any equivalent operation has been executed.
581The `createContainer` hooks MUST be called after the `createRuntime` hooks.
582
583The `createContainer` hooks' path MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
584The `createContainer` hooks MUST be executed in the [container namespace](glossary.md#container-namespace).
585
586For example, on Linux this would happen before the `pivot_root` operation is executed but after the mount namespace was created and setup.
587
588The definition of `createContainer` hooks is currently underspecified and hooks authors, should only expect from the runtime that the mount namespace and different mounts will be setup. Other operations such as cgroups and SELinux/AppArmor labels might not have been performed by the runtime.
589
590### <a name="configHooksStartContainer" />StartContainer Hooks
591
592The `startContainer` hooks MUST be called [before the user-specified process is executed](runtime.md#lifecycle) as part of the [`start`](runtime.md#start) operation.
593This hook can be used to execute some operations in the container, for example running the `ldconfig` binary on linux before the container process is spawned.
594
595The `startContainer` hooks' path MUST resolve in the [container namespace](glossary.md#container-namespace).
596The `startContainer` hooks MUST be executed in the [container namespace](glossary.md#container-namespace).
597
598### <a name="configHooksPoststart" />Poststart
599
600The `poststart` hooks MUST be called [after the user-specified process is executed](runtime.md#lifecycle) but before the [`start`](runtime.md#start) operation returns.
601For example, this hook can notify the user that the container process is spawned.
602
603The `poststart` hooks' path MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
604The `poststart` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
605
606### <a name="configHooksPoststop" />Poststop
607
608The `poststop` hooks MUST be called [after the container is deleted](runtime.md#lifecycle) but before the [`delete`](runtime.md#delete) operation returns.
609Cleanup or debugging functions are examples of such a hook.
610
611The `poststop` hooks' path MUST resolve in the [runtime namespace](glossary.md#runtime-namespace).
612The `poststop` hooks MUST be executed in the [runtime namespace](glossary.md#runtime-namespace).
613
614### Summary
615
616See the below table for a summary of hooks and when they are called:
617
618| Name | Namespace | When |
619| ----------------------- | --------- | -----------------------------------------------------------------------------------------------------------------------------------|
620| `prestart` (Deprecated) | runtime | After the start operation is called but before the user-specified program command is executed. |
621| `createRuntime` | runtime | During the create operation, after the runtime environment has been created and before the pivot root or any equivalent operation. |
622| `createContainer` | container | During the create operation, after the runtime environment has been created and before the pivot root or any equivalent operation. |
623| `startContainer` | container | After the start operation is called but before the user-specified program command is executed. |
624| `poststart` | runtime | After the user-specified process is executed but before the start operation returns. |
625| `poststop` | runtime | After the container is deleted but before the delete operation returns. |
626
627### Example
628
629```json
630"hooks": {
631 "prestart": [
632 {
633 "path": "/usr/bin/fix-mounts",
634 "args": ["fix-mounts", "arg1", "arg2"],
635 "env": [ "key1=value1"]
636 },
637 {
638 "path": "/usr/bin/setup-network"
639 }
640 ],
641 "createRuntime": [
642 {
643 "path": "/usr/bin/fix-mounts",
644 "args": ["fix-mounts", "arg1", "arg2"],
645 "env": [ "key1=value1"]
646 },
647 {
648 "path": "/usr/bin/setup-network"
649 }
650 ],
651 "createContainer": [
652 {
653 "path": "/usr/bin/mount-hook",
654 "args": ["-mount", "arg1", "arg2"],
655 "env": [ "key1=value1"]
656 }
657 ],
658 "startContainer": [
659 {
660 "path": "/usr/bin/refresh-ldcache"
661 }
662 ],
663 "poststart": [
664 {
665 "path": "/usr/bin/notify-start",
666 "timeout": 5
667 }
668 ],
669 "poststop": [
670 {
671 "path": "/usr/sbin/cleanup.sh",
672 "args": ["cleanup.sh", "-f"]
673 }
674 ]
675}
676```
677
678## <a name="configAnnotations" />Annotations
679
680**`annotations`** (object, OPTIONAL) contains arbitrary metadata for the container.
681This information MAY be structured or unstructured.
682Annotations MUST be a key-value map.
683If there are no annotations then this property MAY either be absent or an empty map.
684
685Keys MUST be strings.
686Keys MUST NOT be an empty string.
687Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`.
688Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by subsequent specifications.
689Runtimes MUST handle unknown annotation keys like any other [unknown property](#extensibility).
690
691Values MUST be strings.
692Values MAY be an empty string.
693
694```json
695"annotations": {
696 "com.example.gpu-cores": "2"
697}
698```
699
700## <a name="configExtensibility" />Extensibility
701
702Runtimes MAY [log](runtime.md#warnings) unknown properties but MUST otherwise ignore them.
703That includes not [generating errors](runtime.md#errors) if they encounter an unknown property.
704
705## Valid values
706
707Runtimes MUST generate an error when invalid or unsupported values are encountered.
708Unless support for a valid value is explicitly required, runtimes MAY choose which subset of the valid values it will support.
709
710## Configuration Schema Example
711
712Here is a full example `config.json` for reference.
713
714```json
715{
716 "ociVersion": "1.0.1",
717 "process": {
718 "terminal": true,
719 "user": {
720 "uid": 1,
721 "gid": 1,
722 "additionalGids": [
723 5,
724 6
725 ]
726 },
727 "args": [
728 "sh"
729 ],
730 "env": [
731 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
732 "TERM=xterm"
733 ],
734 "cwd": "/",
735 "capabilities": {
736 "bounding": [
737 "CAP_AUDIT_WRITE",
738 "CAP_KILL",
739 "CAP_NET_BIND_SERVICE"
740 ],
741 "permitted": [
742 "CAP_AUDIT_WRITE",
743 "CAP_KILL",
744 "CAP_NET_BIND_SERVICE"
745 ],
746 "inheritable": [
747 "CAP_AUDIT_WRITE",
748 "CAP_KILL",
749 "CAP_NET_BIND_SERVICE"
750 ],
751 "effective": [
752 "CAP_AUDIT_WRITE",
753 "CAP_KILL"
754 ],
755 "ambient": [
756 "CAP_NET_BIND_SERVICE"
757 ]
758 },
759 "rlimits": [
760 {
761 "type": "RLIMIT_CORE",
762 "hard": 1024,
763 "soft": 1024
764 },
765 {
766 "type": "RLIMIT_NOFILE",
767 "hard": 1024,
768 "soft": 1024
769 }
770 ],
771 "apparmorProfile": "acme_secure_profile",
772 "oomScoreAdj": 100,
773 "selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675",
774 "ioPriority": {
775 "class": "IOPRIO_CLASS_IDLE",
776 "priority": 4
777 },
778 "noNewPrivileges": true
779 },
780 "root": {
781 "path": "rootfs",
782 "readonly": true
783 },
784 "hostname": "slartibartfast",
785 "mounts": [
786 {
787 "destination": "/proc",
788 "type": "proc",
789 "source": "proc"
790 },
791 {
792 "destination": "/dev",
793 "type": "tmpfs",
794 "source": "tmpfs",
795 "options": [
796 "nosuid",
797 "strictatime",
798 "mode=755",
799 "size=65536k"
800 ]
801 },
802 {
803 "destination": "/dev/pts",
804 "type": "devpts",
805 "source": "devpts",
806 "options": [
807 "nosuid",
808 "noexec",
809 "newinstance",
810 "ptmxmode=0666",
811 "mode=0620",
812 "gid=5"
813 ]
814 },
815 {
816 "destination": "/dev/shm",
817 "type": "tmpfs",
818 "source": "shm",
819 "options": [
820 "nosuid",
821 "noexec",
822 "nodev",
823 "mode=1777",
824 "size=65536k"
825 ]
826 },
827 {
828 "destination": "/dev/mqueue",
829 "type": "mqueue",
830 "source": "mqueue",
831 "options": [
832 "nosuid",
833 "noexec",
834 "nodev"
835 ]
836 },
837 {
838 "destination": "/sys",
839 "type": "sysfs",
840 "source": "sysfs",
841 "options": [
842 "nosuid",
843 "noexec",
844 "nodev"
845 ]
846 },
847 {
848 "destination": "/sys/fs/cgroup",
849 "type": "cgroup",
850 "source": "cgroup",
851 "options": [
852 "nosuid",
853 "noexec",
854 "nodev",
855 "relatime",
856 "ro"
857 ]
858 }
859 ],
860 "hooks": {
861 "prestart": [
862 {
863 "path": "/usr/bin/fix-mounts",
864 "args": [
865 "fix-mounts",
866 "arg1",
867 "arg2"
868 ],
869 "env": [
870 "key1=value1"
871 ]
872 },
873 {
874 "path": "/usr/bin/setup-network"
875 }
876 ],
877 "poststart": [
878 {
879 "path": "/usr/bin/notify-start",
880 "timeout": 5
881 }
882 ],
883 "poststop": [
884 {
885 "path": "/usr/sbin/cleanup.sh",
886 "args": [
887 "cleanup.sh",
888 "-f"
889 ]
890 }
891 ]
892 },
893 "linux": {
894 "devices": [
895 {
896 "path": "/dev/fuse",
897 "type": "c",
898 "major": 10,
899 "minor": 229,
900 "fileMode": 438,
901 "uid": 0,
902 "gid": 0
903 },
904 {
905 "path": "/dev/sda",
906 "type": "b",
907 "major": 8,
908 "minor": 0,
909 "fileMode": 432,
910 "uid": 0,
911 "gid": 0
912 }
913 ],
914 "uidMappings": [
915 {
916 "containerID": 0,
917 "hostID": 1000,
918 "size": 32000
919 }
920 ],
921 "gidMappings": [
922 {
923 "containerID": 0,
924 "hostID": 1000,
925 "size": 32000
926 }
927 ],
928 "sysctl": {
929 "net.ipv4.ip_forward": "1",
930 "net.core.somaxconn": "256"
931 },
932 "cgroupsPath": "/myRuntime/myContainer",
933 "resources": {
934 "network": {
935 "classID": 1048577,
936 "priorities": [
937 {
938 "name": "eth0",
939 "priority": 500
940 },
941 {
942 "name": "eth1",
943 "priority": 1000
944 }
945 ]
946 },
947 "pids": {
948 "limit": 32771
949 },
950 "hugepageLimits": [
951 {
952 "pageSize": "2MB",
953 "limit": 9223372036854772000
954 },
955 {
956 "pageSize": "64KB",
957 "limit": 1000000
958 }
959 ],
960 "memory": {
961 "limit": 536870912,
962 "reservation": 536870912,
963 "swap": 536870912,
964 "kernel": -1,
965 "kernelTCP": -1,
966 "swappiness": 0,
967 "disableOOMKiller": false
968 },
969 "cpu": {
970 "shares": 1024,
971 "quota": 1000000,
972 "period": 500000,
973 "realtimeRuntime": 950000,
974 "realtimePeriod": 1000000,
975 "cpus": "2-3",
976 "idle": 1,
977 "mems": "0-7"
978 },
979 "devices": [
980 {
981 "allow": false,
982 "access": "rwm"
983 },
984 {
985 "allow": true,
986 "type": "c",
987 "major": 10,
988 "minor": 229,
989 "access": "rw"
990 },
991 {
992 "allow": true,
993 "type": "b",
994 "major": 8,
995 "minor": 0,
996 "access": "r"
997 }
998 ],
999 "blockIO": {
1000 "weight": 10,
1001 "leafWeight": 10,
1002 "weightDevice": [
1003 {
1004 "major": 8,
1005 "minor": 0,
1006 "weight": 500,
1007 "leafWeight": 300
1008 },
1009 {
1010 "major": 8,
1011 "minor": 16,
1012 "weight": 500
1013 }
1014 ],
1015 "throttleReadBpsDevice": [
1016 {
1017 "major": 8,
1018 "minor": 0,
1019 "rate": 600
1020 }
1021 ],
1022 "throttleWriteIOPSDevice": [
1023 {
1024 "major": 8,
1025 "minor": 16,
1026 "rate": 300
1027 }
1028 ]
1029 }
1030 },
1031 "rootfsPropagation": "slave",
1032 "seccomp": {
1033 "defaultAction": "SCMP_ACT_ALLOW",
1034 "architectures": [
1035 "SCMP_ARCH_X86",
1036 "SCMP_ARCH_X32"
1037 ],
1038 "syscalls": [
1039 {
1040 "names": [
1041 "getcwd",
1042 "chmod"
1043 ],
1044 "action": "SCMP_ACT_ERRNO"
1045 }
1046 ]
1047 },
1048 "timeOffsets": {
1049 "monotonic": {
1050 "secs": 172800,
1051 "nanosecs": 0
1052 },
1053 "boottime": {
1054 "secs": 604800,
1055 "nanosecs": 0
1056 }
1057 },
1058 "namespaces": [
1059 {
1060 "type": "pid"
1061 },
1062 {
1063 "type": "network"
1064 },
1065 {
1066 "type": "ipc"
1067 },
1068 {
1069 "type": "uts"
1070 },
1071 {
1072 "type": "mount"
1073 },
1074 {
1075 "type": "user"
1076 },
1077 {
1078 "type": "cgroup"
1079 },
1080 {
1081 "type": "time"
1082 }
1083 ],
1084 "maskedPaths": [
1085 "/proc/kcore",
1086 "/proc/latency_stats",
1087 "/proc/timer_stats",
1088 "/proc/sched_debug"
1089 ],
1090 "readonlyPaths": [
1091 "/proc/asound",
1092 "/proc/bus",
1093 "/proc/fs",
1094 "/proc/irq",
1095 "/proc/sys",
1096 "/proc/sysrq-trigger"
1097 ],
1098 "mountLabel": "system_u:object_r:svirt_sandbox_file_t:s0:c715,c811"
1099 },
1100 "annotations": {
1101 "com.example.key1": "value1",
1102 "com.example.key2": "value2"
1103 }
1104}
1105```
1106
1107
1108[apparmor]: https://wiki.ubuntu.com/AppArmor
1109[cgroup-v1-memory_2]: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt
1110[selinux]:http://selinuxproject.org/page/Main_Page
1111[no-new-privs]: https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt
1112[proc_2]: https://www.kernel.org/doc/Documentation/filesystems/proc.txt
1113[umask.2]: http://pubs.opengroup.org/onlinepubs/009695399/functions/umask.html
1114[semver-v2.0.0]: http://semver.org/spec/v2.0.0.html
1115[ieee-1003.1-2008-xbd-c8.1]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_01
1116[ieee-1003.1-2008-functions-exec]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/exec.html
1117[naming-a-volume]: https://aka.ms/nb3hqb
1118
1119[capabilities.7]: http://man7.org/linux/man-pages/man7/capabilities.7.html
1120[mount.2]: http://man7.org/linux/man-pages/man2/mount.2.html
1121[mount.8]: http://man7.org/linux/man-pages/man8/mount.8.html
1122[mount.8-filesystem-independent]: http://man7.org/linux/man-pages/man8/mount.8.html#FILESYSTEM-INDEPENDENT_MOUNT_OPTIONS
1123[mount.8-filesystem-specific]: http://man7.org/linux/man-pages/man8/mount.8.html#FILESYSTEM-SPECIFIC_MOUNT_OPTIONS
1124[mount_setattr.2]: http://man7.org/linux/man-pages/man2/mount_setattr.2.html
1125[getrlimit.2]: http://man7.org/linux/man-pages/man2/getrlimit.2.html
1126[getrlimit.3]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/getrlimit.html
1127[stdin.3]: http://man7.org/linux/man-pages/man3/stdin.3.html
1128[uts-namespace.7]: http://man7.org/linux/man-pages/man7/namespaces.7.html
1129[zonecfg.1m]: http://docs.oracle.com/cd/E86824_01/html/E54764/zonecfg-1m.html
View as plain text