From 4d30c413b34bcc35d38bec810d1770d99dc9b694 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 28 Aug 2015 21:54:33 -0700 Subject: [PATCH 01/11] Rename Go and Markdown files to match their associated JSON MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Before this commit we had the following mapping: * config.md → config.go (config.json) * config-linux.md → config_linux.go (config.json's "linux") * runtime-config.md → runtime_config.go (runtime.json) * runtime.md → lifecycle and runtime_config.go (runtime.json's "prestart" and "poststop" hooks) * runtime-config-linux.md → runtime_config_linux.go (runtime.json's "linux") This commit: * replaces underscores with hyphens, and: * renames Go and Markdown files so: * the docs for ${X}.json are in ${X}.md * the platform-independent types for ${X}.json are in ${X}.go * the docs for ${X}.json's ${PLATFORM} section are in ${X}-${PLATFORM}.md * the platform-dependent types for ${X}.json's ${PLATFORM} section are in ${X}-${PLATFORM}.go Signed-off-by: W. Trevor King --- README.md | 2 +- config_linux.go => config-linux.go | 0 lifecycle-linux.md | 7 + lifecycle.md | 59 ++++++ runtime-config-linux.md | 195 ------------------- runtime-config.md | 54 ------ runtime_config_linux.go => runtime-linux.go | 0 runtime-linux.md | 197 +++++++++++++++++++- runtime_config.go => runtime.go | 0 runtime.md | 93 +++++---- 10 files changed, 304 insertions(+), 303 deletions(-) rename config_linux.go => config-linux.go (100%) create mode 100644 lifecycle-linux.md create mode 100644 lifecycle.md delete mode 100644 runtime-config-linux.md delete mode 100644 runtime-config.md rename runtime_config_linux.go => runtime-linux.go (100%) rename runtime_config.go => runtime.go (100%) diff --git a/README.md b/README.md index a98dc4acd..7af9e8a2e 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Table of Contents - [Filesystem Bundle](bundle.md) - [Container Configuration](config.md) - [Linux Specific Configuration](config-linux.md) -- [Runtime and Lifecycle](runtime.md) +- [Runtime and Lifecycle](lifecycle.md) - [Implementations](implementations.md) ## Use Cases diff --git a/config_linux.go b/config-linux.go similarity index 100% rename from config_linux.go rename to config-linux.go diff --git a/lifecycle-linux.md b/lifecycle-linux.md new file mode 100644 index 000000000..545af8103 --- /dev/null +++ b/lifecycle-linux.md @@ -0,0 +1,7 @@ +## File descriptors + +By default, only the `stdin`, `stdout` and `stderr` file descriptors are kept open for the application by the runtime. + +The runtime may pass additional file descriptors to the application to support features such as [socket activation](http://0pointer.de/blog/projects/socket-activated-containers.html). + +Some of the file descriptors may be redirected to `/dev/null` even though they are open. diff --git a/lifecycle.md b/lifecycle.md new file mode 100644 index 000000000..dbd055f04 --- /dev/null +++ b/lifecycle.md @@ -0,0 +1,59 @@ +# Runtime and Lifecycle + +## Lifecycle + +### Create + +Creates the container: file system, namespaces, cgroups, capabilities. + +### Start (process) + +Runs a process in a container. Can be invoked several times. + +### Stop (process) + +Not sure we need that from runc cli. Process is killed from the outside. + +This event needs to be captured by runc to run onstop event handlers. + +## Hooks +Hooks allow one to run code before/after various lifecycle events of the container. +The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work. + +Hook paths are absolute and are executed from the host's filesystem. + +### Pre-start +The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed. +They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container. +In Linux, for e.g., the network namespace could be configured in this hook. + +If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down. + +### Post-stop +The post-stop hooks are called after the container process is stopped. Cleanup or debugging could be performed in such a hook. +If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed. + +*Example* + +```json + "hooks" : { + "prestart": [ + { + "path": "/usr/bin/fix-mounts", + "args": ["arg1", "arg2"], + "env": [ "key1=value1"] + }, + { + "path": "/usr/bin/setup-network" + } + ], + "poststop": [ + { + "path": "/usr/sbin/cleanup.sh", + "args": ["-f"] + } + ] + } +``` + +`path` is required for a hook. `args` and `env` are optional. diff --git a/runtime-config-linux.md b/runtime-config-linux.md deleted file mode 100644 index 1cabc6156..000000000 --- a/runtime-config-linux.md +++ /dev/null @@ -1,195 +0,0 @@ -## Namespaces - -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. -Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes. -For more information, see [the man page](http://man7.org/linux/man-pages/man7/namespaces.7.html). - -Namespaces are specified in the spec as an array of entries. -Each entry has a type field with possible values described below and an optional path element. -If a path is specified, that particular file is used to join that type of namespace. - -```json - "namespaces": [ - { - "type": "pid", - "path": "/proc/1234/ns/pid" - }, - { - "type": "net", - "path": "/var/run/netns/neta" - }, - { - "type": "mnt", - }, - { - "type": "ipc", - }, - { - "type": "uts", - }, - { - "type": "user", - }, - ] -``` - -#### Namespace types - -* **pid** processes inside the container will only be able to see other processes inside the same container. -* **network** the container will have its own network stack. -* **mnt** the container will have an isolated mount table. -* **ipc** processes inside the container will only be able to communicate to other processes inside the same -container via system level IPC. -* **uts** the container will be able to have its own hostname and domain name. -* **user** the container will be able to remap user and group IDs from the host to local users and groups -within the container. - -### Access to devices - -Devices is an array specifying the list of devices to be created in the container. -Next parameters can be specified: - -* type - type of device: 'c', 'b', 'u' or 'p'. More info in `man mknod` -* path - full path to device inside container -* major, minor - major, minor numbers for device. More info in `man mknod`. - There is special value: `-1`, which means `*` for `device` - cgroup setup. -* permissions - cgroup permissions for device. A composition of 'r' - (read), 'w' (write), and 'm' (mknod). -* fileMode - file mode for device file -* uid - uid of device owner -* gid - gid of device owner - -```json - "devices": [ - { - "path": "/dev/random", - "type": "c", - "major": 1, - "minor": 8, - "permissions": "rwm", - "fileMode": 0666, - "uid": 0, - "gid": 0 - }, - { - "path": "/dev/urandom", - "type": "c", - "major": 1, - "minor": 9, - "permissions": "rwm", - "fileMode": 0666, - "uid": 0, - "gid": 0 - }, - { - "path": "/dev/null", - "type": "c", - "major": 1, - "minor": 3, - "permissions": "rwm", - "fileMode": 0666, - "uid": 0, - "gid": 0 - }, - { - "path": "/dev/zero", - "type": "c", - "major": 1, - "minor": 5, - "permissions": "rwm", - "fileMode": 0666, - "uid": 0, - "gid": 0 - }, - { - "path": "/dev/tty", - "type": "c", - "major": 5, - "minor": 0, - "permissions": "rwm", - "fileMode": 0666, - "uid": 0, - "gid": 0 - }, - { - "path": "/dev/full", - "type": "c", - "major": 1, - "minor": 7, - "permissions": "rwm", - "fileMode": 0666, - "uid": 0, - "gid": 0 - } - ] -``` - -## Control groups - -Also known as cgroups, they are used to restrict resource usage for a container and handle -device access. cgroups provide controls to restrict cpu, memory, IO, and network for -the container. For more information, see the [kernel cgroups documentation](https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt). - -## Sysctl - -sysctl allows kernel parameters to be modified at runtime for the container. -For more information, see [the man page](http://man7.org/linux/man-pages/man8/sysctl.8.html) - -```json - "sysctl": { - "net.ipv4.ip_forward": "1", - "net.core.somaxconn": "256" - } -``` - -## Rlimits - -```json - "rlimits": [ - { - "type": "RLIMIT_NPROC", - "soft": 1024, - "hard": 102400 - } - ] -``` - -rlimits allow setting resource limits. The type is from the values defined in [the man page](http://man7.org/linux/man-pages/man2/setrlimit.2.html). The kernel enforces the soft limit for a resource while the hard limit acts as a ceiling for that value that could be set by an unprivileged process. - -## SELinux process label - -SELinux process label specifies the label with which the processes in a container are run. -For more information about SELinux, see [Selinux documentation](http://selinuxproject.org/page/Main_Page) -```json - "selinuxProcessLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675" -``` - -## Apparmor profile - -Apparmor profile specifies the name of the apparmor profile that will be used for the container. -For more information about Apparmor, see [Apparmor documentation](https://wiki.ubuntu.com/AppArmor) - -```json - "apparmorProfile": "acme_secure_profile" -``` - -## seccomp - -Seccomp provides application sandboxing mechanism in the Linux kernel. -Seccomp configuration allows one to configure actions to take for matched syscalls and furthermore also allows -matching on values passed as arguments to syscalls. -For more information about Seccomp, see [Seccomp kernel documentation](https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt) -The actions and operators are strings that match the definitions in seccomp.h from [libseccomp](https://github.com/seccomp/libseccomp) and are translated to corresponding values. - -```json - "seccomp": { - "defaultAction": "SCMP_ACT_ALLOW", - "syscalls": [ - { - "name": "getcwd", - "action": "SCMP_ACT_ERRNO" - } - ] - } -``` diff --git a/runtime-config.md b/runtime-config.md deleted file mode 100644 index 6074e98bf..000000000 --- a/runtime-config.md +++ /dev/null @@ -1,54 +0,0 @@ -## Mount Configuration - -Additional filesystems can be declared as "mounts", specified in the *mounts* array. 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) - -* **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 -* **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) -* **destination** (string, required) where the source filesystem is mounted relative to the container rootfs. -* **options** (list of strings, optional) in the fstab format [https://wiki.archlinux.org/index.php/Fstab](https://wiki.archlinux.org/index.php/Fstab). - -*Example (Linux)* - -```json -"mounts": [ - { - "type": "proc", - "source": "proc", - "destination": "/proc", - "options": [] - }, - { - "type": "tmpfs", - "source": "tmpfs", - "destination": "/dev", - "options": ["nosuid","strictatime","mode=755","size=65536k"] - }, - { - "type": "devpts", - "source": "devpts", - "destination": "/dev/pts", - "options": ["nosuid","noexec","newinstance","ptmxmode=0666","mode=0620","gid=5"] - }, - { - "type": "bind", - "source": "/volumes/testing", - "destination": "/data", - "options": ["rbind","rw"] - } -] -``` - -*Example (Windows)* - -```json -"mounts": [ - { - "type": "ntfs", - "source": "\\\\?\\Volume\\{2eca078d-5cbc-43d3-aff8-7e8511f60d0e}\\", - "destination": "C:\\Users\\crosbymichael\\My Fancy Mount Point\\", - "options": [] - } -] -``` - -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. diff --git a/runtime_config_linux.go b/runtime-linux.go similarity index 100% rename from runtime_config_linux.go rename to runtime-linux.go diff --git a/runtime-linux.md b/runtime-linux.md index dcfa24eb4..1cabc6156 100644 --- a/runtime-linux.md +++ b/runtime-linux.md @@ -1,6 +1,195 @@ -## File descriptors -By default, only the `stdin`, `stdout` and `stderr` file descriptors are kept open for the application by the runtime. +## Namespaces -The runtime may pass additional file descriptors to the application to support features such as [socket activation](http://0pointer.de/blog/projects/socket-activated-containers.html). +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. +Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes. +For more information, see [the man page](http://man7.org/linux/man-pages/man7/namespaces.7.html). -Some of the file descriptors may be redirected to `/dev/null` even though they are open. +Namespaces are specified in the spec as an array of entries. +Each entry has a type field with possible values described below and an optional path element. +If a path is specified, that particular file is used to join that type of namespace. + +```json + "namespaces": [ + { + "type": "pid", + "path": "/proc/1234/ns/pid" + }, + { + "type": "net", + "path": "/var/run/netns/neta" + }, + { + "type": "mnt", + }, + { + "type": "ipc", + }, + { + "type": "uts", + }, + { + "type": "user", + }, + ] +``` + +#### Namespace types + +* **pid** processes inside the container will only be able to see other processes inside the same container. +* **network** the container will have its own network stack. +* **mnt** the container will have an isolated mount table. +* **ipc** processes inside the container will only be able to communicate to other processes inside the same +container via system level IPC. +* **uts** the container will be able to have its own hostname and domain name. +* **user** the container will be able to remap user and group IDs from the host to local users and groups +within the container. + +### Access to devices + +Devices is an array specifying the list of devices to be created in the container. +Next parameters can be specified: + +* type - type of device: 'c', 'b', 'u' or 'p'. More info in `man mknod` +* path - full path to device inside container +* major, minor - major, minor numbers for device. More info in `man mknod`. + There is special value: `-1`, which means `*` for `device` + cgroup setup. +* permissions - cgroup permissions for device. A composition of 'r' + (read), 'w' (write), and 'm' (mknod). +* fileMode - file mode for device file +* uid - uid of device owner +* gid - gid of device owner + +```json + "devices": [ + { + "path": "/dev/random", + "type": "c", + "major": 1, + "minor": 8, + "permissions": "rwm", + "fileMode": 0666, + "uid": 0, + "gid": 0 + }, + { + "path": "/dev/urandom", + "type": "c", + "major": 1, + "minor": 9, + "permissions": "rwm", + "fileMode": 0666, + "uid": 0, + "gid": 0 + }, + { + "path": "/dev/null", + "type": "c", + "major": 1, + "minor": 3, + "permissions": "rwm", + "fileMode": 0666, + "uid": 0, + "gid": 0 + }, + { + "path": "/dev/zero", + "type": "c", + "major": 1, + "minor": 5, + "permissions": "rwm", + "fileMode": 0666, + "uid": 0, + "gid": 0 + }, + { + "path": "/dev/tty", + "type": "c", + "major": 5, + "minor": 0, + "permissions": "rwm", + "fileMode": 0666, + "uid": 0, + "gid": 0 + }, + { + "path": "/dev/full", + "type": "c", + "major": 1, + "minor": 7, + "permissions": "rwm", + "fileMode": 0666, + "uid": 0, + "gid": 0 + } + ] +``` + +## Control groups + +Also known as cgroups, they are used to restrict resource usage for a container and handle +device access. cgroups provide controls to restrict cpu, memory, IO, and network for +the container. For more information, see the [kernel cgroups documentation](https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt). + +## Sysctl + +sysctl allows kernel parameters to be modified at runtime for the container. +For more information, see [the man page](http://man7.org/linux/man-pages/man8/sysctl.8.html) + +```json + "sysctl": { + "net.ipv4.ip_forward": "1", + "net.core.somaxconn": "256" + } +``` + +## Rlimits + +```json + "rlimits": [ + { + "type": "RLIMIT_NPROC", + "soft": 1024, + "hard": 102400 + } + ] +``` + +rlimits allow setting resource limits. The type is from the values defined in [the man page](http://man7.org/linux/man-pages/man2/setrlimit.2.html). The kernel enforces the soft limit for a resource while the hard limit acts as a ceiling for that value that could be set by an unprivileged process. + +## SELinux process label + +SELinux process label specifies the label with which the processes in a container are run. +For more information about SELinux, see [Selinux documentation](http://selinuxproject.org/page/Main_Page) +```json + "selinuxProcessLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675" +``` + +## Apparmor profile + +Apparmor profile specifies the name of the apparmor profile that will be used for the container. +For more information about Apparmor, see [Apparmor documentation](https://wiki.ubuntu.com/AppArmor) + +```json + "apparmorProfile": "acme_secure_profile" +``` + +## seccomp + +Seccomp provides application sandboxing mechanism in the Linux kernel. +Seccomp configuration allows one to configure actions to take for matched syscalls and furthermore also allows +matching on values passed as arguments to syscalls. +For more information about Seccomp, see [Seccomp kernel documentation](https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt) +The actions and operators are strings that match the definitions in seccomp.h from [libseccomp](https://github.com/seccomp/libseccomp) and are translated to corresponding values. + +```json + "seccomp": { + "defaultAction": "SCMP_ACT_ALLOW", + "syscalls": [ + { + "name": "getcwd", + "action": "SCMP_ACT_ERRNO" + } + ] + } +``` diff --git a/runtime_config.go b/runtime.go similarity index 100% rename from runtime_config.go rename to runtime.go diff --git a/runtime.md b/runtime.md index dbd055f04..6074e98bf 100644 --- a/runtime.md +++ b/runtime.md @@ -1,59 +1,54 @@ -# Runtime and Lifecycle +## Mount Configuration -## Lifecycle +Additional filesystems can be declared as "mounts", specified in the *mounts* array. 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) -### Create +* **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 +* **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) +* **destination** (string, required) where the source filesystem is mounted relative to the container rootfs. +* **options** (list of strings, optional) in the fstab format [https://wiki.archlinux.org/index.php/Fstab](https://wiki.archlinux.org/index.php/Fstab). -Creates the container: file system, namespaces, cgroups, capabilities. +*Example (Linux)* -### Start (process) - -Runs a process in a container. Can be invoked several times. - -### Stop (process) - -Not sure we need that from runc cli. Process is killed from the outside. - -This event needs to be captured by runc to run onstop event handlers. - -## Hooks -Hooks allow one to run code before/after various lifecycle events of the container. -The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work. - -Hook paths are absolute and are executed from the host's filesystem. - -### Pre-start -The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed. -They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container. -In Linux, for e.g., the network namespace could be configured in this hook. - -If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down. - -### Post-stop -The post-stop hooks are called after the container process is stopped. Cleanup or debugging could be performed in such a hook. -If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed. +```json +"mounts": [ + { + "type": "proc", + "source": "proc", + "destination": "/proc", + "options": [] + }, + { + "type": "tmpfs", + "source": "tmpfs", + "destination": "/dev", + "options": ["nosuid","strictatime","mode=755","size=65536k"] + }, + { + "type": "devpts", + "source": "devpts", + "destination": "/dev/pts", + "options": ["nosuid","noexec","newinstance","ptmxmode=0666","mode=0620","gid=5"] + }, + { + "type": "bind", + "source": "/volumes/testing", + "destination": "/data", + "options": ["rbind","rw"] + } +] +``` -*Example* +*Example (Windows)* ```json - "hooks" : { - "prestart": [ - { - "path": "/usr/bin/fix-mounts", - "args": ["arg1", "arg2"], - "env": [ "key1=value1"] - }, - { - "path": "/usr/bin/setup-network" - } - ], - "poststop": [ - { - "path": "/usr/sbin/cleanup.sh", - "args": ["-f"] - } - ] +"mounts": [ + { + "type": "ntfs", + "source": "\\\\?\\Volume\\{2eca078d-5cbc-43d3-aff8-7e8511f60d0e}\\", + "destination": "C:\\Users\\crosbymichael\\My Fancy Mount Point\\", + "options": [] } +] ``` -`path` is required for a hook. `args` and `env` are optional. +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. From 4cfa5841b3272baceae573feb00a306b2ca1b782 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 28 Aug 2015 22:02:22 -0700 Subject: [PATCH 02/11] Move hooks from lifecycle.md to runtime.md Hooks are only valid in runtime.json, so we should discuss them in the runtime.json docs. I'll add appropriate links from the lifecycle docs in a bit, but linking into runtime.json is poor enough that I think it deserves its own commit. The only change here besides the copy/paste is the addition of a blank line after the Markdown headers to match the rest of the documentation. Signed-off-by: W. Trevor King --- lifecycle.md | 42 ------------------------------------------ runtime.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 42 deletions(-) diff --git a/lifecycle.md b/lifecycle.md index dbd055f04..e5520dfbd 100644 --- a/lifecycle.md +++ b/lifecycle.md @@ -15,45 +15,3 @@ Runs a process in a container. Can be invoked several times. Not sure we need that from runc cli. Process is killed from the outside. This event needs to be captured by runc to run onstop event handlers. - -## Hooks -Hooks allow one to run code before/after various lifecycle events of the container. -The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work. - -Hook paths are absolute and are executed from the host's filesystem. - -### Pre-start -The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed. -They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container. -In Linux, for e.g., the network namespace could be configured in this hook. - -If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down. - -### Post-stop -The post-stop hooks are called after the container process is stopped. Cleanup or debugging could be performed in such a hook. -If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed. - -*Example* - -```json - "hooks" : { - "prestart": [ - { - "path": "/usr/bin/fix-mounts", - "args": ["arg1", "arg2"], - "env": [ "key1=value1"] - }, - { - "path": "/usr/bin/setup-network" - } - ], - "poststop": [ - { - "path": "/usr/sbin/cleanup.sh", - "args": ["-f"] - } - ] - } -``` - -`path` is required for a hook. `args` and `env` are optional. diff --git a/runtime.md b/runtime.md index 6074e98bf..d182c4169 100644 --- a/runtime.md +++ b/runtime.md @@ -1,3 +1,48 @@ +## Hooks + +Hooks allow one to run code before/after various lifecycle events of the container. +The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work. + +Hook paths are absolute and are executed from the host's filesystem. + +### Pre-start + +The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed. +They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container. +In Linux, for e.g., the network namespace could be configured in this hook. + +If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down. + +### Post-stop + +The post-stop hooks are called after the container process is stopped. Cleanup or debugging could be performed in such a hook. +If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed. + +*Example* + +```json + "hooks" : { + "prestart": [ + { + "path": "/usr/bin/fix-mounts", + "args": ["arg1", "arg2"], + "env": [ "key1=value1"] + }, + { + "path": "/usr/bin/setup-network" + } + ], + "poststop": [ + { + "path": "/usr/sbin/cleanup.sh", + "args": ["-f"] + } + ] + } +``` + +`path` is required for a hook. `args` and `env` are optional. + ## Mount Configuration Additional filesystems can be declared as "mounts", specified in the *mounts* array. 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) From c5305f9683b48dad183491228a6ef27a39c0289d Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 28 Aug 2015 23:40:46 -0700 Subject: [PATCH 03/11] bundle.md: Link to the runtime.json docs Just like we link to the config.json docs. Signed-off-by: W. Trevor King --- bundle.md | 1 + 1 file changed, 1 insertion(+) diff --git a/bundle.md b/bundle.md index 58f4146f6..fed726511 100644 --- a/bundle.md +++ b/bundle.md @@ -19,6 +19,7 @@ The `runtime.json` file contains settings that are host specific such as memory The goal is that the bundle can be moved as a unit to another machine and run the same application if `runtime.json` is removed or reconfigured. The syntax and semantics for `config.json` are described in [this specification](config.md). +The syntax and semantics for `runtime.json` are described in [this specification](runtime.md). A single `rootfs` directory MUST be in the same directory as the `config.json`. The names of the directories may be arbitrary, but users should consider using conventional names as in the example below. From fcd496c59637ccc770d7803fc50f7ad79eeb66ca Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 29 Aug 2015 00:09:19 -0700 Subject: [PATCH 04/11] README: Link to the runtime.json docs Just like we link to the config.json docs. Signed-off-by: W. Trevor King --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7af9e8a2e..f443afa5c 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,10 @@ This project is where the [Open Container Initiative](http://www.opencontainers. Table of Contents - [Filesystem Bundle](bundle.md) -- [Container Configuration](config.md) +- [Host-independent Container Configuration](config.md) - [Linux Specific Configuration](config-linux.md) +- [Host-specific Container Configuration](runtime.md) + - [Linux Specific Configuration](runtime-linux.md) - [Runtime and Lifecycle](lifecycle.md) - [Implementations](implementations.md) From 8dae07a7b2ed8d9165cea536407d63f98fa28fec Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 29 Aug 2015 00:19:11 -0700 Subject: [PATCH 05/11] lifecycle: Add a list outlining the usual flow Signed-off-by: W. Trevor King --- lifecycle.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/lifecycle.md b/lifecycle.md index e5520dfbd..8143f43a5 100644 --- a/lifecycle.md +++ b/lifecycle.md @@ -2,6 +2,25 @@ ## Lifecycle +A typical lifecyle progresses like this: + +1. There is no container or running application +2. A user tells the runtime to [create](#create) a container +3. The runtime creates the container +4. A user tells the runtime to [start](#start-process) an application +5. The runtime executes any [pre-start hooks](runtime.md#pre-start) +6. The runtime executes the application +7. The application is running +8. A user tells the runtime to [stop](#stop) an application +9. The runtime sends a termination signal to the application +10. The application exits +11. The runtime executes any [post-stop hooks](runtime.md#post-stop) +12. The runtime removes the container + +With steps 8 and 9, the user is explicitly stopping the application +(via the runtime), but it's also possible that the application could +exit for other reasons. In that case we skip directly from 7 to 10. + ### Create Creates the container: file system, namespaces, cgroups, capabilities. From 7d6e8b3dadb987fd099487fc4b52c09231dd3578 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 29 Aug 2015 00:23:06 -0700 Subject: [PATCH 06/11] lifecycle: Add an explicit container-destroy step It doesn't make sense to split creation into "create" and "start" while only having one "stop" command for both the application and container teardown. --- lifecycle.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/lifecycle.md b/lifecycle.md index 8143f43a5..a02b4e6cc 100644 --- a/lifecycle.md +++ b/lifecycle.md @@ -15,7 +15,8 @@ A typical lifecyle progresses like this: 9. The runtime sends a termination signal to the application 10. The application exits 11. The runtime executes any [post-stop hooks](runtime.md#post-stop) -12. The runtime removes the container +12. A user tells the runtime to [destroy](#destroy) the container +13. The runtime removes the container With steps 8 and 9, the user is explicitly stopping the application (via the runtime), but it's also possible that the application could @@ -34,3 +35,8 @@ Runs a process in a container. Can be invoked several times. Not sure we need that from runc cli. Process is killed from the outside. This event needs to be captured by runc to run onstop event handlers. + +### Destroy + +Remove the container: unmount file systems, remove namespaces, etc. +This is the inverse of [create](#create). From 1c55c3cb56b08a532f9e84c8fe797aa8709f1c65 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 29 Aug 2015 01:17:49 -0700 Subject: [PATCH 07/11] README: Change 'Linux Specific' -> 'Linux-specific' To match 'Host-specific' and 'Host-independent'. Signed-off-by: W. Trevor King --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f443afa5c..90074eab4 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ Table of Contents - [Filesystem Bundle](bundle.md) - [Host-independent Container Configuration](config.md) - - [Linux Specific Configuration](config-linux.md) + - [Linux-specific Configuration](config-linux.md) - [Host-specific Container Configuration](runtime.md) - - [Linux Specific Configuration](runtime-linux.md) + - [Linux-specific Configuration](runtime-linux.md) - [Runtime and Lifecycle](lifecycle.md) - [Implementations](implementations.md) From c65526fae14417da916cbabd5be542d71699a539 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 29 Aug 2015 22:26:14 -0700 Subject: [PATCH 08/11] config: Mention host-independent in headings To distinguish from the host-dependent runtime.json configuration. Signed-off-by: W. Trevor King --- config-linux.md | 2 +- config.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/config-linux.md b/config-linux.md index aab976967..e695edef2 100644 --- a/config-linux.md +++ b/config-linux.md @@ -1,4 +1,4 @@ -# Linux-specific configuration +# Linux-specific, host-independent configuration The Linux container specification uses various kernel features like namespaces, cgroups, capabilities, LSM, and file system jails to fulfill the spec. diff --git a/config.md b/config.md index 00f24aa6f..41baab147 100644 --- a/config.md +++ b/config.md @@ -1,4 +1,4 @@ -# Configuration file +# Host-independent container configuration The container's top-level directory MUST contain a configuration file called `config.json`. For now the canonical schema is defined in [spec.go](spec.go) and [spec_linux.go](spec_linux.go), but this will be moved to a formal JSON schema over time. From e74f66fcd1c2f9023da98acf91da7c0ac7b4f740 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 29 Aug 2015 22:27:06 -0700 Subject: [PATCH 09/11] lifecycle: Cross-link the generic and Linux-specific notes Signed-off-by: W. Trevor King --- lifecycle-linux.md | 8 +++++++- lifecycle.md | 2 ++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/lifecycle-linux.md b/lifecycle-linux.md index 545af8103..2393a8db1 100644 --- a/lifecycle-linux.md +++ b/lifecycle-linux.md @@ -1,4 +1,10 @@ -## File descriptors +# Linux-specific lifecycle notes + +The [platform-independent lifecycle](lifecycle.md) has a few Linux-specific extensions. + +## Start (process) + +### File descriptors By default, only the `stdin`, `stdout` and `stderr` file descriptors are kept open for the application by the runtime. diff --git a/lifecycle.md b/lifecycle.md index a02b4e6cc..4f900c597 100644 --- a/lifecycle.md +++ b/lifecycle.md @@ -29,6 +29,8 @@ Creates the container: file system, namespaces, cgroups, capabilities. ### Start (process) Runs a process in a container. Can be invoked several times. +On Linux hosts, some information for this execution may come from outside the [`config.json`](config.md) and [`runtime.json`](runtime.md) specifications. +See [the Linux-specific notes](lifecycle-linux.md#start-process) for details. ### Stop (process) From 07e052f890c4fbf24a55b040ea9f0664cf1a0903 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 29 Aug 2015 22:27:49 -0700 Subject: [PATCH 10/11] runtime: Cross-link the generic and Linux-specific notes And add top-level headings for these files. Signed-off-by: W. Trevor King --- runtime-linux.md | 4 ++++ runtime.md | 5 +++++ 2 files changed, 9 insertions(+) diff --git a/runtime-linux.md b/runtime-linux.md index 1cabc6156..d3bbb649d 100644 --- a/runtime-linux.md +++ b/runtime-linux.md @@ -1,3 +1,7 @@ +# Linux-specific, host-dependent configuration + +The Linux-specific section of the [host-dependent configuration](runtime.md). + ## Namespaces 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. diff --git a/runtime.md b/runtime.md index d182c4169..c99a7c211 100644 --- a/runtime.md +++ b/runtime.md @@ -1,3 +1,8 @@ +# Host-specific container configuration + +The `runtime.json` file contains host-specific information needed to create containers and launch applications. +There are also platform-specific extensions for [Linux](runtime-linux.md). + ## Hooks Hooks allow one to run code before/after various lifecycle events of the container. From e22af5d633f0c0cc78eed06a054fd53acec0185f Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 29 Aug 2015 22:29:29 -0700 Subject: [PATCH 11/11] lifecycle: Drop 'Runtime and Lifecycle' top heading This page is just about the lifecycle now. I'm not sure what the original intention was, but when this header landed in runtime.md with 5d2eb180 (*: re-org the spec, 2015-06-24) there wasn't anything beyond the lifecycle stuff in this file. Now that it's lifecycle.md and there are other files for our other content, I don't expect it to talk about anything besides the lifecycle in the future. Signed-off-by: W. Trevor King --- lifecycle.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/lifecycle.md b/lifecycle.md index 4f900c597..9eb6ebe8b 100644 --- a/lifecycle.md +++ b/lifecycle.md @@ -1,6 +1,4 @@ -# Runtime and Lifecycle - -## Lifecycle +# Lifecycle A typical lifecyle progresses like this: @@ -22,23 +20,23 @@ With steps 8 and 9, the user is explicitly stopping the application (via the runtime), but it's also possible that the application could exit for other reasons. In that case we skip directly from 7 to 10. -### Create +## Create Creates the container: file system, namespaces, cgroups, capabilities. -### Start (process) +## Start (process) Runs a process in a container. Can be invoked several times. On Linux hosts, some information for this execution may come from outside the [`config.json`](config.md) and [`runtime.json`](runtime.md) specifications. See [the Linux-specific notes](lifecycle-linux.md#start-process) for details. -### Stop (process) +## Stop (process) Not sure we need that from runc cli. Process is killed from the outside. This event needs to be captured by runc to run onstop event handlers. -### Destroy +## Destroy Remove the container: unmount file systems, remove namespaces, etc. This is the inverse of [create](#create).