Add --readonly for read only container rootfs

Add a --readonly flag to allow the container's root filesystem to be
mounted as readonly.  This can be used in combination with volumes to
force a container's process to only write to locations that will be
persisted.  This is useful in many cases where the admin controls where
they would like developers to write files and error on any other
locations.

Closes #7923
Closes #8752

Signed-off-by: Michael Crosby <crosbymichael@gmail.com>
Upstream-commit: 409407091a7282d0c4086b71e86397e2d089ba13
Component: engine

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

@@ -34,6 +34,7 @@ docker-create - Create a new container
 [**-p**|**--publish**[=*[]*]]
 [**--pid**[=*[]*]]
 [**--privileged**[=*false*]]
+[**--read-only**[=*false*]]
 [**--restart**[=*RESTART*]]
 [**--security-opt**[=*[]*]]
 [**-t**|**--tty**[=*false*]]
@@ -140,6 +141,9 @@ IMAGE [COMMAND] [ARG...]
 **--privileged**=*true*|*false*
    Give extended privileges to this container. The default is *false*.
 
+**--read-only**=*true*|*false*
+    Mount the container's root filesystem as read only.
+
 **--restart**=""
    Restart policy to apply when a container exits (no, on-failure[:max-retry], always)
 

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

@@ -35,6 +35,7 @@ docker-run - Run a command in a new container
 [**-p**|**--publish**[=*[]*]]
 [**--pid**[=*[]*]]
 [**--privileged**[=*false*]]
+[**--read-only**[=*false*]]
 [**--restart**[=*RESTART*]]
 [**--rm**[=*false*]]
 [**--security-opt**[=*[]*]]
@@ -253,6 +254,13 @@ to all devices on the host as well as set some configuration in AppArmor to
 allow the container nearly all the same access to the host as processes running
 outside of a container on the host.
 
+**--read-only**=*true*|*false*
+    Mount the container's root filesystem as read only.
+
+    By default a container will have its root filesystem writable allowing processes
+to write files anywhere.  By specifying the `--read-only` flag the container will have
+its root filesystem mounted as read only prohibiting any writes.
+
 **--restart**=""
    Restart policy to apply when a container exits (no, on-failure[:max-retry], always)
 

components/engine/docs/sources/reference/api/docker_remote_api.md

@@ -61,6 +61,13 @@ This endpoint now returns the list current execs associated with the container (
 **New!**
 New endpoint to rename a container `id` to a new name.
 
+`POST /containers/create`
+`POST /containers/(id)/start`
+
+**New!**
+(`ReadonlyRootfs`) can be passed in the host config to mount the container's
+root filesystem as read only.
+
 ## v1.16
 
 ### Full Documentation

components/engine/docs/sources/reference/api/docker_remote_api_v1.17.md

@@ -146,6 +146,7 @@ Create a container
                "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] },
                "PublishAllPorts": false,
                "Privileged": false,
+               "ReadonlyRootfs": false,
                "Dns": ["8.8.8.8"],
                "DnsSearch": [""],
                "VolumesFrom": ["parent", "other:ro"],
@@ -218,6 +219,8 @@ Json Parameters:
         exposed ports. Specified as a boolean value.
   -   **Privileged** - Gives the container full access to the host.  Specified as
         a boolean value.
+  -   **ReadonlyRootfs** - Mount the container's root filesystem as read only.
+        Specified as a boolean value.
   -   **Dns** - A list of dns servers for the container to use.
   -   **DnsSearch** - A list of DNS search domains
   -   **VolumesFrom** - A list of volumes to inherit from another container.
@@ -323,6 +326,7 @@ Return low-level information on the container `id`
 			"NetworkMode": "bridge",
 			"PortBindings": {},
 			"Privileged": false,
+			"ReadonlyRootfs": false,
 			"PublishAllPorts": false,
 			"RestartPolicy": {
 				"MaximumRetryCount": 2,

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

@@ -753,6 +753,7 @@ Creates a new container.
                                    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)
       --privileged=false         Give extended privileges to this container
+      --read-only=false           Mount the container's root filesystem as read only
       --restart=""               Restart policy to apply when a container exits (no, on-failure[:max-retry], always)
       --security-opt=[]          Security Options
       -t, --tty=false            Allocate a pseudo-TTY
@@ -1606,6 +1607,7 @@ removed before the image is removed.
                                    (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
+      --read-only=false           Mount the container's root filesystem as read only
       --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)
       --security-opt=[]          Security Options
@@ -1681,6 +1683,13 @@ will automatically create this directory on the host for you. In the
 example above, Docker will create the `/doesnt/exist`
 folder before starting your container.
 
+    $ sudo docker run --read-only -v /icanwrite busybox touch /icanwrite here
+
+Volumes can be used in combination with `--read-only` to control where 
+a container writes files.  The `--read only` flag mounts the container's root
+filesystem as read only prohibiting writes to locations other than the
+specified volumes for the container.
+
     $ sudo docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v ./static-docker:/usr/bin/docker busybox sh
 
 By bind-mounting the docker unix socket and statically linked docker