Skip to content

Commit 41839d7

Browse files
author
Michael Crosby
authored
Merge pull request opencontainers#707 from mrunalp/anchor_tags
Anchor tags
2 parents 40474dd + c942816 commit 41839d7

7 files changed

Lines changed: 69 additions & 69 deletions

File tree

‎config-linux.md‎

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
# Linux-specific Container Configuration
1+
# <a name="linuxContainerConfiguration" />Linux Container Configuration
22

33
This document describes the schema for the [Linux-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md).
44
The Linux container specification uses various kernel features like namespaces, cgroups, capabilities, LSM, and filesystem jails to fulfill the spec.
55

6-
## Default Filesystems
6+
## <a name="configLinuxDefaultFilesystems" />Default Filesystems
77

88
The Linux ABI includes both syscalls and several special file paths.
99
Applications expecting a Linux environment will very likely expect these file paths to be setup correctly.
@@ -17,7 +17,7 @@ The following filesystems SHOULD be made available in each container's filesyste
1717
| /dev/pts | [devpts](https://www.kernel.org/doc/Documentation/filesystems/devpts.txt) |
1818
| /dev/shm | [tmpfs](https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt) |
1919

20-
## Namespaces
20+
## <a name="configLinuxNamespaces" />Namespaces
2121

2222
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.
2323
Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes.
@@ -71,7 +71,7 @@ If a `namespaces` field contains duplicated namespaces with same `type`, the run
7171
]
7272
```
7373

74-
## User namespace mappings
74+
## <a name="configLinuxUserNamespaceMappings" />User namespace mappings
7575

7676
**`uidMappings`** (array of objects, OPTIONAL) describes the user namespace uid mappings from the host to the container.
7777
**`gidMappings`** (array of objects, OPTIONAL) describes the user namespace gid mappings from the host to the container.
@@ -104,7 +104,7 @@ Note that the number of mapping entries MAY be limited by the [kernel][user-name
104104
]
105105
```
106106

107-
## Devices
107+
## <a name="configLinuxDevices" />Devices
108108

109109
**`devices`** (array of objects, OPTIONAL) lists devices that MUST be available in the container.
110110
The runtime may supply them however it likes (with [mknod][mknod.2], by bind mounting from the runtime mount namespace, etc.).
@@ -148,7 +148,7 @@ The same `type`, `major` and `minor` SHOULD NOT be used for multiple devices.
148148
]
149149
```
150150

151-
###### Default Devices
151+
###### <a name="configLinuxDefaultDevices" />Default Devices
152152

153153
In addition to any devices configured with this setting, the runtime MUST also supply:
154154

@@ -162,7 +162,7 @@ In addition to any devices configured with this setting, the runtime MUST also s
162162
* [`/dev/ptmx`][pts.4].
163163
A [bind-mount or symlink of the container's `/dev/pts/ptmx`][devpts].
164164

165-
## Control groups
165+
## <a name="configLinuxControlGroups" />Control groups
166166

167167
Also known as cgroups, they are used to restrict resource usage for a container and handle device access.
168168
cgroups provide controls (through controllers) to restrict cpu, memory, IO, pids and network for the container.
@@ -207,7 +207,7 @@ However, a runtime MAY attach the container process to additional cgroup control
207207
}
208208
```
209209

210-
#### Device whitelist
210+
#### <a name="configLinuxDeviceWhitelist" />Device whitelist
211211

212212
**`devices`** (array of objects, OPTIONAL) configures the [device whitelist][cgroup-v1-devices].
213213
The runtime MUST apply entries in the listed order.
@@ -247,7 +247,7 @@ Each entry has the following structure:
247247
]
248248
```
249249

250-
#### Disable out-of-memory killer
250+
#### <a name="configLinuxDisableOutOfMemoryKiller" />Disable out-of-memory killer
251251

252252
`disableOOMKiller` contains a boolean (`true` or `false`) that enables or disables the Out of Memory killer for a cgroup.
253253
If enabled (`false`), tasks that attempt to consume more memory than they are allowed are immediately killed by the OOM killer.
@@ -263,7 +263,7 @@ For more information, see [the memory cgroup man page][cgroup-v1-memory].
263263
"disableOOMKiller": false
264264
```
265265

266-
#### Set oom_score_adj
266+
#### <a name="configLinuxSetOomScoreAdj" />Set oom_score_adj
267267

268268
`oomScoreAdj` sets heuristic regarding how the process is evaluated by the kernel during memory pressure.
269269
For more information, see [the proc filesystem documentation section 3.1](https://www.kernel.org/doc/Documentation/filesystems/proc.txt).
@@ -278,7 +278,7 @@ For more information on how these two settings work together, see [the memory cg
278278
"oomScoreAdj": 100
279279
```
280280

281-
#### Memory
281+
#### <a name="configLinuxMemory" />Memory
282282

283283
**`memory`** (object, OPTIONAL) represents the cgroup subsystem `memory` and it's used to set limits on the container's memory usage.
284284
For more information, see [the memory cgroup man page][cgroup-v1-memory].
@@ -310,7 +310,7 @@ The following parameters can be specified to setup the controller:
310310
}
311311
```
312312

313-
#### CPU
313+
#### <a name="configLinuxCPU" />CPU
314314

315315
**`cpu`** (object, OPTIONAL) represents the cgroup subsystems `cpu` and `cpusets`.
316316
For more information, see [the cpusets cgroup man page][cgroup-v1-cpusets].
@@ -345,7 +345,7 @@ The following parameters can be specified to setup the controller:
345345
}
346346
```
347347

348-
#### Block IO Controller
348+
#### <a name="configLinuxBlockIO" />Block IO
349349

350350
**`blockIO`** (object, OPTIONAL) represents the cgroup subsystem `blkio` which implements the block IO controller.
351351
For more information, see [the kernel cgroups documentation about blkio][cgroup-v1-blkio].
@@ -404,7 +404,7 @@ The following parameters can be specified to setup the controller:
404404
}
405405
```
406406

407-
#### Huge page limits
407+
#### <a name="configLinuxHugePageLimits" />Huge page limits
408408

409409
**`hugepageLimits`** (array of objects, OPTIONAL) represents the `hugetlb` controller which allows to limit the
410410
HugeTLB usage per control group and enforces the controller limit during page fault.
@@ -427,7 +427,7 @@ Each entry has the following structure:
427427
]
428428
```
429429

430-
#### Network
430+
#### <a name="configLinuxNetwork" />Network
431431

432432
**`network`** (object, OPTIONAL) represents the cgroup subsystems `net_cls` and `net_prio`.
433433
For more information, see [the net\_cls cgroup man page][cgroup-v1-net-cls] and [the net\_prio cgroup man page][cgroup-v1-net-prio].
@@ -459,7 +459,7 @@ The following parameters can be specified to setup the controller:
459459
}
460460
```
461461

462-
#### PIDs
462+
#### <a name="configLinuxPIDS" />PIDs
463463

464464
**`pids`** (object, OPTIONAL) represents the cgroup subsystem `pids`.
465465
For more information, see [the pids cgroup man page][cgroup-v1-pids].
@@ -476,7 +476,7 @@ The following parameters can be specified to setup the controller:
476476
}
477477
```
478478

479-
## Sysctl
479+
## <a name="configLinuxSysctl" />Sysctl
480480

481481
**`sysctl`** (object, OPTIONAL) allows kernel parameters to be modified at runtime for the container.
482482
For more information, see [the man page](http://man7.org/linux/man-pages/man8/sysctl.8.html)
@@ -490,7 +490,7 @@ For more information, see [the man page](http://man7.org/linux/man-pages/man8/sy
490490
}
491491
```
492492

493-
## seccomp
493+
## <a name="configLinuxSeccomp" />Seccomp
494494

495495
Seccomp provides application sandboxing mechanism in the Linux kernel.
496496
Seccomp configuration allows one to configure actions to take for matched syscalls and furthermore also allows matching on values passed as arguments to syscalls.
@@ -554,7 +554,7 @@ Operator Constants:
554554
}
555555
```
556556

557-
## Rootfs Mount Propagation
557+
## <a name="configLinuxRootfsMountPropagation" />Rootfs Mount Propagation
558558

559559
**`rootfsPropagation`** (string, OPTIONAL) sets the rootfs's mount propagation.
560560
Its value is either slave, private, or shared.
@@ -566,7 +566,7 @@ Its value is either slave, private, or shared.
566566
"rootfsPropagation": "slave",
567567
```
568568

569-
## Masked Paths
569+
## <a name="configLinuxMaskedPaths" />Masked Paths
570570

571571
**`maskedPaths`** (array of strings, OPTIONAL) will mask over the provided paths inside the container so that they cannot be read.
572572
The values MUST be absolute paths in the [container namespace][container-namespace2].
@@ -579,7 +579,7 @@ The values MUST be absolute paths in the [container namespace][container-namespa
579579
]
580580
```
581581

582-
## Readonly Paths
582+
## <a name="configLinuxReadonlyPaths" />Readonly Paths
583583

584584
**`readonlyPaths`** (array of strings, OPTIONAL) will set the provided paths as readonly inside the container.
585585
The values MUST be absolute paths in the [container namespace][container-namespace2].
@@ -592,7 +592,7 @@ The values MUST be absolute paths in the [container namespace][container-namespa
592592
]
593593
```
594594

595-
## Mount Label
595+
## <a name"configLinuxMountLabel" />Mount Label
596596

597597
**`mountLabel`** (string, OPTIONAL) will set the Selinux context for the mounts in the container.
598598

‎config.md‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Container Configuration file
1+
# <a name="containerConfigurationFile" />Container Configuration file
22

33
The container's top-level directory MUST contain a configuration file called `config.json`.
44
The canonical schema is defined in this document, but there is a JSON Schema in [`schema/config-schema.json`](schema/config-schema.json) and Go bindings in [`specs-go/config.go`](specs-go/config.go).
@@ -13,7 +13,7 @@ Platform-specific fields are identified as such.
1313
For all platform-specific configuration values, the scope defined below in the [Platform-specific configuration](#platform-specific-configuration) section applies.
1414

1515

16-
## Specification version
16+
## <a name="configSpecificationVersion" />Specification version
1717

1818
* **`ociVersion`** (string, REQUIRED) MUST be in [SemVer v2.0.0](http://semver.org/spec/v2.0.0.html) format and specifies the version of the Open Container Runtime Specification with which the bundle complies.
1919
The Open Container Runtime Specification follows semantic versioning and retains forward and backward compatibility within major versions.
@@ -25,7 +25,7 @@ For example, if a configuration is compliant with version 1.1 of this specificat
2525
"ociVersion": "0.1.0"
2626
```
2727

28-
## Root Configuration
28+
## <a name="configRoot" />Root
2929

3030
**`root`** (object, REQUIRED) specifies the container's root filesystem.
3131

@@ -44,7 +44,7 @@ For example, if a configuration is compliant with version 1.1 of this specificat
4444
}
4545
```
4646

47-
## Mounts
47+
## <a name="configMounts" />Mounts
4848

4949
**`mounts`** (array, OPTIONAL) specifies additional mounts beyond [`root`](#root-configuration).
5050
The runtime MUST mount entries in the listed order.
@@ -118,7 +118,7 @@ For Windows, see links for details about [mountvol](http://ss64.com/nt/mountvol.
118118
]
119119
```
120120

121-
## Process
121+
## <a name="configProcess" />Process
122122

123123
**`process`** (object, REQUIRED) specifies the container process.
124124

@@ -158,11 +158,11 @@ For Linux-based systems the process structure supports the following process spe
158158
* **`selinuxLabel`** (string, OPTIONAL) specifies the SELinux label to be applied to the processes in the container.
159159
For more information about SELinux, see [SELinux documentation](http://selinuxproject.org/page/Main_Page)
160160

161-
### User
161+
### <a name="configUser" />User
162162

163163
The user for the process is a platform-specific structure that allows specific control over which user the process runs as.
164164

165-
#### Linux and Solaris User
165+
#### <a name="configLinuxAndSolarisUser" />Linux and Solaris User
166166

167167
For Linux and Solaris based systems the user structure has the following fields:
168168

@@ -255,7 +255,7 @@ _Note: symbolic name for uid and gid, such as uname and gname respectively, are
255255
}
256256
```
257257

258-
#### Windows User
258+
#### <a name="configWindowsUser" />Windows User
259259

260260
For Windows based systems the user structure has the following fields:
261261

@@ -280,7 +280,7 @@ For Windows based systems the user structure has the following fields:
280280
```
281281

282282

283-
## Hostname
283+
## <a name="configHostname" />Hostname
284284

285285
* **`hostname`** (string, OPTIONAL) specifies the container's hostname as seen by processes running inside the container.
286286
On Linux, for example, this will change the hostname in the [container][container-namespace] [UTS namespace][uts-namespace].
@@ -292,7 +292,7 @@ For Windows based systems the user structure has the following fields:
292292
"hostname": "mrsdalloway"
293293
```
294294

295-
## Platform
295+
## <a name="configPlatform" />Platform
296296

297297
**`platform`** (object, REQUIRED) specifies the configuration's target platform.
298298

@@ -314,7 +314,7 @@ For Windows based systems the user structure has the following fields:
314314
}
315315
```
316316

317-
## Platform-specific configuration
317+
## <a name="configPlatformSpecificConfiguration" />Platform-specific configuration
318318

319319
[**`platform.os`**](#platform) is used to specify platform-specific configuration.
320320
Runtime implementations MAY support any valid values for platform-specific fields as part of this configuration.
@@ -345,7 +345,7 @@ Implementations MUST error out when invalid values are encountered and MUST gene
345345
}
346346
```
347347

348-
## Hooks
348+
## <a name="configHooks" />Hooks
349349

350350
Hooks allow for the configuration of custom actions related to the [lifecycle](runtime.md#lifecycle) of the container.
351351

@@ -366,21 +366,21 @@ Hooks allow users to specify programs to run before or after various lifecycle e
366366
Hooks MUST be called in the listed order.
367367
The [state](runtime.md#state) of the container MUST be passed to hooks over stdin so that they may do work appropriate to the current state of the container.
368368

369-
### Prestart
369+
### <a name="configHooksPrestart" />Prestart
370370

371371
The pre-start hooks MUST be called after the container has been created, but before the user supplied command is executed.
372372
On Linux, for example, they are called after the container namespaces are created, so they provide an opportunity to customize the container (e.g. the network namespace could be specified in this hook).
373373

374374
If a hook returns a non-zero exit code, an error including the exit code and the stderr MUST be returned to the caller and the container MUST be destroyed.
375375

376-
### Poststart
376+
### <a name="configHooksPoststart" />Poststart
377377

378378
The post-start hooks MUST be called after the user process is started.
379379
For example, this hook can notify the user that the container process is spawned.
380380

381381
If a hook returns a non-zero exit code, then an error MUST be logged and the remaining hooks are executed.
382382

383-
### Poststop
383+
### <a name="configHooksPoststop" />Poststop
384384

385385
The post-stop hooks MUST be called after the container process is stopped.
386386
Cleanup or debugging functions are examples of such a hook.
@@ -415,7 +415,7 @@ If a hook returns a non-zero exit code, then an error MUST be logged and the rem
415415
}
416416
```
417417

418-
## Annotations
418+
## <a name="configAnnotations" />Annotations
419419

420420
**`annotations`** (object, OPTIONAL) contains arbitrary metadata for the container.
421421
This information MAY be structured or unstructured.
@@ -438,7 +438,7 @@ Values MAY be an empty string.
438438
}
439439
```
440440

441-
## Extensibility
441+
## <a name="configExtensibility" />Extensibility
442442
Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown property.
443443
Instead they MUST ignore unknown properties.
444444

‎implementations.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
1-
# Implementations
1+
# <a name="implementations" />Implementations
22

33
The following sections link to associated projects, some of which are maintained by the OCI and some of which are maintained by external organizations.
44
If you know of any associated projects that are not listed here, please file a pull request adding a link to that project.
55

6-
## Runtime (Container)
6+
## <a name"implementationsRuntimeContainer" />Runtime (Container)
77

88
* [opencontainers/runc](https://github.com/opencontainers/runc) - Reference implementation of OCI runtime
99

10-
## Runtime (Virtual Machine)
10+
## <a name="implementationsRuntimeVirtualMachine" />Runtime (Virtual Machine)
1111

1212
* [hyperhq/runv](https://github.com/hyperhq/runv) - Hypervisor-based runtime for OCI
1313
* [01org/cc-oci-runtime](https://github.com/01org/cc-oci-runtime) - Hypervisor-based OCI runtime for Intel® Architecture
1414

15-
## Testing & Tools
15+
## <a name="implementationsTestingTools" />Testing & Tools
1616

1717
* [kunalkushwaha/octool](https://github.com/kunalkushwaha/octool) - A config linter and validator.
1818
* [huawei-openlab/oct](https://github.com/huawei-openlab/oct) - Open Container Testing framework for OCI configuration and runtime

‎project.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Project docs
1+
# <a name="projectDocs" />Project docs
22

3-
## Release Process
3+
## <a name="projectReleaseProcess" />Release Process
44

55
* Increment version in [`specs-go/version.go`](specs-go/version.go)
66
* `git commit` version increment

0 commit comments

Comments
 (0)