From b644395e96a6164a82a78cd328447764d0fb7952 Mon Sep 17 00:00:00 2001
From: "W. Trevor King" <wking@tremily.us>
Date: Tue, 11 Apr 2017 21:11:50 -0700
Subject: [PATCH] config-linux: RFC 2119 tightening for namespaces

Previously we had no MUST-level runtime requirements for namespace
entries in valid configs.  This commit attempts to pin those down.

I think we want more wording about new namespace creation (what
namespace is the seed/parent?  Which user namespace owns a runtime
namespace?  For more background on hierarchical namespaces, see [1].
For more background on the owning user namespace idea, see [2,3,4]),
but that wording proved contentious [5,6], so I punted it to [7].

The "'path' not associated with a namespace of type 'type'" condition
ensures that runtimes don't blindly call setns(2) on the path without
setting nstype nonzero.

[1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=a7306ed8d94af729ecef8b6e37506a1c6fc14788
     nsfs: add ioctl to get a parent namespace, 2016-09-06
[2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=6786741dbf99e44fb0c0ed85a37582b8a26f1c3b
     nsfs: add ioctl to get owning user namespace for ns file
     descriptor, 2016-09-06
[3]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=e5ff5ce6e20ee22511398bb31fb912466cf82a36
     nsfs: Add an ioctl() to return the namespace type, 2017-01-25
[4]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=d95fa3c76a66b6d76b1e109ea505c55e66360f3c
     nsfs: Add an ioctl() to return owner UID of a userns, 2017-01-25
[5]: https://github.com/opencontainers/runtime-spec/pull/767#discussion_r115591844
[6]: https://github.com/opencontainers/runtime-spec/pull/767#discussion_r115592437
[7]: https://github.com/opencontainers/runtime-spec/pull/795

Signed-off-by: W. Trevor King <wking@tremily.us>
---
 config-linux.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/config-linux.md b/config-linux.md
index 64f7663e6..f0603535a 100644
--- a/config-linux.md
+++ b/config-linux.md
@@ -35,11 +35,14 @@ The following parameters can be specified to setup namespaces:
     * **`user`** the container will be able to remap user and group IDs from the host to local users and groups within the container.
     * **`cgroup`** the container will have an isolated view of the cgroup hierarchy.
 
-* **`path`** *(string, OPTIONAL)* - an absolute path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace)
+* **`path`** *(string, OPTIONAL)* - an absolute path to namespace file in the [runtime mount namespace](glossary.md#runtime-namespace).
+    The runtime MUST place the container process in the namespace associated with that `path`.
+    The runtime MUST [generate an error](runtime.md#errors) if `path` is not associated with a namespace of type `type`.
+
+    If `path` is not specified, the runtime MUST create a new [container namespace](glossary.md#container-namespace) of type `type`.
 
-If a path is specified, that particular file is used to join that type of namespace.
 If a namespace type is not specified in the `namespaces` array, the container MUST inherit the [runtime namespace](glossary.md#runtime-namespace) of that type.
-If a `namespaces` field contains duplicated namespaces with same `type`, the runtime MUST error out.
+If a `namespaces` field contains duplicated namespaces with same `type`, the runtime MUST [generate an error](runtime.md#errors).
 
 ###### Example