Merge pull request #367 from kolyshkin/ipcmode

Introduce/document new IPC modes

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,

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)

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

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:<name|id>': 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:<donor-name-or-ID>"` for other containers.
 
 ## Network settings
 

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`.