*: flatten platform dependent source

This introduces verbiage of fields that may occur in json (technically
optional), but is required on certain platforms (e.g. Linux).

The JSON document will look the same as it presently does, but now the
reference source compiles regardless of platform.

Not adding a "name" string to the user sturct, as that is not a
requirement yet.

In the event a windows runtime shows up, I could imagine an `sid` on the
user struct, but we'll get to that when it happens.

Closes opencontainers#135
Related to opencontainers#166

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

Makefile

@@ -11,7 +11,6 @@ DOC_FILES := \
 	runtime.md \
 	runtime-linux.md \
 	config.md \
-	config-linux.md \
 	runtime-config.md \
 	runtime-config-linux.md \
 	glossary.md

config.go

@@ -16,6 +16,9 @@ type Spec struct {
 	Hostname string `json:"hostname,omitempty"`
 	// Mounts profile configuration for adding mounts to the container's filesystem.
 	Mounts []MountPoint `json:"mounts"`
+
+	// Linux is platform specific configuration for linux based containers. (this field is platform dependent)
+	Linux Linux `json:"linux,omitempty" platform:"linux"`
 }
 
 // Process contains information to start a specific application inside the container.
@@ -33,6 +36,17 @@ type Process struct {
 	Cwd string `json:"cwd"`
 }
 
+// User specifies linux specific user and group information for the container's
+// main process.
+type User struct {
+	// UID is the user ID the Process is executed as. (this field is platform dependent)
+	UID uint32 `json:"uid,omitempty" platform:"linux"`
+	// GID is the group ID the Process is executed as. (this field is platform dependent)
+	GID uint32 `json:"gid,omitempty" platform:"linux"`
+	// AdditionalGids are additional group ids set for the container's process. (this field is platform dependent)
+	AdditionalGids []uint32 `json:"additionalGids,omitempty" platform:"linux"`
+}
+
 // Root contains information about the container's root filesystem on the host.
 type Root struct {
 	// Path is the absolute path to the container's root filesystem.
@@ -57,3 +71,9 @@ type MountPoint struct {
 	// 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.
 	Path string `json:"path"`
 }
+
+// Linux contains platform specific configuration for linux based containers.
+type Linux struct {
+	// Capabilities are linux capabilities that are kept for the container.
+	Capabilities []string `json:"capabilities"`
+}

config.md

@@ -28,10 +28,10 @@ Each container has exactly one *root filesystem*, specified in the *root* object
 *Example*
 
 ```json
-"root": {
+  "root": {
     "path": "rootfs",
     "readonly": true
-}
+  }
 ```
 
 ## Mount Points
@@ -46,24 +46,24 @@ The runtime MUST mount entries in the listed order.
 *Example*
 
 ```json
-"mounts": [
+  "mounts": [
     {
-        "name": "proc",
-        "path": "/proc"
+      "name": "proc",
+      "path": "/proc"
     },
     {
-        "name": "dev",
-        "path": "/dev"
+      "name": "dev",
+      "path": "/dev"
     },
     {
-        "name": "devpts",
-        "path": "/dev/pts"
+      "name": "devpts",
+      "path": "/dev/pts"
     },
     {
-        "name": "data",
-        "path": "/data"
+      "name": "data",
+      "path": "/data"
     }
-]
+  ]
 ```
 
 ## Process configuration
@@ -74,11 +74,11 @@ The runtime MUST mount entries in the listed order.
 * **`args`** (string, required) executable to launch and any flags as an array. The executable is the first element and must be available at the given path inside of the rootfs. If the executable path is not an absolute path then the search $PATH is interpreted to find the executable.
 
 The user for the process is a platform-specific structure that allows specific control over which user the process runs as.
-For Linux-based systems the user structure has the following fields:
+The user structure has the following fields:
 
-* **`uid`** (int, required) specifies the user id.
-* **`gid`** (int, required) specifies the group id.
-* **`additionalGids`** (array of ints, optional) specifies additional group ids to be added to the process.
+* **`uid`** (int, required on Linux) specifies the user id.
+* **`gid`** (int, required on Linux) specifies the group id.
+* **`additionalGids`** (array of ints, optional on Linux) specifies additional group ids to be added to the process.
 
 *Example (Linux)*
 
@@ -101,7 +101,6 @@ For Linux-based systems the user structure has the following fields:
 }
 ```
 
-
 ## Hostname
 
 * **`hostname`** (string, optional) as it is accessible to processes running inside.  On Linux, you can only set this if your bundle creates a new [UTS namespace][uts-namespace].
@@ -117,6 +116,8 @@ For Linux-based systems the user structure has the following fields:
 * **`os`** (string, required) specifies the operating system family this image must run on. Values for os must be in the list specified by the Go Language document for [`$GOOS`](https://golang.org/doc/install/source#environment).
 * **`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).
 
+*Example*
+
 ```json
 "platform": {
     "os": "linux",
@@ -125,6 +126,46 @@ For Linux-based systems the user structure has the following fields:
 ```
 
 Interpretation of the platform section of the JSON file is used to find which platform-specific sections may be available in the document.
-For example, if `os` is set to `linux`, then a JSON object conforming to the [Linux-specific schema](config-linux.md) SHOULD be found at the key `linux` in the `config.json`.
+For example, if `os` is set to `linux`, then a JSON object conforming to the [Linux-specific schema](#linux-specific-container-configuration) SHOULD be found at the key `linux` in the `config.json`.
+
+## Linux-specific Container Configuration
+
+The Linux container specification.
+uses various kernel features like namespaces, cgroups, capabilities, LSM, and file system jails to fulfill the spec.
+
+### Capabilities
+
+Capabilities is an array that specifies Linux capabilities that can be provided to the process inside the container.
+Valid values are the strings for capabilities defined in [the man page](http://man7.org/linux/man-pages/man7/capabilities.7.html)
+
+```json
+  "capabilities": [
+    "CAP_AUDIT_WRITE",
+    "CAP_KILL",
+    "CAP_NET_BIND_SERVICE"
+  ]
+```
+
+### Default Devices and File Systems
+
+The Linux ABI includes both syscalls and several special file paths.
+Applications expecting a Linux environment will very likely expect these files paths to be setup correctly.
+
+The following devices and filesystems MUST be made available in each application's filesystem
+
+|     Path     |  Type  |  Notes  |
+| ------------ | ------ | ------- |
+| /proc        | [procfs](https://www.kernel.org/doc/Documentation/filesystems/proc.txt)    | |
+| /sys         | [sysfs](https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt)    | |
+| /dev/null    | [device](http://man7.org/linux/man-pages/man4/null.4.html)                 | |
+| /dev/zero    | [device](http://man7.org/linux/man-pages/man4/zero.4.html)                 | |
+| /dev/full    | [device](http://man7.org/linux/man-pages/man4/full.4.html)                 | |
+| /dev/random  | [device](http://man7.org/linux/man-pages/man4/random.4.html)               | |
+| /dev/urandom | [device](http://man7.org/linux/man-pages/man4/random.4.html)               | |
+| /dev/tty     | [device](http://man7.org/linux/man-pages/man4/tty.4.html)                  | |
+| /dev/console | [device](http://man7.org/linux/man-pages/man4/console.4.html)              | |
+| /dev/pts     | [devpts](https://www.kernel.org/doc/Documentation/filesystems/devpts.txt)  | |
+| /dev/ptmx    | [device](https://www.kernel.org/doc/Documentation/filesystems/devpts.txt)  | Bind-mount or symlink of /dev/pts/ptmx |
+| /dev/shm     | [tmpfs](https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt)    | |
 
 [uts-namespace]: http://man7.org/linux/man-pages/man7/namespaces.7.html