Skip to content

Commit 7ac41c6

Browse files
author
Brandon Philips
committed
config.md: reformat into a standard style
Cleanup all of the properties into a consistent style for readability and easier additions later.
1 parent f2569d1 commit 7ac41c6

File tree

1 file changed

+87
-96
lines changed

1 file changed

+87
-96
lines changed

‎config.md‎

Lines changed: 87 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,149 +1,140 @@
11
# Configuration file
22

3-
The container’s top-level directory MUST contain a configuration file called config.json. The configuration file MUST comply with the Open Container Configuration JSON Schema attached to this document. For now the schema is defined in [spec.go](https://github.com/opencontainers/runc/blob/master/spec.go) and [spec_linux.go](https://github.com/opencontainers/runc/blob/master/spec_linux.go), this will be moved to a JSON schema overtime.
3+
The container’s top-level directory MUST contain a configuration file called `config.json`.
4+
For now the schema is defined in [spec.go](https://github.com/opencontainers/runc/blob/master/spec.go) and [spec_linux.go](https://github.com/opencontainers/runc/blob/master/spec_linux.go), this will be moved to a JSON schema overtime.
45

5-
The configuration file contains metadata necessary to implement standard operations against the container. This includes process to run, environment variables to inject, sandboxing features to use, etc.
6+
The configuration file contains metadata necessary to implement standard operations against the container.
7+
This includes the process to run, environment variables to inject, sandboxing features to use, etc.
68

79
Below is a detailed description of each field defined in the configuration format.
810

911
## Manifest version
1012

11-
The `version` element specifies the version of the OCF specification which the container complies with. If the container is compliant with multiple versions, it SHOULD advertise the most recent known version to be supported.
13+
* **version** (string, required) specifies the version of the OCF specification which the container bundle complies with. If the container is compliant with multiple versions, it SHOULD advertise the most recent known version to be supported.
1214

1315
*Example*
16+
1417
```json
1518
"version": "1"
1619
```
1720

18-
## File system configuration
19-
20-
Each container has exactly one *root filesystem*, and any number of optional *mounted filesystems*. Both need to be declared in the manifest.
21+
## Root Configuration
2122

22-
The path string element specifies the path to the root file system for the container, relative to the path where the manifest is. A directory MUST exist at the relative path declared by the field.
23-
24-
The readonly is an optional boolean element which defaults to false. If readonly is true then the root file system MUST be read-only inside the container.
23+
* **path** (string, required) Each container has exactly one *root filesystem*. The path string element specifies the path to the root file system for the container, relative to the path where the manifest is. A directory MUST exist at the relative path declared by the field.
24+
* **readonly** (bool, optional) If true then the root file system MUST be read-only inside the container. Defaults to false.
2525

2626
*Example*
27+
2728
```json
28-
"root": {
29-
"path": "rootfs",
30-
"readonly": true
31-
}
29+
"root": {
30+
"path": "rootfs",
31+
"readonly": true
32+
}
3233
```
3334

34-
Additional file systems can be declared as "mounts", declared by the array element mounts. 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)
35-
36-
type: 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
35+
## Mount Configuration
3736

38-
source: 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)
39-
40-
destination: where the file system is mounted in the container.
37+
Additional file systems can be declared as "mounts", declared by the array element mounts. 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)
4138

42-
options: in the fstab format [https://wiki.archlinux.org/index.php/Fstab](https://wiki.archlinux.org/index.php/Fstab).
39+
* **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
40+
* **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)
41+
* **destination** (string, required) where the file system is mounted in the container.
42+
* **options** (string, optional) in the fstab format [https://wiki.archlinux.org/index.php/Fstab](https://wiki.archlinux.org/index.php/Fstab).
4343

4444
*Example (Linux)*
4545

4646
```json
47-
"mounts": [
48-
{
49-
"type": "proc",
50-
"source": "proc",
51-
"destination": "/proc",
52-
"options": ""
53-
},
54-
{
55-
"type": "tmpfs",
56-
"source": "tmpfs",
57-
"destination": "/dev",
58-
"options": "nosuid,strictatime,mode=755,size=65536k"
59-
},
60-
{
61-
"type": "devpts",
62-
"source": "devpts",
63-
"destination": "/dev/pts",
64-
"options": "nosuid,noexec,newinstance,ptmxmode=0666,mode=0620,gid=5"
65-
},
66-
{
67-
"type": "tmpfs",
68-
"source": "shm",
69-
"destination": "/dev/shm",
70-
"options": "nosuid,noexec,nodev,mode=1777,size=65536k"
71-
},
72-
]
47+
"mounts": [
48+
{
49+
"type": "proc",
50+
"source": "proc",
51+
"destination": "/proc",
52+
"options": ""
53+
},
54+
{
55+
"type": "tmpfs",
56+
"source": "tmpfs",
57+
"destination": "/dev",
58+
"options": "nosuid,strictatime,mode=755,size=65536k"
59+
},
60+
{
61+
"type": "devpts",
62+
"source": "devpts",
63+
"destination": "/dev/pts",
64+
"options": "nosuid,noexec,newinstance,ptmxmode=0666,mode=0620,gid=5"
65+
},
66+
{
67+
"type": "tmpfs",
68+
"source": "shm",
69+
"destination": "/dev/shm",
70+
"options": "nosuid,noexec,nodev,mode=1777,size=65536k"
71+
},
72+
]
7373
```
7474

7575
*Example (Windows)*
76+
7677
```json
77-
"mounts": [
78-
{
79-
"type": "ntfs",
80-
"source": "\\?\Volume\{2eca078d-5cbc-43d3-aff8-7e8511f60d0e}\",
81-
"destination": "C:\Users\crosbymichael\My Fancy Mount Point\",
82-
"options": ""
83-
}
84-
]
78+
"mounts": [
79+
{
80+
"type": "ntfs",
81+
"source": "\\?\Volume\{2eca078d-5cbc-43d3-aff8-7e8511f60d0e}\",
82+
"destination": "C:\Users\crosbymichael\My Fancy Mount Point\",
83+
"options": ""
84+
}
85+
]
8586
```
8687

87-
See links for details about mountvol in Windows.
88+
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.
8889

89-
[https://msdn.microsoft.com/en-us/library/windows/desktop/aa365561(v=vs.85).aspx](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365561(v=vs.85).aspx)
90+
## Processes configuration
9091

91-
[http://ss64.com/nt/mountvol.html](http://ss64.com/nt/mountvol.html)
92-
93-
### Processes configuration
94-
95-
- Command-line arguments
96-
- Terminal allocation
97-
- User ID
98-
- Environment variables
99-
- Working directory
92+
* **terminal** (bool, optional) specifies whether you want a terminal attached to that process. Defaults to false.
93+
* **user** (string, required) indicates the user which the process will run as.
94+
* **cwd** (string, optional) is the working directory that will be set for the executable.
95+
* **env** (array of strings, optional) contains a list of variables that will be set in the processes environment prior to execution. Elements in the array are specified as Strings in the form "KEY=value". The left hand side must consist solely of letters, digits, and underscores '_' as outlined in [IEEE Std 1003.1-2001](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html).
96+
* **args** (string, required) executable to launch and any flags as an array. The executable is the first element and must be available at the given path inside of the rootfs. If the executable path is not an absoulte path then the search $PATH is interpreted to find the executable.
10097

10198
*Example*
99+
102100
```json
103-
"process": {
104-
"terminal": true,
105-
"user": "daemon",
106-
"args": [
107-
"sh"
108-
],
109-
"env": [
110-
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
111-
"TERM=xterm"
112-
],
113-
"cwd": ""
114-
}
101+
"process": {
102+
"terminal": true,
103+
"user": "daemon",
104+
"env": [
105+
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
106+
"TERM=xterm"
107+
],
108+
"cwd": "",
109+
"args": [
110+
"sh"
111+
]
112+
}
115113
```
116114

117-
The command to start a process is specified in an array of args. It will be run in the working directory specified in the string cwd.
118-
119-
Environment variables are specified in an array called env.
120115

121-
Elements in the array are specified as Strings in the form "KEY=value"
116+
## Hostname
122117

123-
The user inside the container under which the process is running is specified under the user key.
124-
125-
terminal is a boolean that lets you specify whether you want a terminal attached to that process.
126-
127-
hostname is a string specifying the hostname for that container as it is accessible to processes running in it.
118+
* **hostname** (string, optional) as it is accessible to processes running inside.
128119

129120
*Example*
121+
130122
```json
131-
"hostname": "mrsdalloway"
123+
"hostname": "mrsdalloway"
132124
```
133125

134126
## Machine-specific configuration
135127

128+
* **os** (string, required) specifies the operating system family this image must run on. Values for arch must be in the list specified by the Go Language document for [$GOOS](https://golang.org/doc/install/source#environment).
129+
* **arch** (string, required) specifies the instruction set for which the binaries in the image have been compiled. Values for arch must be in the list specified by the Go Language document for [$GOARCH](https://golang.org/doc/install/source#environment).
130+
136131
```json
137-
"platform": {
138-
"os": "linux",
139-
"arch": "amd64"
140-
}
132+
"platform": {
133+
"os": "linux",
134+
"arch": "amd64"
135+
}
141136
```
142137

143-
os specifies the operating system family this image must run on.
144-
145-
arch specifies the instruction set for which the binaries in the image have been compiled.
138+
Interpretation of the platform section of the JSON file is used to find which platform specific section may be availble in the document. For example if `os` is set to `linux` then the `linux` JSON object SHOULD be found in the `config.json`.
146139

147-
values for os and arch must be in the list specified by the Go Language documentation for $GOOS and $GOARCH https://golang.org/doc/install/source#environment
148140

149-
OS or architecture specific settings can be added in the json file. They will be interpreted by the implementation depending on the os and arch values specified at the top of the manifest.

0 commit comments

Comments
 (0)