Merge pull request #19401 from wenchma/18410-default_net_driver

docs: document options for default network driver

docs/reference/commandline/network_create.md

@@ -21,8 +21,8 @@ parent = "smn_cli"
     --internal               Restricts external access to the network
     --ip-range=[]            Allocate container ip from a sub-range
     --ipam-driver=default    IP Address Management Driver
-    -o --opt=map[]           Set custom network plugin options
+    --ipam-opt=map[]         Set custom IPAM driver specific options
-    --ipam-opt=map[]         Set custom IPAM plugin options
+    -o --opt=map[]           Set custom driver specific options
     --subnet=[]              Subnet in CIDR format that represents a network segment
 
 Creates a new network. The `DRIVER` accepts `bridge` or `overlay` which are the
@@ -122,6 +122,26 @@ docker network create -d overlay
 ```
 Be sure that your subnetworks do not overlap. If they do, the network create fails and Engine returns an error.
 
+# Bridge driver options
+
+When creating a custom network, the default network driver (i.e. `bridge`) has additional options that can be passed.
+The following are those options and the equivalent docker daemon flags used for docker0 bridge:
+
+| Option                                           | Equivalent  | Description                                           |
+|--------------------------------------------------|-------------|-------------------------------------------------------|
+| `com.docker.network.bridge.name`                 | -           | bridge name to be used when creating the Linux bridge |
+| `com.docker.network.bridge.enable_ip_masquerade` | `--ip-masq` | Enable IP masquerading                                |
+| `com.docker.network.bridge.enable_icc`           | `--icc`     | Enable or Disable Inter Container Connectivity        |
+| `com.docker.network.bridge.host_binding_ipv4`    | `--ip`      | Default IP when binding container ports               |
+| `com.docker.network.mtu`                         | `--mtu`     | Set the containers network MTU                        |
+| `com.docker.network.enable_ipv6`                 | `--ipv6`    | Enable IPv6 networking                                |
+
+For example, let's use `-o` or `--opt` options to specify an IP address binding when publishing ports:
+
+```bash
+docker network create -o "com.docker.network.bridge.host_binding_ipv4"="172.19.0.1" simple-network
+```
+
 ### Network internal mode
 
 By default, when you connect a container to an `overlay` network, Docker also connects a bridge network to it to provide external connectivity.

docs/userguide/containers/networkingcontainers.md

@@ -168,7 +168,10 @@ If you inspect the network, you'll find that it has nothing in it.
             "IPAM": {
                 "Driver": "default",
                 "Config": [
-                    {}
+                    {
+                        "Subnet": "172.18.0.0/16",
+                        "Gateway": "172.18.0.1/16"
+                    }
                 ]
             },
             "Containers": {},

docs/userguide/networking/work-with-networks.md

@@ -95,6 +95,53 @@ $ docker network create -d overlay
 
 Be sure that your subnetworks do not overlap. If they do, the network create fails and Engine returns an error.
 
+When creating a custom network, the default network driver (i.e. `bridge`) has additional options that can be passed.
+The following are those options and the equivalent docker daemon flags used for docker0 bridge:
+
+| Option                                           | Equivalent  | Description                                           |
+|--------------------------------------------------|-------------|-------------------------------------------------------|
+| `com.docker.network.bridge.name`                 | -           | bridge name to be used when creating the Linux bridge |
+| `com.docker.network.bridge.enable_ip_masquerade` | `--ip-masq` | Enable IP masquerading                                |
+| `com.docker.network.bridge.enable_icc`           | `--icc`     | Enable or Disable Inter Container Connectivity        |
+| `com.docker.network.bridge.host_binding_ipv4`    | `--ip`      | Default IP when binding container ports               |
+| `com.docker.network.mtu`                         | `--mtu`     | Set the containers network MTU                        |
+| `com.docker.network.enable_ipv6`                 | `--ipv6`    | Enable IPv6 networking                                |
+
+For example, now let's use `-o` or `--opt` options to specify an IP address binding when publishing ports:
+
+```bash
+$ docker network create -o "com.docker.network.bridge.host_binding_ipv4"="172.23.0.1" my-network
+b1a086897963e6a2e7fc6868962e55e746bee8ad0c97b54a5831054b5f62672a
+$ docker network inspect my-network
+[
+    {
+        "Name": "my-network",
+        "Id": "b1a086897963e6a2e7fc6868962e55e746bee8ad0c97b54a5831054b5f62672a",
+        "Scope": "local",
+        "Driver": "bridge",
+        "IPAM": {
+            "Driver": "default",
+            "Options": {},
+            "Config": [
+                {
+                    "Subnet": "172.23.0.0/16",
+                    "Gateway": "172.23.0.1/16"
+                }
+            ]
+        },
+        "Containers": {},
+        "Options": {
+            "com.docker.network.bridge.host_binding_ipv4": "172.23.0.1"
+        }
+    }
+]
+$ docker run -d -P --name redis --net my-network redis
+bafb0c808c53104b2c90346f284bda33a69beadcab4fc83ab8f2c5a4410cd129
+$ docker ps
+CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                        NAMES
+bafb0c808c53        redis               "/entrypoint.sh redis"   4 seconds ago       Up 3 seconds        172.23.0.1:32770->6379/tcp   redis
+```
+
 ## Connect containers
 
 You can connect containers dynamically to one or more networks. These networks

man/docker-network-create.1.md

@@ -150,10 +150,10 @@ If you want to create an externally isolated `overlay` network, you can specify
   IP Address Management Driver
 
 **--ipam-opt**=map[]
-  Set custom IPAM plugin options
+  Set custom IPAM driver options
 
 **-o**, **--opt**=map[]
-  Set custom network plugin options
+  Set custom driver options
 
 **--subnet**=[]
   Subnet in CIDR format that represents a network segment