diff --git a/docs/man/docker-create.1.md b/docs/man/docker-create.1.md index c5ed0349c4..00934347e3 100644 --- a/docs/man/docker-create.1.md +++ b/docs/man/docker-create.1.md @@ -61,7 +61,7 @@ docker-create - Create a new container CPUs in which to allow execution (0-3, 0,1) **--device**=[] - Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc) + Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc:rwm) **--dns-search**=[] Set custom DNS search domains diff --git a/docs/man/docker-run.1.md b/docs/man/docker-run.1.md index e3d846749d..32777b7f0e 100644 --- a/docs/man/docker-run.1.md +++ b/docs/man/docker-run.1.md @@ -98,8 +98,9 @@ the detached mode, then you cannot use the **-rm** option. When attached in the tty mode, you can detach from a running container without stopping the process by pressing the keys CTRL-P CTRL-Q. + **--device**=[] - Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc) + Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc:rwm) **--dns-search**=[] Set custom DNS search domains diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md index 86f02b6cf1..0912007e5a 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -487,7 +487,7 @@ Creates a new container. --cap-drop=[] Drop Linux capabilities --cidfile="" Write the container ID to the file --cpuset="" CPUs in which to allow execution (0-3, 0,1) - --device=[] Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc) + --device=[] Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc:rwm) --dns=[] Set custom DNS servers --dns-search=[] Set custom DNS search domains -e, --env=[] Set environment variables @@ -527,6 +527,8 @@ container at any point. This is useful when you want to set up a container configuration ahead of time so that it is ready to start when you need it. +Please see the [run command](#run) section for more details. + #### Example $ sudo docker create -t -i fedora bash @@ -1185,7 +1187,7 @@ removed before the image is removed. --cidfile="" Write the container ID to the file --cpuset="" CPUs in which to allow execution (0-3, 0,1) -d, --detach=false Detached mode: run the container in the background and print the new container ID - --device=[] Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc) + --device=[] Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc:rwm) --dns=[] Set custom DNS servers --dns-search=[] Set custom DNS search domains -e, --env=[] Set environment variables @@ -1394,8 +1396,31 @@ option enables that. For example, a specific block storage device or loop device or audio device can be added to an otherwise unprivileged container (without the `--privileged` flag) and have the application directly access it. +By default, the container will be able to `read`, `write` and `mknod` these devices. +This can be overridden using a third `:rwm` set of options to each `--device` +flag: + + +``` + $ sudo docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc + + Command (m for help): q + $ sudo docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc + You will not be able to write the partition table. + + Command (m for help): q + + $ sudo docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc + + Command (m for help): q + + $ sudo docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc + fdisk: unable to open /dev/xvdc: Operation not permitted +``` + **Note:** -> `--device` cannot be safely used with ephemeral devices. Block devices that may be removed should not be added to untrusted containers with `--device`. +> `--device` cannot be safely used with ephemeral devices. Block devices that +> may be removed should not be added to untrusted containers with `--device`. **A complete example:** diff --git a/docs/sources/reference/run.md b/docs/sources/reference/run.md index 67007ccff7..2183ee957c 100644 --- a/docs/sources/reference/run.md +++ b/docs/sources/reference/run.md @@ -308,6 +308,26 @@ will be accessible within the container. $ sudo docker run --device=/dev/snd:/dev/snd ... +By default, the container will be able to `read`, `write`, and `mknod` these devices. +This can be overridden using a third `:rwm` set of options to each `--device` flag: + + +``` + $ sudo docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc + + Command (m for help): q + $ sudo docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc + You will not be able to write the partition table. + + Command (m for help): q + + $ sudo docker run --device=/dev/sda:/dev/xvdc:w --rm -it ubuntu fdisk /dev/xvdc + crash.... + + $ sudo docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc + fdisk: unable to open /dev/xvdc: Operation not permitted +``` + In addition to `--privileged`, the operator can have fine grain control over the capabilities using `--cap-add` and `--cap-drop`. By default, Docker has a default list of capabilities that are kept. Both flags support the value `all`, so if the diff --git a/runconfig/parse.go b/runconfig/parse.go index 42ec68898d..3a8cdd3350 100644 --- a/runconfig/parse.go +++ b/runconfig/parse.go @@ -65,7 +65,7 @@ func Parse(cmd *flag.FlagSet, args []string, sysInfo *sysinfo.SysInfo) (*Config, cmd.Var(&flAttach, []string{"a", "-attach"}, "Attach to STDIN, STDOUT or STDERR.") cmd.Var(&flVolumes, []string{"v", "-volume"}, "Bind mount a volume (e.g., from the host: -v /host:/container, from Docker: -v /container)") cmd.Var(&flLinks, []string{"#link", "-link"}, "Add link to another container in the form of name:alias") - cmd.Var(&flDevices, []string{"-device"}, "Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc)") + cmd.Var(&flDevices, []string{"-device"}, "Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc:rwm)") cmd.Var(&flEnv, []string{"e", "-env"}, "Set environment variables") cmd.Var(&flEnvFile, []string{"-env-file"}, "Read in a line delimited file of environment variables")