From a60c612a0456c551bb45bdb9d3197bf532e1fd42 Mon Sep 17 00:00:00 2001 From: Dan Walsh Date: Tue, 29 Mar 2016 08:24:28 -0400 Subject: [PATCH] Add support for setting sysctls This patch will allow users to specify namespace specific "kernel parameters" for running inside of a container. Signed-off-by: Dan Walsh --- contrib/completion/bash/docker | 1 + contrib/completion/zsh/_docker | 1 + docs/reference/commandline/create.md | 1 + docs/reference/commandline/run.md | 28 +++++++++++++++++++++++ man/docker-create.1.md | 16 ++++++++++++++ man/docker-run.1.md | 33 ++++++++++++++++++++++++++++ 6 files changed, 80 insertions(+) diff --git a/contrib/completion/bash/docker b/contrib/completion/bash/docker index b0f3ccd7ba..51c6a0207f 100644 --- a/contrib/completion/bash/docker +++ b/contrib/completion/bash/docker @@ -1671,6 +1671,7 @@ _docker_run() { --shm-size --stop-signal --tmpfs + --sysctl --ulimit --user -u --userns diff --git a/contrib/completion/zsh/_docker b/contrib/completion/zsh/_docker index 25f53c53e1..a66b3457ca 100644 --- a/contrib/completion/zsh/_docker +++ b/contrib/completion/zsh/_docker @@ -644,6 +644,7 @@ __docker_subcommand() { "($help)--privileged[Give extended privileges to this container]" "($help)--read-only[Mount the container's root filesystem as read only]" "($help)*--security-opt=[Security options]:security option: " + "($help)*--sysctl=-[sysctl options]:sysctl: " "($help -t --tty)"{-t,--tty}"[Allocate a pseudo-tty]" "($help -u --user)"{-u=,--user=}"[Username or UID]:user:_users" "($help)--tmpfs[mount tmpfs]" diff --git a/docs/reference/commandline/create.md b/docs/reference/commandline/create.md index 0540b3f34a..3e4024374c 100644 --- a/docs/reference/commandline/create.md +++ b/docs/reference/commandline/create.md @@ -82,6 +82,7 @@ Creates a new container. --stop-signal="SIGTERM" Signal to stop a container --shm-size=[] Size of `/dev/shm`. The format is ``. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. --storage-opt=[] Set storage driver options per container + --sysctl[=*[]*]] Configure namespaced kernel parameters at runtime -t, --tty Allocate a pseudo-TTY -u, --user="" Username or UID --userns="" Container user namespace diff --git a/docs/reference/commandline/run.md b/docs/reference/commandline/run.md index 00438bebad..67e0010232 100644 --- a/docs/reference/commandline/run.md +++ b/docs/reference/commandline/run.md @@ -84,6 +84,7 @@ parent = "smn_cli" --sig-proxy=true Proxy received signals to the process --stop-signal="SIGTERM" Signal to stop a container --storage-opt=[] Set storage driver options per container + --sysctl[=*[]*]] Configure namespaced kernel parameters at runtime -t, --tty Allocate a pseudo-TTY -u, --user="" Username or UID (format: [:]) --userns="" Container user namespace @@ -620,3 +621,30 @@ If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, $ docker run -d --isolation default busybox top $ docker run -d --isolation hyperv busybox top ``` + +### Configure namespaced kernel parameters (sysctls) at runtime + +The `--sysctl` sets namespaced kernel parameters (sysctls) in the +container. For example, to turn on IP forwarding in the containers +network namespace, run this command: + + $ docker run --sysctl net.ipv4.ip_forward=1 someimage + + +> **Note**: Not all sysctls are namespaced. docker does not support changing sysctls +> inside of a container that also modify the host system. As the kernel +> evolves we expect to see more sysctls become namespaced. + +#### Currently supported sysctls + + `IPC Namespace`: + + kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced + Sysctls beginning with fs.mqueue.* + + If you use the `--ipc=host` option these sysctls will not be allowed. + + `Network Namespace`: + Sysctls beginning with net.* + + If you use the `--net=host` option using these sysctls will not be allowed. diff --git a/man/docker-create.1.md b/man/docker-create.1.md index d3cb85c78c..3f90a3a1d8 100644 --- a/man/docker-create.1.md +++ b/man/docker-create.1.md @@ -67,6 +67,7 @@ docker-create - Create a new container [**--storage-opt**[=*[]*]] [**--stop-signal**[=*SIGNAL*]] [**--shm-size**[=*[]*]] +[**--sysctl**[=*[]*]] [**-t**|**--tty**] [**--tmpfs**[=*[CONTAINER-DIR[:]*]] [**-u**|**--user**[=*USER*]] @@ -336,6 +337,21 @@ unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. **--stop-signal**=*SIGTERM* Signal to stop a container. Default is SIGTERM. +**--sysctl**=SYSCTL + Configure namespaced kernel parameters at runtime + + IPC Namespace - current sysctls allowed: + + kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced + Sysctls beginning with fs.mqueue.* + + Note: if you use --ipc=host using these sysctls will not be allowed. + + Network Namespace - current sysctls allowed: + Sysctls beginning with net.* + + Note: if you use --net=host using these sysctls will not be allowed. + **-t**, **--tty**=*true*|*false* Allocate a pseudo-TTY. The default is *false*. diff --git a/man/docker-run.1.md b/man/docker-run.1.md index e6757fc512..921ff9a07b 100644 --- a/man/docker-run.1.md +++ b/man/docker-run.1.md @@ -71,6 +71,7 @@ docker-run - Run a command in a new container [**--stop-signal**[=*SIGNAL*]] [**--shm-size**[=*[]*]] [**--sig-proxy**[=*true*]] +[**--sysctl**[=*[]*]] [**-t**|**--tty**] [**--tmpfs**[=*[CONTAINER-DIR[:]*]] [**-u**|**--user**[=*USER*]] @@ -492,6 +493,21 @@ its root filesystem mounted as read only prohibiting any writes. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m`(megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. +**--sysctl**=SYSCTL + Configure namespaced kernel parameters at runtime + + IPC Namespace - current sysctls allowed: + + kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced + Sysctls beginning with fs.mqueue.* + + If you use the `--ipc=host` option these sysctls will not be allowed. + + Network Namespace - current sysctls allowed: + Sysctls beginning with net.* + + If you use the `--net=host` option these sysctls will not be allowed. + **--sig-proxy**=*true*|*false* Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true*. @@ -955,6 +971,23 @@ $ docker run -d --isolation default busybox top $ docker run -d --isolation hyperv busybox top ``` +## Setting Namespaced Kernel Parameters (Sysctls) + +The `--sysctl` sets namespaced kernel parameters (sysctls) in the +container. For example, to turn on IP forwarding in the containers +network namespace, run this command: + + $ docker run --sysctl net.ipv4.ip_forward=1 someimage + +Note: + +Not all sysctls are namespaced. docker does not support changing sysctls +inside of a container that also modify the host system. As the kernel +evolves we expect to see more sysctls become namespaced. + +See the definition of the `--sysctl` option above for the current list of +supported sysctls. + # HISTORY April 2014, Originally compiled by William Henry (whenry at redhat dot com) based on docker.com source material and internal work.