mesos git commit: Added documentation for mesos-containerizer Linux capabilities support.

[ji...@apache.org]

Repository: mesos
Updated Branches:
  refs/heads/master c7dab59bf -> 70bddc989


Added documentation for mesos-containerizer Linux capabilities support.

Review: https://reviews.apache.org/r/52783/


Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/70bddc98
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/70bddc98
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/70bddc98

Branch: refs/heads/master
Commit: 70bddc989dda3e7fcc6958eaaaae2ad341aace59
Parents: c7dab59
Author: Benjamin Bannier <be...@mesosphere.io>
Authored: Tue Oct 18 15:49:31 2016 -0700
Committer: Jie Yu <yu...@gmail.com>
Committed: Tue Oct 18 16:00:25 2016 -0700

----------------------------------------------------------------------
 docs/configuration.md       | 16 ++++++++++++
 docs/linux_capabilities.md  | 53 ++++++++++++++++++++++++++++++++++++++++
 docs/mesos-containerizer.md |  4 +++
 3 files changed, 73 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/mesos/blob/70bddc98/docs/configuration.md
----------------------------------------------------------------------
diff --git a/docs/configuration.md b/docs/configuration.md
index c83a58e..efe3e9b 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -996,6 +996,22 @@ cgroup.
 </tr>
 <tr>
   <td>
+    --allowed_capabilities=VALUE
+  </td>
+  <td>
+The value needs to be a JSON-formatted string of Linux capabilities
+that the agent should allow. Note that if no Linux capabilities
+isolation is enabled (<code>linux/capabilities</code> is not present
+in the arguments to <code>--isolation</code>), this flags is ignored.
+<p/>
+Example:
+<pre><code>{
+"capabilities": [NET_RAW, MKNOD]
+}</code></pre>
+  </td>
+</tr>
+<tr>
+  <td>
     --appc_simple_discovery_uri_prefix=VALUE
   </td>
   <td>

http://git-wip-us.apache.org/repos/asf/mesos/blob/70bddc98/docs/linux_capabilities.md
----------------------------------------------------------------------
diff --git a/docs/linux_capabilities.md b/docs/linux_capabilities.md
new file mode 100644
index 0000000..b79aa8c
--- /dev/null
+++ b/docs/linux_capabilities.md
@@ -0,0 +1,53 @@
+# Linux Capabilities Support in Mesos Containerizer
+
+This document describes the `linux/capabilities` isolator. The
+isolator adds support for controlling [Linux
+Capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html)
+of containers launched using the
+[MesosContainerizer](mesos-containerizer.md)
+
+The Linux capabilities isolator allows operators to control which
+privileged operations Mesos tasks may perform. Operators can specify
+which capabilities to allow for containers executing on an agent;
+containers on the other hand can expose which capabilities they need.
+
+See the protobuf definition of `CapabilityInfo::Capability` for the
+list of currently exposed capabilities.
+
+
+## Agent setup
+
+The Linux capabilities isolator is loaded when `linux/capabilities` is
+present in the agent's `--isolation` flag.
+Capabilities which should be allowed are passed with the
+`--allowed_capabilities` flag. This isolator requires the
+`CAP_SETPCAP` capability so agent processes typically need to be
+started as root. A possible agent startup invocation could be
+
+```{.console}
+sudo mesos-agent --master=<master ip> --ip=<agent ip>
+  --work_dir=/var/lib/mesos
+  --isolation=linux/capabilities[,other isolation flags]
+  --allowed_capabilities='{"capabilities":[NET_RAW,MKNOD]}'
+```
+
+An empty list for `--allowed_capabilities` signifies that no
+capabilities are allowed, while an absent `--allowed_capabilities` flag
+signifies that all capabilities are allowed.
+
+
+## Task setup
+
+In order for a Mesos task to acquire allowed capabilities it needs to
+declare required capabilities in the `LinuxInfo` of its
+`ContainerInfo`.
+
+A Mesos task can only request capabilities which are allowed for the
+agent; a task requesting unallowed capabilities will be rejected.
+
+If an empty list of capabilities is given the Mesos task will drop all
+capabilities; if the optional `capability_info` field is not set the
+container will be able to acquire the capabilities of the Mesos task's
+user.
+
+Tasks

http://git-wip-us.apache.org/repos/asf/mesos/blob/70bddc98/docs/mesos-containerizer.md
----------------------------------------------------------------------
diff --git a/docs/mesos-containerizer.md b/docs/mesos-containerizer.md
index 7654462..2bff35f 100644
--- a/docs/mesos-containerizer.md
+++ b/docs/mesos-containerizer.md
@@ -285,3 +285,7 @@ This is described in a [separate document](docker-volume.md).
 ### The `network/cni` Isolator
 
 This is described in a [separate document](cni.md).
+
+### The `linux/capabilities` Isolator
+
+This is described in a [separate document](linux_capabilities.md).