1 files changed, 35 insertions, 0 deletions
diff --git a/docs/source/markdown/options/cpu-shares.md b/docs/source/markdown/options/cpu-shares.md
new file mode 100644
index 000000000..a5aacd2ca
--- /dev/null
+++ b/docs/source/markdown/options/cpu-shares.md
@@ -0,0 +1,35 @@
+#### **--cpu-shares**, **-c**=*shares*
+
+CPU shares (relative weight).
+
+By default, all containers get the same proportion of CPU cycles. This
+proportion can be modified by changing the container's CPU share weighting
+relative to the combined weight of all the running containers.
+Default weight is **1024**.
+
+The proportion will only apply when CPU-intensive processes are running.
+When tasks in one container are idle, other containers can use the
+left-over CPU time. The actual amount of CPU time will vary depending on
+the number of containers running on the system.
+
+For example, consider three containers, one has a cpu-share of 1024 and
+two others have a cpu-share setting of 512. When processes in all three
+containers attempt to use 100% of CPU, the first container would receive
+50% of the total CPU time. If a fourth container is added with a cpu-share
+of 1024, the first container only gets 33% of the CPU. The remaining containers
+receive 16.5%, 16.5% and 33% of the CPU.
+
+On a multi-core system, the shares of CPU time are distributed over all CPU
+cores. Even if a container is limited to less than 100% of CPU time, it can
+use 100% of each individual CPU core.
+
+For example, consider a system with more than three cores.
+If the container _C0_ is started with **--cpu-shares=512** running one process,
+and another container _C1_ with **--cpu-shares=1024** running two processes,
+this can result in the following division of CPU shares:
+
+| PID  |  container  | CPU     | CPU share    |
+| ---- | ----------- | ------- | ------------ |
+| 100  |  C0         | 0       | 100% of CPU0 |
+| 101  |  C1         | 1       | 100% of CPU1 |
+| 102  |  C1         | 2       | 100% of CPU2 |