Skip to content

config-vm: Recycle the 'process' schema #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

config-vm: Recycle the 'process' schema #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
edd501a
config-vm: Recycle the 'process' schema
wking Mar 8, 2018
96c89b2
WIP: Copy/paste new Markdown and Go for hypervisor
wking Mar 8, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 88 additions & 8 deletions config-vm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,87 @@ The virtual-machine container specification provides additional configuration fo

## <a name="HypervisorObject" /> Hypervisor Object

**`hypervisor`** (object, OPTIONAL) specifies details of the hypervisor that manages the container virtual machine.
* **`path`** (string, REQUIRED) path to the hypervisor binary that manages the container virtual machine.
This value MUST be an absolute path in the [runtime mount namespace](glossary.md#runtime-namespace).
* **`parameters`** (array of strings, OPTIONAL) specifies an array of parameters to pass to the hypervisor.
**`hypervisor`** (object, OPTIONAL) configures the hypervisor process.
The schema is a subset of the [`process`](config.md#process) schema with the terminal properties `terminal` and `consoleSize` removed.

* **`cwd`** (string, REQUIRED) is the working directory that will be set for the executable.
This value MUST be an absolute path.
* **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2008's `environ`][ieee-1003.1-2008-xbd-c8.1_2].
* **`args`** (array of strings, REQUIRED) with similar semantics to [IEEE Std 1003.1-2008 `execvp`'s *argv*][ieee-1003.1-2008-functions-exec_2].
This specification extends the IEEE standard in that at least one entry is REQUIRED, and that entry is used with the same semantics as `execvp`'s *file*.

### <a name="HypervisorPOSIXProcess" />POSIX process

For systems that support POSIX rlimits (for example Linux and Solaris), the `hypervisor` object supports the following process-specific properties:

* **`rlimits`** (array of objects, OPTIONAL) allows setting resource limits for the process.
Each entry has the following structure:

* **`type`** (string, REQUIRED) the platform resource being limited.
* Linux: valid values are defined in the [`getrlimit(2)`][getrlimit.2_2] man page, such as `RLIMIT_MSGQUEUE`.
* Solaris: valid values are defined in the [`getrlimit(3)`][getrlimit.3_2] man page, such as `RLIMIT_CORE`.

The runtime MUST [generate an error](runtime.md#errors) for any values which cannot be mapped to a relevant kernel interface.
For each entry in `rlimits`, a [`getrlimit(3)`][getrlimit.3_2] on `type` MUST succeed.
For the following properties, `rlim` refers to the status returned by the `getrlimit(3)` call.

* **`soft`** (uint64, REQUIRED) the value of the limit enforced for the corresponding resource.
`rlim.rlim_cur` MUST match the configured value.
* **`hard`** (uint64, REQUIRED) the ceiling for the soft limit that could be set by an unprivileged process.
`rlim.rlim_max` MUST match the configured value.
Only a privileged process (e.g. one with the `CAP_SYS_RESOURCE` capability) can raise a hard limit.

If `rlimits` contains duplicated entries with same `type`, the runtime MUST [generate an error](runtime.md#errors).

### <a name="HypervisorLinuxProcess" />Linux Process

For Linux-based systems, the `hypervisor` object supports the following process-specific properties.

* **`apparmorProfile`** (string, OPTIONAL) specifies the name of the AppArmor profile for the process.
For more information about AppArmor, see [AppArmor documentation][apparmor_2].
* **`capabilities`** (object, OPTIONAL) is an object containing arrays that specifies the sets of capabilities for the process.
Valid values are defined in the [capabilities(7)][capabilities.7_2] man page, such as `CAP_CHOWN`.
Any value which cannot be mapped to a relevant kernel interface MUST cause an error.
`capabilities` contains the following properties:

* **`effective`** (array of strings, OPTIONAL) the `effective` field is an array of effective capabilities that are kept for the process.
* **`bounding`** (array of strings, OPTIONAL) the `bounding` field is an array of bounding capabilities that are kept for the process.
* **`inheritable`** (array of strings, OPTIONAL) the `inheritable` field is an array of inheritable capabilities that are kept for the process.
* **`permitted`** (array of strings, OPTIONAL) the `permitted` field is an array of permitted capabilities that are kept for the process.
* **`ambient`** (array of strings, OPTIONAL) the `ambient` field is an array of ambient capabilities that are kept for the process.
* **`noNewPrivileges`** (bool, OPTIONAL) setting `noNewPrivileges` to true prevents the process from gaining additional privileges.
As an example, the [`no_new_privs`][no-new-privs_2] article in the kernel documentation has information on how this is achieved using a `prctl` system call on Linux.
* **`oomScoreAdj`** *(int, OPTIONAL)* adjusts the oom-killer score in `[pid]/oom_score_adj` for the process's `[pid]` in a [proc pseudo-filesystem][proc_3].
If `oomScoreAdj` is set, the runtime MUST set `oom_score_adj` to the given value.
If `oomScoreAdj` is not set, the runtime MUST NOT change the value of `oom_score_adj`.
* **`selinuxLabel`** (string, OPTIONAL) specifies the SELinux label for the process.
For more information about SELinux, see [SELinux documentation][selinux_2].

### <a name="HypervisorUser" />User

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

#### <a name="HypervisorPOSIXUser" />POSIX-platform User

For POSIX platforms the `user` structure has the following fields:

* **`uid`** (int, REQUIRED) specifies the user ID in the [container namespace](glossary.md#container-namespace).
* **`gid`** (int, REQUIRED) specifies the group ID in the [container namespace](glossary.md#container-namespace).
* **`additionalGids`** (array of ints, OPTIONAL) specifies additional group IDs in the [container namespace](glossary.md#container-namespace) to be added to the process.

_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)_

#### <a name="HypervisorWindowsUser" />Windows User

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

* **`username`** (string, OPTIONAL) specifies the user name for the process.

### Example

```json
"hypervisor": {
"path": "/path/to/vmm",
"parameters": ["opts1=foo", "opts2=bar"]
"args": ["/path/to/vmm", "opts1=foo", "opts2=bar"]
}
```

Expand Down Expand Up @@ -61,8 +131,18 @@ This image contains the root filesystem that the virtual machine **`kernel`** wi
}
```

[raw-image-format]: https://en.wikipedia.org/wiki/IMG_(file_format)
[apparmor_2]: https://wiki.ubuntu.com/AppArmor
[ieee-1003.1-2008-functions-exec_2]: http://pubs.opengroup.org/onlinepubs/9699919799/fu
[ieee-1003.1-2008-xbd-c8.1_2]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_01
[no-new-privs_2]: https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt
[proc_3]: https://www.kernel.org/doc/Documentation/filesystems/proc.txt
[qcow2-image-format]: https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/interop/qcow2.txt;hb=HEAD
[raw-image-format]: https://en.wikipedia.org/wiki/IMG_(file_format)
[selinux_2]:http://selinuxproject.org/page/Main_Page
[vdi-image-format]: https://forensicswiki.org/wiki/Virtual_Disk_Image_(VDI)
[vmdk-image-format]: http://www.vmware.com/app/vmdk/?src=vmdk
[vhd-image-format]: https://github.com/libyal/libvhdi/blob/master/documentation/Virtual%20Hard%20Disk%20(VHD)%20image%20format.asciidoc
[vmdk-image-format]: http://www.vmware.com/app/vmdk/?src=vmdk

[capabilities.7_2]: http://man7.org/linux/man-pages/man7/capabilities.7.html
[getrlimit.2_2]: http://man7.org/linux/man-pages/man2/getrlimit.2.html
[getrlimit.3_2]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/getrlimit.html
107 changes: 1 addition & 106 deletions schema/config-schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,112 +48,7 @@
}
},
"process": {
"type": "object",
"required": [
"cwd",
"args"
],
"properties": {
"args": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
},
"consoleSize": {
"type": "object",
"required": [
"height",
"width"
],
"properties": {
"height": {
"$ref": "defs.json#/definitions/uint64"
},
"width": {
"$ref": "defs.json#/definitions/uint64"
}
}
},
"cwd": {
"type": "string"
},
"env": {
"$ref": "defs.json#/definitions/Env"
},
"terminal": {
"type": "boolean"
},
"user": {
"type": "object",
"properties": {
"uid": {
"$ref": "defs.json#/definitions/UID"
},
"gid": {
"$ref": "defs.json#/definitions/GID"
},
"additionalGids": {
"$ref": "defs.json#/definitions/ArrayOfGIDs"
},
"username": {
"type": "string"
}
}
},
"capabilities": {
"type": "object",
"properties": {
"bounding": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
},
"permitted": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
},
"effective": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
},
"inheritable": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
},
"ambient": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
}
}
},
"apparmorProfile": {
"type": "string"
},
"oomScoreAdj": {
"type": "integer"
},
"selinuxLabel": {
"type": "string"
},
"noNewPrivileges": {
"type": "boolean"
},
"rlimits": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"soft",
"hard"
],
"properties": {
"hard": {
"$ref": "defs.json#/definitions/uint64"
},
"soft": {
"$ref": "defs.json#/definitions/uint64"
},
"type": {
"type": "string",
"pattern": "^RLIMIT_[A-Z]+$"
}
}
}
}
}
"$ref": "defs.json#/definitions/Process"
},
"linux": {
"$ref": "config-linux.json#/linux"
Expand Down
13 changes: 1 addition & 12 deletions schema/config-vm.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,7 @@
"properties": {
"hypervisor": {
"description": "hypervisor config used by VM-based containers",
"type": "object",
"required": [
"path"
],
"properties": {
"path": {
"$ref": "defs.json#/definitions/FilePath"
},
"parameters": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
}
}
"$ref": "defs.json#/definitions/Process"
},
"kernel": {
"description": "kernel config used by VM-based containers",
Expand Down
108 changes: 108 additions & 0 deletions schema/defs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,114 @@
"Env": {
"$ref": "#/definitions/ArrayOfStrings"
},
"Process": {
"type": "object",
"required": [
"cwd",
"args"
],
"properties": {
"args": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
},
"consoleSize": {
"type": "object",
"required": [
"height",
"width"
],
"properties": {
"height": {
"$ref": "defs.json#/definitions/uint64"
},
"width": {
"$ref": "defs.json#/definitions/uint64"
}
}
},
"cwd": {
"type": "string"
},
"env": {
"$ref": "defs.json#/definitions/Env"
},
"terminal": {
"type": "boolean"
},
"user": {
"type": "object",
"properties": {
"uid": {
"$ref": "defs.json#/definitions/UID"
},
"gid": {
"$ref": "defs.json#/definitions/GID"
},
"additionalGids": {
"$ref": "defs.json#/definitions/ArrayOfGIDs"
},
"username": {
"type": "string"
}
}
},
"capabilities": {
"type": "object",
"properties": {
"bounding": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
},
"permitted": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
},
"effective": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
},
"inheritable": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
},
"ambient": {
"$ref": "defs.json#/definitions/ArrayOfStrings"
}
}
},
"apparmorProfile": {
"type": "string"
},
"oomScoreAdj": {
"type": "integer"
},
"selinuxLabel": {
"type": "string"
},
"noNewPrivileges": {
"type": "boolean"
},
"rlimits": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"soft",
"hard"
],
"properties": {
"hard": {
"$ref": "defs.json#/definitions/uint64"
},
"soft": {
"$ref": "defs.json#/definitions/uint64"
},
"type": {
"type": "string",
"pattern": "^RLIMIT_[A-Z]+$"
}
}
}
}
}
},
"Hook": {
"type": "object",
"properties": {
Expand Down
Loading