Parcourir la source

Add info on --device flag permissions ':rwm'

Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au>

Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au> (github: SvenDowideit)
Sven Dowideit il y a 10 ans
Parent
commit
2709c4677c

+ 1 - 1
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)
    CPUs in which to allow execution (0-3, 0,1)
 
 
 **--device**=[]
 **--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**=[]
 **--dns-search**=[]
    Set custom DNS search domains
    Set custom DNS search domains

+ 2 - 1
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
    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.
 stopping the process by pressing the keys CTRL-P CTRL-Q.
+
 **--device**=[]
 **--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**=[]
 **--dns-search**=[]
    Set custom DNS search domains
    Set custom DNS search domains

+ 28 - 3
docs/sources/reference/commandline/cli.md

@@ -417,7 +417,7 @@ Creates a new container.
       --cap-drop=[]              Drop Linux capabilities
       --cap-drop=[]              Drop Linux capabilities
       --cidfile=""               Write the container ID to the file
       --cidfile=""               Write the container ID to the file
       --cpuset=""                CPUs in which to allow execution (0-3, 0,1)
       --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=[]                   Set custom DNS servers
       --dns-search=[]            Set custom DNS search domains
       --dns-search=[]            Set custom DNS search domains
       -e, --env=[]               Set environment variables
       -e, --env=[]               Set environment variables
@@ -457,6 +457,8 @@ container at any point.
 This is useful when you want to set up a container configuration ahead
 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.
 of time so that it is ready to start when you need it.
 
 
+Please see the [run command](#run) section for more details.
+
 #### Example
 #### Example
 
 
     $ sudo docker create -t -i fedora bash
     $ sudo docker create -t -i fedora bash
@@ -1115,7 +1117,7 @@ removed before the image is removed.
       --cidfile=""               Write the container ID to the file
       --cidfile=""               Write the container ID to the file
       --cpuset=""                CPUs in which to allow execution (0-3, 0,1)
       --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
       -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=[]                   Set custom DNS servers
       --dns-search=[]            Set custom DNS search domains
       --dns-search=[]            Set custom DNS search domains
       -e, --env=[]               Set environment variables
       -e, --env=[]               Set environment variables
@@ -1324,8 +1326,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
 device or audio device can be added to an otherwise unprivileged container
 (without the `--privileged` flag) and have the application directly access it.
 (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:**
 **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:**
 **A complete example:**
 
 

+ 20 - 0
docs/sources/reference/run.md

@@ -308,6 +308,26 @@ will be accessible within the container.
 
 
     $ sudo docker run --device=/dev/snd:/dev/snd ...
     $ 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
 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
 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
 list of capabilities that are kept. Both flags support the value `all`, so if the

+ 1 - 1
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(&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(&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(&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(&flEnv, []string{"e", "-env"}, "Set environment variables")
 	cmd.Var(&flEnvFile, []string{"-env-file"}, "Read in a line delimited file of environment variables")
 	cmd.Var(&flEnvFile, []string{"-env-file"}, "Read in a line delimited file of environment variables")