Merge pull request #10080 from crosbymichael/pid-ns

Add --pid flag for staying in the host's pid namespace
Upstream-commit: 47e3da848ffbe88d0188ae6cfc09d6e1668bc293
Component: engine

components/engine/docs/man/docker-create.1.md

@@ -32,6 +32,7 @@ docker-create - Create a new container
 [**--net**[=*"bridge"*]]
 [**-P**|**--publish-all**[=*false*]]
 [**-p**|**--publish**[=*[]*]]
+[**--pid**[=*[]*]]
 [**--privileged**[=*false*]]
 [**--restart**[=*RESTART*]]
 [**--security-opt**[=*[]*]]
@@ -131,6 +132,11 @@ IMAGE [COMMAND] [ARG...]
                                When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. (e.g., `-p 1234-1236:1234-1236/tcp`)
                                (use 'docker port' to see the actual mapping)
 
+**--pid**=host
+   Set the PID mode for the container
+     **host**: use the host's PID namespace inside the container.
+     Note: the host mode gives the container full access to local PID and is therefore considered insecure.
+
 **--privileged**=*true*|*false*
    Give extended privileges to this container. The default is *false*.
 

components/engine/docs/man/docker-run.1.md

@@ -33,6 +33,7 @@ docker-run - Run a command in a new container
 [**--net**[=*"bridge"*]]
 [**-P**|**--publish-all**[=*false*]]
 [**-p**|**--publish**[=*[]*]]
+[**--pid**[=*[]*]]
 [**--privileged**[=*false*]]
 [**--restart**[=*RESTART*]]
 [**--rm**[=*false*]]
@@ -234,6 +235,11 @@ mapping between the host ports and the exposed ports, use **docker port**.
                                When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. (e.g., `-p 1234-1236:1234-1236/tcp`)
                                (use 'docker port' to see the actual mapping)
 
+**--pid**=host
+   Set the PID mode for the container
+     **host**: use the host's PID namespace inside the container.
+     Note: the host mode gives the container full access to local PID and is therefore considered insecure.
+
 **--privileged**=*true*|*false*
    Give extended privileges to this container. The default is *false*.
 

components/engine/docs/sources/reference/commandline/cli.md

@@ -1604,6 +1604,7 @@ removed before the image is removed.
                                    Both hostPort and containerPort can be specified as a range of ports. 
                                    When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. (e.g., `-p 1234-1236:1234-1236/tcp`)
                                    (use 'docker port' to see the actual mapping)
+      --pid=host		 'host': use the host PID namespace inside the container.  Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
       --privileged=false         Give extended privileges to this container
       --restart=""               Restart policy to apply when a container exits (no, on-failure[:max-retry], always)
       --rm=false                 Automatically remove the container when it exits (incompatible with -d)

components/engine/docs/sources/reference/run.md

@@ -133,11 +133,31 @@ While not strictly a means of identifying a container, you can specify a version
 image you'd like to run the container with by adding `image[:tag]` to the command. For
 example, `docker run ubuntu:14.04`.
 
+## PID Settings
+    --pid=""  : Set the PID (Process) Namespace mode for the container,
+           'host': use the host's PID namespace inside the container
+By default, all containers have the PID namespace enabled.
+
+PID namespace provides separation of processes. The PID Namespace removes the
+view of the system processes, and allows process ids to be reused including
+pid 1.
+
+In certain cases you want your container to share the host's process namespace,
+basically allowing processes within the container to see all of the processes
+on the system.  For example, you could build a container with debugging tools
+like `strace` or `gdb`, but want to use these tools when debugging processes
+within the container.
+
+    $ sudo docker run --pid=host rhel7 strace -p 1234
+
+This command would allow you to use `strace` inside the container on pid 1234 on
+the host.
+
 ## IPC Settings
     --ipc=""  : Set the IPC mode for the container,
                                  'container:<name|id>': reuses another container's IPC namespace
                                  'host': use the host's IPC namespace inside the container
-By default, all containers have the IPC namespace enabled 
+By default, all containers have the IPC namespace enabled.
 
 IPC (POSIX/SysV IPC) namespace provides separation of named shared memory segments, semaphores and message queues.