Merge pull request #4994 from robmry/47639_per-interface-sysctls

Document CLI support for per interface sysctls

cli/command/network/connect_test.go

@@ -43,27 +43,41 @@ func TestNetworkConnectErrors(t *testing.T) {
 }
 
 func TestNetworkConnectWithFlags(t *testing.T) {
-	expectedOpts := []network.IPAMConfig{
+	expectedConfig := &network.EndpointSettings{
-		{
+		IPAMConfig: &network.EndpointIPAMConfig{
-			Subnet:     "192.168.4.0/24",
+			IPv4Address:  "192.168.4.1",
-			IPRange:    "192.168.4.0/24",
+			IPv6Address:  "fdef:f401:8da0:1234::5678",
-			Gateway:    "192.168.4.1/24",
+			LinkLocalIPs: []string{"169.254.42.42"},
-			AuxAddress: map[string]string{},
+		},
+		Links:   []string{"otherctr"},
+		Aliases: []string{"poor-yorick"},
+		DriverOpts: map[string]string{
+			"driveropt1": "optval1,optval2",
+			"driveropt2": "optval4",
 		},
 	}
 	cli := test.NewFakeCli(&fakeClient{
 		networkConnectFunc: func(ctx context.Context, networkID, container string, config *network.EndpointSettings) error {
-			assert.Check(t, is.DeepEqual(expectedOpts, config.IPAMConfig), "not expected driver error")
+			assert.Check(t, is.DeepEqual(expectedConfig, config))
 			return nil
 		},
 	})
-	args := []string{"banana"}
+	args := []string{"mynet", "myctr"}
-	cmd := newCreateCommand(cli)
+	cmd := newConnectCommand(cli)
 
 	cmd.SetArgs(args)
-	cmd.Flags().Set("driver", "foo")
+	for _, opt := range []struct{ name, value string }{
-	cmd.Flags().Set("ip-range", "192.168.4.0/24")
+		{"alias", "poor-yorick"},
-	cmd.Flags().Set("gateway", "192.168.4.1/24")
+		{"driver-opt", "\"driveropt1=optval1,optval2\""},
-	cmd.Flags().Set("subnet", "192.168.4.0/24")
+		{"driver-opt", "driveropt2=optval3"},
+		{"driver-opt", "driveropt2=optval4"}, // replaces value
+		{"ip", "192.168.4.1"},
+		{"ip6", "fdef:f401:8da0:1234::5678"},
+		{"link", "otherctr"},
+		{"link-local-ip", "169.254.42.42"},
+	} {
+		err := cmd.Flags().Set(opt.name, opt.value)
+		assert.Check(t, err)
+	}
 	assert.NilError(t, cmd.Execute())
 }

docs/reference/commandline/container_run.md

@@ -707,7 +707,24 @@ For additional information on working with labels, see
 
 To start a container and connect it to a network, use the `--network` option.
 
-The following commands create a network named `my-net` and adds a `busybox` container
+If you want to add a running container to a network use the `docker network connect` subcommand.
+
+You can connect multiple containers to the same network. Once connected, the
+containers can communicate using only another container's IP address
+or name. For `overlay` networks or custom plugins that support multi-host
+connectivity, containers connected to the same multi-host network but launched
+from different Engines can also communicate in this way.
+
+> **Note**
+>
+> The default bridge network only allows containers to communicate with each other using
+> internal IP addresses. User-created bridge networks provide DNS resolution between
+> containers using container names.
+
+You can disconnect a container from a network using the `docker network
+disconnect` command.
+
+The following commands create a network named `my-net` and add a `busybox` container
 to the `my-net` network.
 
 ```console
@@ -724,24 +741,56 @@ $ docker network create --subnet 192.0.2.0/24 my-net
 $ docker run -itd --network=my-net --ip=192.0.2.69 busybox
 ```
 
-If you want to add a running container to a network use the `docker network connect` subcommand.
+To connect the container to more than one network, repeat the `--network` option.
 
-You can connect multiple containers to the same network. Once connected, the
+```console
-containers can communicate using only another container's IP address
+$ docker network create --subnet 192.0.2.0/24 my-net1
-or name. For `overlay` networks or custom plugins that support multi-host
+$ docker network create --subnet 192.0.3.0/24 my-net2
-connectivity, containers connected to the same multi-host network but launched
+$ docker run -itd --network=my-net1 --network=my-net2 busybox
-from different Engines can also communicate in this way.
+```
+
+To specify options when connecting to more than one network, use the extended syntax
+for the `--network` flag. Comma-separated options that can be specified in the extended
+`--network` syntax are:
+
+| Option          | Top-level Equivalent                  | Description                                     |
+|-----------------|---------------------------------------|-------------------------------------------------|
+| `name`          |                                       | The name of the network (mandatory)             |
+| `alias`         | `--network-alias`                     | Add network-scoped alias for the container      |
+| `ip`            | `--ip`                                | IPv4 address (e.g., 172.30.100.104)             |
+| `ip6`           | `--ip6`                               | IPv6 address (e.g., 2001:db8::33)               |
+| `mac-address`   | `--mac-address`                       | Container MAC address (e.g., 92:d0:c6:0a:29:33) |
+| `link-local-ip` | `--link-local-ip`                     | Container IPv4/IPv6 link-local addresses        |
+| `driver-opt`    | `docker network connect --driver-opt` | Network driver options                          |
+
+```console
+$ docker network create --subnet 192.0.2.0/24 my-net1
+$ docker network create --subnet 192.0.3.0/24 my-net2
+$ docker run -itd --network=name=my-net1,ip=192.0.2.42 --network=name=my-net2,ip=192.0.3.42 busybox
+```
+
+`sysctl` settings that start with `net.ipv4.`, `net.ipv6.` or `net.mpls.` can be
+set per-interface using `driver-opt` label `com.docker.network.endpoint.sysctls`.
+The interface name must be the string `IFNAME`.
+
+To set more than one `sysctl` for an interface, quote the whole `driver-opt` field,
+remembering to escape the quotes for the shell if necessary. For example, if the
+interface to `my-net` is given name `eth0`, the following example sets sysctls
+`net.ipv4.conf.eth0.log_martians=1` and `net.ipv4.conf.eth0.forwarding=0`, and
+assigns the IPv4 address `192.0.2.42`.
+
+```console
+$ docker network create --subnet 192.0.2.0/24 my-net
+$ docker run -itd --network=name=my-net,\"driver-opt=com.docker.network.endpoint.sysctls=net.ipv4.conf.IFNAME.log_martians=1,net.ipv4.conf.IFNAME.forwarding=0\",ip=192.0.2.42 busybox
+```
 
 > **Note**
 >
-> The default bridge network only allow containers to communicate with each other using
+> Network drivers may restrict the sysctl settings that can be modified and, to protect
-> internal IP addresses. User-created bridge networks provide DNS resolution between
+> the operation of the network, new restrictions may be added in the future.
-> containers using container names.
 
-You can disconnect a container from a network using the `docker network
+For more information on connecting a container to a network when using the `run` command,
-disconnect` command.
+see the [Docker network overview](https://docs.docker.com/network/).
-
-For more information on connecting a container to a network when using the `run` command, see the ["*Docker network overview*"](https://docs.docker.com/network/).
 
 ### <a name="volumes-from"></a> Mount volumes from container (--volumes-from)
 

docs/reference/commandline/network_connect.md

@@ -65,6 +65,26 @@ being connected to.
 $ docker network connect --alias db --alias mysql multi-host-network container2
 ```
 
+### <a name="sysctl"></a> Set sysctls for a container's interface (--driver-opt)
+
+`sysctl` settings that start with `net.ipv4.` and `net.ipv6.` can be set per-interface
+using `--driver-opt` label `com.docker.network.endpoint.sysctls`. The name of the
+interface must be replaced by `IFNAME`.
+
+To set more than one `sysctl` for an interface, quote the whole value of the
+`driver-opt` field, remembering to escape the quotes for the shell if necessary.
+For example, if the interface to `my-net` is given name `eth3`, the following example
+sets `net.ipv4.conf.eth3.log_martians=1` and `net.ipv4.conf.eth3.forwarding=0`.
+
+```console
+$ docker network connect --driver-opt=\"com.docker.network.endpoint.sysctls=net.ipv4.conf.IFNAME.log_martians=1,net.ipv4.conf.IFNAME.forwarding=0\" multi-host-network container2
+```
+
+> **Note**
+>
+> Network drivers may restrict the sysctl settings that can be modified and, to protect
+> the operation of the network, new restrictions may be added in the future.
+
 ### Network implications of stopping, pausing, or restarting containers
 
 You can pause, restart, and stop containers that are connected to a network.

opts/network_test.go

@@ -98,6 +98,20 @@ func TestNetworkOptAdvancedSyntax(t *testing.T) {
 				},
 			},
 		},
+		{
+			value: "name=docknet1,\"driver-opt=com.docker.network.endpoint.sysctls=net.ipv6.conf.IFNAME.accept_ra=2,net.ipv6.conf.IFNAME.forwarding=1\"",
+			expected: []NetworkAttachmentOpts{
+				{
+					Target:  "docknet1",
+					Aliases: []string{},
+					DriverOpts: map[string]string{
+						// The CLI converts IFNAME to ifname - it probably shouldn't, but the API
+						// allows ifname to cater for this.
+						"com.docker.network.endpoint.sysctls": "net.ipv6.conf.ifname.accept_ra=2,net.ipv6.conf.ifname.forwarding=1",
+					},
+				},
+			},
+		},
 	}
 	for _, tc := range testCases {
 		tc := tc