From 9285db67525c4dce4308903dcf80627f693388dc Mon Sep 17 00:00:00 2001 From: Kir Kolyshkin Date: Thu, 20 Jul 2017 14:42:51 -0700 Subject: [PATCH] Introduce/document new IPC modes This builds (and depends) on https://github.com/moby/moby/pull/34087 Version 2: - remove --ipc argument validation (it is now done by daemon) - add/document 'none' value - docs/reference/run.md: add a table with better modes description - dockerd(8) typesetting fixes Version 3: - remove ipc mode tests from cli/command/container/opts_test.go Signed-off-by: Kir Kolyshkin --- cli/command/container/opts.go | 9 ++------- cli/command/container/opts_test.go | 15 ++------------- contrib/completion/bash/docker | 2 +- docs/reference/run.md | 21 ++++++++++++++++----- man/dockerd.8.md | 5 +++++ 5 files changed, 26 insertions(+), 26 deletions(-) diff --git a/cli/command/container/opts.go b/cli/command/container/opts.go index cf1f931b29..f80474d3fe 100644 --- a/cli/command/container/opts.go +++ b/cli/command/container/opts.go @@ -274,7 +274,7 @@ func addFlags(flags *pflag.FlagSet) *containerOptions { // Low-level execution (cgroups, namespaces, ...) flags.StringVar(&copts.cgroupParent, "cgroup-parent", "", "Optional parent cgroup for the container") - flags.StringVar(&copts.ipcMode, "ipc", "", "IPC namespace to use") + flags.StringVar(&copts.ipcMode, "ipc", "", "IPC mode to use") flags.StringVar(&copts.isolation, "isolation", "", "Container isolation technology") flags.StringVar(&copts.pidMode, "pid", "", "PID namespace to use") flags.Var(&copts.shmSize, "shm-size", "Size of /dev/shm") @@ -421,11 +421,6 @@ func parse(flags *pflag.FlagSet, copts *containerOptions) (*containerConfig, err return nil, err } - ipcMode := container.IpcMode(copts.ipcMode) - if !ipcMode.Valid() { - return nil, errors.Errorf("--ipc: invalid IPC mode") - } - pidMode := container.PidMode(copts.pidMode) if !pidMode.Valid() { return nil, errors.Errorf("--pid: invalid PID mode") @@ -584,7 +579,7 @@ func parse(flags *pflag.FlagSet, copts *containerOptions) (*containerConfig, err ExtraHosts: copts.extraHosts.GetAll(), VolumesFrom: copts.volumesFrom.GetAll(), NetworkMode: container.NetworkMode(copts.netMode), - IpcMode: ipcMode, + IpcMode: container.IpcMode(copts.ipcMode), PidMode: pidMode, UTSMode: utsMode, UsernsMode: usernsMode, diff --git a/cli/command/container/opts_test.go b/cli/command/container/opts_test.go index 25e5b04fc8..6443ed3310 100644 --- a/cli/command/container/opts_test.go +++ b/cli/command/container/opts_test.go @@ -366,23 +366,12 @@ func TestParseDevice(t *testing.T) { } func TestParseModes(t *testing.T) { - // ipc ko - _, _, _, err := parseRun([]string{"--ipc=container:", "img", "cmd"}) - testutil.ErrorContains(t, err, "--ipc: invalid IPC mode") - - // ipc ok - _, hostconfig, _, err := parseRun([]string{"--ipc=host", "img", "cmd"}) - require.NoError(t, err) - if !hostconfig.IpcMode.Valid() { - t.Fatalf("Expected a valid IpcMode, got %v", hostconfig.IpcMode) - } - // pid ko - _, _, _, err = parseRun([]string{"--pid=container:", "img", "cmd"}) + _, _, _, err := parseRun([]string{"--pid=container:", "img", "cmd"}) testutil.ErrorContains(t, err, "--pid: invalid PID mode") // pid ok - _, hostconfig, _, err = parseRun([]string{"--pid=host", "img", "cmd"}) + _, hostconfig, _, err := parseRun([]string{"--pid=host", "img", "cmd"}) require.NoError(t, err) if !hostconfig.PidMode.Valid() { t.Fatalf("Expected a valid PidMode, got %v", hostconfig.PidMode) diff --git a/contrib/completion/bash/docker b/contrib/completion/bash/docker index 280bca1069..55613d70a5 100644 --- a/contrib/completion/bash/docker +++ b/contrib/completion/bash/docker @@ -1862,7 +1862,7 @@ _docker_container_run_and_create() { __docker_complete_containers_running ;; *) - COMPREPLY=( $( compgen -W 'host container:' -- "$cur" ) ) + COMPREPLY=( $( compgen -W 'none host private shareable container:' -- "$cur" ) ) # shellcheck disable=SC2128 if [ "$COMPREPLY" = "container:" ]; then __docker_nospace diff --git a/docs/reference/run.md b/docs/reference/run.md index 4a1a4c1cb9..22d3b249d3 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -265,11 +265,21 @@ more advanced use case would be changing the host's hostname from a container. ## IPC settings (--ipc) - --ipc="" : Set the IPC mode for the container, - 'container:': reuses another container's IPC namespace - 'host': use the host's IPC namespace inside the container + --ipc="MODE" : Set the IPC mode for the container -By default, all containers have the IPC namespace enabled. +The following values are accepted: + +| Value | Description | +|:---------------------------|:----------------------------------------------------------------------------------| +| "" | Use daemon's default. | +| "none" | Own private IPC namespace, with /dev/shm not mounted. | +| "private" | Own private IPC namespace. | +| "shareable" | Own private IPC namespace, with a possibility to share it with other containers. | +| "container:<_name-or-ID_>" | Join another ("shareable") container's IPC namespace. | +| "host" | Use the host system's IPC namespace. | + +If not specified, daemon default is used, which can either be `"private"` +or `"shareable"`, depending on the daemon version and configration. IPC (POSIX/SysV IPC) namespace provides separation of named shared memory segments, semaphores and message queues. @@ -280,7 +290,8 @@ memory is commonly used by databases and custom-built (typically C/OpenMPI, C++/using boost libraries) high performance applications for scientific computing and financial services industries. If these types of applications are broken into multiple containers, you might need to share the IPC mechanisms -of the containers. +of the containers, using `"shareable"` mode for the main (i.e. "donor") +container, and `"container:"` for other containers. ## Network settings diff --git a/man/dockerd.8.md b/man/dockerd.8.md index 8a7619ca2c..733cc20f88 100644 --- a/man/dockerd.8.md +++ b/man/dockerd.8.md @@ -23,6 +23,7 @@ dockerd - Enable daemon mode [**--default-gateway**[=*DEFAULT-GATEWAY*]] [**--default-gateway-v6**[=*DEFAULT-GATEWAY-V6*]] [**--default-runtime**[=*runc*]] +[**--default-ipc-mode**=*MODE*] [**--default-shm-size**[=*64MiB*]] [**--default-ulimit**[=*[]*]] [**--disable-legacy-registry**] @@ -185,6 +186,10 @@ $ sudo dockerd --add-runtime runc=runc --add-runtime custom=/usr/local/bin/my-ru **--default-runtime**="runc" Set default runtime if there're more than one specified by `--add-runtime`. +**--default-ipc-mode**="**private**|**shareable**" + Set the default IPC mode for newly created containers. The argument + can either be **private** or **shareable**. + **--default-shm-size**=*64MiB* Set the daemon-wide default shm size for containers. Default is `64MiB`.