--- description: How to work with docker networks keywords: commands, Usage, network, docker, cluster title: Work with network commands --- This article provides examples of the network subcommands you can use to interact with Docker networks and the containers in them. The commands are available through the Docker Engine CLI. These commands are: * `docker network create` * `docker network connect` * `docker network ls` * `docker network rm` * `docker network disconnect` * `docker network inspect` While not required, it is a good idea to read [Understanding Docker network](index.md) before trying the examples in this section. The examples for the rely on a `bridge` network so that you can try them immediately. If you would prefer to experiment with an `overlay` network see the [Getting started with multi-host networks](get-started-overlay.md) instead. ## Create networks Docker Engine creates a `bridge` network automatically when you install Engine. This network corresponds to the `docker0` bridge that Engine has traditionally relied on. In addition to this network, you can create your own `bridge` or `overlay` network. A `bridge` network resides on a single host running an instance of Docker Engine. An `overlay` network can span multiple hosts running their own engines. If you run `docker network create` and supply only a network name, it creates a bridge network for you. ```bash $ docker network create simple-network 69568e6336d8c96bbf57869030919f7c69524f71183b44d80948bd3927c87f6a $ docker network inspect simple-network [ { "Name": "simple-network", "Id": "69568e6336d8c96bbf57869030919f7c69524f71183b44d80948bd3927c87f6a", "Scope": "local", "Driver": "bridge", "IPAM": { "Driver": "default", "Config": [ { "Subnet": "172.22.0.0/16", "Gateway": "172.22.0.1" } ] }, "Containers": {}, "Options": {}, "Labels": {} } ] ``` Unlike `bridge` networks, `overlay` networks require some pre-existing conditions before you can create one. These conditions are: * Access to a key-value store. Engine supports Consul, Etcd, and ZooKeeper (Distributed store) key-value stores. * A cluster of hosts with connectivity to the key-value store. * A properly configured Engine `daemon` on each host in the swarm. The `dockerd` options that support the `overlay` network are: * `--cluster-store` * `--cluster-store-opt` * `--cluster-advertise` When you create a network, Engine creates a non-overlapping subnetwork for the network by default. You can override this default and specify a subnetwork directly using the `--subnet` option. On a `bridge` network you can only specify a single subnet. An `overlay` network supports multiple subnets. > **Note** : It is highly recommended to use the `--subnet` option while creating > a network. If the `--subnet` is not specified, the docker daemon automatically > chooses and assigns a subnet for the network and it could overlap with another subnet > in your infrastructure that is not managed by docker. Such overlaps can cause > connectivity issues or failures when containers are connected to that network. In addition to the `--subnet` option, you also specify the `--gateway`, `--ip-range`, and `--aux-address` options. ```bash $ docker network create -d overlay \ --subnet=192.168.0.0/16 \ --subnet=192.170.0.0/16 \ --gateway=192.168.0.100 \ --gateway=192.170.0.100 \ --ip-range=192.168.1.0/24 \ --aux-address="my-router=192.168.1.5" --aux-address="my-switch=192.168.1.6" \ --aux-address="my-printer=192.170.1.5" --aux-address="my-nas=192.170.1.6" \ my-multihost-network ``` Be sure that your subnetworks do not overlap. If they do, network creation fails and Engine returns an error. When creating a custom network, you can pass additional options to the driver. The `bridge` driver accepts the following options: | 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.driver.mtu` | `--mtu` | Set the containers network MTU | The `com.docker.network.driver.mtu` option is also supported by the `overlay` driver. The following arguments can be passed to `docker network create` for any network driver. | Argument | Equivalent | Description | |--------------|------------|------------------------------------------| | `--internal` | - | Restricts external access to the network | | `--ipv6` | `--ipv6` | Enable IPv6 networking | The following example uses `-o` to bind to a specific IP address when binding ports, then uses `docker network inspect` to inspect the network, and finally attaches a new container to the new network. ```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" } ] }, "Containers": {}, "Options": { "com.docker.network.bridge.host_binding_ipv4": "172.23.0.1" }, "Labels": {} } ] $ docker run -d -P --name redis --network 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 an existing container to one or more networks. A container can connect to networks which use different network drivers. Once connected, the containers can communicate using 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 hosts can also communicate in this way. This example uses six containers, and directs you to create them as they are needed. ### Basic container networking example 1. First, create and run two containers, `container1` and `container2`: ```bash $ docker run -itd --name=container1 busybox 18c062ef45ac0c026ee48a83afa39d25635ee5f02b58de4abc8f467bcaa28731 $ docker run -itd --name=container2 busybox 498eaaaf328e1018042c04b2de04036fc04719a6e39a097a4f4866043a2c2152 ``` 2. Create an isolated, `bridge` network to test with. ```bash $ docker network create -d bridge --subnet 172.25.0.0/16 isolated_nw 06a62f1c73c4e3107c0f555b7a5f163309827bfbbf999840166065a8f35455a8 ``` 3. Connect `container2` to the network and then `inspect` the network to verify the connection: ```bash $ docker network connect isolated_nw container2 $ docker network inspect isolated_nw [ { "Name": "isolated_nw", "Id": "06a62f1c73c4e3107c0f555b7a5f163309827bfbbf999840166065a8f35455a8", "Scope": "local", "Driver": "bridge", "IPAM": { "Driver": "default", "Config": [ { "Subnet": "172.25.0.0/16", "Gateway": "172.25.0.1/16" } ] }, "Containers": { "90e1f3ec71caf82ae776a827e0712a68a110a3f175954e5bd4222fd142ac9428": { "Name": "container2", "EndpointID": "11cedac1810e864d6b1589d92da12af66203879ab89f4ccd8c8fdaa9b1c48b1d", "MacAddress": "02:42:ac:19:00:02", "IPv4Address": "172.25.0.2/16", "IPv6Address": "" } }, "Options": {} } ] ``` Notice that `container2` is assigned an IP address automatically. Because you specified a `--subnet` when creating the network, the IP address was chosen from that subnet. As a reminder, `container1` is only connected to the default `bridge` network. 4. Start a third container, but this time assign it an IP address using the `--ip` flag and connect it to the `isolated_nw` network using the `docker run` command's `--network` option: ```bash $ docker run --network=isolated_nw --ip=172.25.3.3 -itd --name=container3 busybox 467a7863c3f0277ef8e661b38427737f28099b61fa55622d6c30fb288d88c551 ``` As long as the IP address you specify for the container is part of the network's subnet, you can assign an IPv4 or IPv6 address to a container when connecting it to a network, by using the `--ip` or `--ip6` flag. when you specify an IP address in this way while using a user-defined network, the configuration is preserved as part of the container's configuration and will be applied when the container is reloaded. Assigned IP addresses are preserved when using non-user-defined networks, because there is no guarantee that a container's subnet will not change when the Docker daemon restarts unless you use user-defined networks. 5. Inspect the network resources used by `container3`. The output below is truncated for brevity. ```bash $ docker inspect --format='{{json .NetworkSettings.Networks}}' container3 {"isolated_nw": {"IPAMConfig": { "IPv4Address":"172.25.3.3"}, "NetworkID":"1196a4c5af43a21ae38ef34515b6af19236a3fc48122cf585e3f3054d509679b", "EndpointID":"dffc7ec2915af58cc827d995e6ebdc897342be0420123277103c40ae35579103", "Gateway":"172.25.0.1", "IPAddress":"172.25.3.3", "IPPrefixLen":16, "IPv6Gateway":"", "GlobalIPv6Address":"", "GlobalIPv6PrefixLen":0, "MacAddress":"02:42:ac:19:03:03"} } } } ``` Because you connected `container3` to the `isolated_nw` when you started it, it is not connected to the default `bridge` network at all. 6. Inspect the network resources used by `container2`. If you have Python installed, you can pretty print the output. ```bash $ docker inspect --format='{{json .NetworkSettings.Networks}}' container2 | python -m json.tool { "bridge": { "NetworkID":"7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", "EndpointID": "0099f9efb5a3727f6a554f176b1e96fca34cae773da68b3b6a26d046c12cb365", "Gateway": "172.17.0.1", "GlobalIPv6Address": "", "GlobalIPv6PrefixLen": 0, "IPAMConfig": null, "IPAddress": "172.17.0.3", "IPPrefixLen": 16, "IPv6Gateway": "", "MacAddress": "02:42:ac:11:00:03" }, "isolated_nw": { "NetworkID":"1196a4c5af43a21ae38ef34515b6af19236a3fc48122cf585e3f3054d509679b", "EndpointID": "11cedac1810e864d6b1589d92da12af66203879ab89f4ccd8c8fdaa9b1c48b1d", "Gateway": "172.25.0.1", "GlobalIPv6Address": "", "GlobalIPv6PrefixLen": 0, "IPAMConfig": null, "IPAddress": "172.25.0.2", "IPPrefixLen": 16, "IPv6Gateway": "", "MacAddress": "02:42:ac:19:00:02" } } ``` Notice that `container2` belongs to two networks. It joined the default `bridge` network when you launched it and you connected it to the `isolated_nw` in step 3. ![](images/working.png) eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:03 eth1 Link encap:Ethernet HWaddr 02:42:AC:15:00:02 7. Use the `docker attach` command to connect to the running `container2` and examine its networking stack: ```bash $ docker attach container2 ``` Use the `ifconfig` command to examine the container's networking stack. you should see two ethernet interfaces, one for the default `bridge` network, and the other for the `isolated_nw` network. ```bash $ sudo ifconfig -a eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:03 inet addr:172.17.0.3 Bcast:0.0.0.0 Mask:255.255.0.0 inet6 addr: fe80::42:acff:fe11:3/64 Scope:Link UP BROADCAST RUNNING MULTICAST MTU:9001 Metric:1 RX packets:8 errors:0 dropped:0 overruns:0 frame:0 TX packets:8 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:648 (648.0 B) TX bytes:648 (648.0 B) eth1 Link encap:Ethernet HWaddr 02:42:AC:15:00:02 inet addr:172.25.0.2 Bcast:0.0.0.0 Mask:255.255.0.0 inet6 addr: fe80::42:acff:fe19:2/64 Scope:Link UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:8 errors:0 dropped:0 overruns:0 frame:0 TX packets:8 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:648 (648.0 B) TX bytes:648 (648.0 B) lo Link encap:Local Loopback inet addr:127.0.0.1 Mask:255.0.0.0 inet6 addr: ::1/128 Scope:Host UP LOOPBACK RUNNING MTU:65536 Metric:1 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) ``` 8. The Docker embedded DNS server enables name resolution for containers connected to a given network. This means that any connected container can ping another container on the same network by its container name. From within `container2`, you can ping `container3` by name. ```bash / # ping -w 4 container3 PING container3 (172.25.3.3): 56 data bytes 64 bytes from 172.25.3.3: seq=0 ttl=64 time=0.070 ms 64 bytes from 172.25.3.3: seq=1 ttl=64 time=0.080 ms 64 bytes from 172.25.3.3: seq=2 ttl=64 time=0.080 ms 64 bytes from 172.25.3.3: seq=3 ttl=64 time=0.097 ms --- container3 ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 0.070/0.081/0.097 ms ``` This functionality is not available for the default `bridge` network. Both `container1` and `container2` are connected to the `bridge` network, but you cannot ping `container1` from `container2` using the container name. ```bash / # ping -w 4 container1 ping: bad address 'container1' ``` You can still ping the IP address directly: ```bash / # ping -w 4 172.17.0.2 PING 172.17.0.2 (172.17.0.2): 56 data bytes 64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.095 ms 64 bytes from 172.17.0.2: seq=1 ttl=64 time=0.075 ms 64 bytes from 172.17.0.2: seq=2 ttl=64 time=0.072 ms 64 bytes from 172.17.0.2: seq=3 ttl=64 time=0.101 ms --- 172.17.0.2 ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 0.072/0.085/0.101 ms ``` Detach from `container2` and leave it running using `CTRL-p CTRL-q`. 9. Currently, `container2` is attached to both `bridge` and `isolated_nw` networks, so it can communicate with both `container1` and `container3`. However, `container3` and `container1` do not have any networks in common, so they cannot communicate. To verify this, attach to `container3` and try to ping `container1` by IP address. ```bash $ docker attach container3 $ ping 172.17.0.2 PING 172.17.0.2 (172.17.0.2): 56 data bytes ^C --- 172.17.0.2 ping statistics --- 10 packets transmitted, 0 packets received, 100% packet loss ``` Detach from `container3` and leave it running using `CTRL-p CTRL-q`. >You can connect a container to a network even if the container is not running. However, `docker network inspect` only displays information on running containers. ### Linking containers without using user-defined networks After you complete the steps in [Basic container networking examples](#basic-container-networking-examples), `container2` can resolve `container3`'s name automatically because both containers are connected to the `isolated_nw` network. However, containers connected to the default `bridge` network cannot resolve each other's container name. If you need containers to be able to communicate with each other over the `bridge` network, you need to use the legacy [link](default_network/dockerlinks.md) feature. This is the only use case where using `--link` is recommended. You should strongly consider using user-defined networks instead. Using the legacy `link` flag adds the following features for communication between communication on the default `bridge` network: * the ability to resolve container names to IP addresses * the ability to define a network alias as an alternate way to refer to the linked container, using `--link=CONTAINER-NAME:ALIAS` * secured container connectivity (in isolation via `--icc=false`) * environment variable injection To reiterate, all of these features are provided by default when you use a user-defined network, with no additional configuration required. **Additionally, you get the ability to dynamically attach to and detach from multiple networks.** * automatic name resolution using DNS * supports the `--link` option to provide name alias for the linked container * automatic secured isolated environment for the containers in a network * environment variable injection The following example briefly describes how to use `--link`. 1. Continuing with the above example, create a new container, `container4`, and connect it to the network `isolated_nw`. In addition, link it to container `container5` (which does not exist yet!) using the `--link` flag. ```bash $ docker run --network=isolated_nw -itd --name=container4 --link container5:c5 busybox 01b5df970834b77a9eadbaff39051f237957bd35c4c56f11193e0594cfd5117c ``` This is a little tricky, because `container5` does not exist yet. When `container5` is created, `container4` will be able to resolve the name `c5` to `container5`'s IP address. >**Note:** Any link between containers created with *legacy link* is static in nature and hard-binds the container with the alias. It does not tolerate linked container restarts. The new *link* functionality in user defined networks supports dynamic links between containers, and tolerates restarts and IP address changes in the linked container. Since you have not yet created container `container5` trying to ping it will result in an error. Attach to `container4` and try to ping either `container5` or `c5`: ```bash $ docker attach container4 $ ping container5 ping: bad address 'container5' $ ping c5 ping: bad address 'c5' ``` Detach from `container3` and leave it running using `CTRL-p CTRL-q`. 2. Create another container named `container5`, and link it to `container4` using the alias `c4`. ```bash $ docker run --network=isolated_nw -itd --name=container5 --link container4:c4 busybox 72eccf2208336f31e9e33ba327734125af00d1e1d2657878e2ee8154fbb23c7a ``` Now attach to `container4` and try to ping `c5` and `container5`. ```bash $ docker attach container4 / # ping -w 4 c5 PING c5 (172.25.0.5): 56 data bytes 64 bytes from 172.25.0.5: seq=0 ttl=64 time=0.070 ms 64 bytes from 172.25.0.5: seq=1 ttl=64 time=0.080 ms 64 bytes from 172.25.0.5: seq=2 ttl=64 time=0.080 ms 64 bytes from 172.25.0.5: seq=3 ttl=64 time=0.097 ms --- c5 ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 0.070/0.081/0.097 ms / # ping -w 4 container5 PING container5 (172.25.0.5): 56 data bytes 64 bytes from 172.25.0.5: seq=0 ttl=64 time=0.070 ms 64 bytes from 172.25.0.5: seq=1 ttl=64 time=0.080 ms 64 bytes from 172.25.0.5: seq=2 ttl=64 time=0.080 ms 64 bytes from 172.25.0.5: seq=3 ttl=64 time=0.097 ms --- container5 ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 0.070/0.081/0.097 ms ``` Detach from `container4` and leave it running using `CTRL-p CTRL-q`. 3. Finally, attach to `container5` and verify that you can ping `container4`. ```bash $ docker attach container5 / # ping -w 4 c4 PING c4 (172.25.0.4): 56 data bytes 64 bytes from 172.25.0.4: seq=0 ttl=64 time=0.065 ms 64 bytes from 172.25.0.4: seq=1 ttl=64 time=0.070 ms 64 bytes from 172.25.0.4: seq=2 ttl=64 time=0.067 ms 64 bytes from 172.25.0.4: seq=3 ttl=64 time=0.082 ms --- c4 ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 0.065/0.070/0.082 ms / # ping -w 4 container4 PING container4 (172.25.0.4): 56 data bytes 64 bytes from 172.25.0.4: seq=0 ttl=64 time=0.065 ms 64 bytes from 172.25.0.4: seq=1 ttl=64 time=0.070 ms 64 bytes from 172.25.0.4: seq=2 ttl=64 time=0.067 ms 64 bytes from 172.25.0.4: seq=3 ttl=64 time=0.082 ms --- container4 ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 0.065/0.070/0.082 ms ``` Detach from `container5` and leave it running using `CTRL-p CTRL-q`. ### Network alias scoping example When you link containers, whether using the legacy `link` method or using user-defined networks, any aliases you specify only have meaning to the container where they are specified, and won't work on other containers on the default `bridge` network. In addition, if a container belongs to multiple networks, a given linked alias is scoped within a given network. Thus, a container can be linked to different aliases in different networks, and the aliases will not work for containers which are not on the same network. The following example illustrates these points. 1. Create another network named `local_alias` ```bash $ docker network create -d bridge --subnet 172.26.0.0/24 local_alias 76b7dc932e037589e6553f59f76008e5b76fa069638cd39776b890607f567aaa ``` 2. Next, connect `container4` and `container5` to the new network `local_alias` with the aliases `foo` and `bar`: ```bash $ docker network connect --link container5:foo local_alias container4 $ docker network connect --link container4:bar local_alias container5 ``` 3. Attach to `container3` and try to ping `container4` using alias `foo`, then try pinging container `container5` using alias `c5`: ```bash $ docker attach container4 / # ping -w 4 foo PING foo (172.26.0.3): 56 data bytes 64 bytes from 172.26.0.3: seq=0 ttl=64 time=0.070 ms 64 bytes from 172.26.0.3: seq=1 ttl=64 time=0.080 ms 64 bytes from 172.26.0.3: seq=2 ttl=64 time=0.080 ms 64 bytes from 172.26.0.3: seq=3 ttl=64 time=0.097 ms --- foo ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 0.070/0.081/0.097 ms / # ping -w 4 c5 PING c5 (172.25.0.5): 56 data bytes 64 bytes from 172.25.0.5: seq=0 ttl=64 time=0.070 ms 64 bytes from 172.25.0.5: seq=1 ttl=64 time=0.080 ms 64 bytes from 172.25.0.5: seq=2 ttl=64 time=0.080 ms 64 bytes from 172.25.0.5: seq=3 ttl=64 time=0.097 ms --- c5 ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 0.070/0.081/0.097 ms ``` Both pings succeed, but the subnets are different, which means that the networks are different. Detach from `container4` and leave it running using `CTRL-p CTRL-q`. 4. Disconnect `container5` from the `isolated_nw` network. Attach to `container4` and try pinging `c5` and `foo`. ``` $ docker network disconnect isolated_nw container5 $ docker attach container4 / # ping -w 4 c5 ping: bad address 'c5' / # ping -w 4 foo PING foo (172.26.0.3): 56 data bytes 64 bytes from 172.26.0.3: seq=0 ttl=64 time=0.070 ms 64 bytes from 172.26.0.3: seq=1 ttl=64 time=0.080 ms 64 bytes from 172.26.0.3: seq=2 ttl=64 time=0.080 ms 64 bytes from 172.26.0.3: seq=3 ttl=64 time=0.097 ms --- foo ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 0.070/0.081/0.097 ms ``` You can no longer reach containers on the `isolated_nw` network from `container5`. However, you can still reach `container4` (from `container4`) using the alias `foo`. Detach from `container4` and leave it running using `CTRL-p CTRL-q`. ### Limitations of `docker network` Although `docker network` is the recommended way to control the networks your containers use, it does have some limitations. #### Environment variable injection Environment variable injection is static in nature and environment variables cannot be changed after a container is started. The legacy `--link` flag shares all environment variables to the linked container, but the `docker network` command has no equivalent. When you connect to a network using `docker network`, no environment variables can be dynamically among containers. #### Understanding network-scoped aliases Legacy links provide outgoing name resolution that is isolated within the container in which the alias is configured. Network-scoped aliases do not allow for this one-way isolation, but provide the alias to all members of the network. The following example illustrates this limitation. 1. Create another container called `container6` in the network `isolated_nw` and give it the network alias `app`. ```bash $ docker run --network=isolated_nw -itd --name=container6 --network-alias app busybox 8ebe6767c1e0361f27433090060b33200aac054a68476c3be87ef4005eb1df17 ``` 2. Attach to `container4`. Try pinging the container by name (`container6`) and by network alias (`app`). Notice that the IP address is the same. ```bash $ docker attach container4 / # ping -w 4 app PING app (172.25.0.6): 56 data bytes 64 bytes from 172.25.0.6: seq=0 ttl=64 time=0.070 ms 64 bytes from 172.25.0.6: seq=1 ttl=64 time=0.080 ms 64 bytes from 172.25.0.6: seq=2 ttl=64 time=0.080 ms 64 bytes from 172.25.0.6: seq=3 ttl=64 time=0.097 ms --- app ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 0.070/0.081/0.097 ms / # ping -w 4 container6 PING container5 (172.25.0.6): 56 data bytes 64 bytes from 172.25.0.6: seq=0 ttl=64 time=0.070 ms 64 bytes from 172.25.0.6: seq=1 ttl=64 time=0.080 ms 64 bytes from 172.25.0.6: seq=2 ttl=64 time=0.080 ms 64 bytes from 172.25.0.6: seq=3 ttl=64 time=0.097 ms --- container6 ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 0.070/0.081/0.097 ms ``` Detach from `container4` and leave it running using `CTRL-p CTRL-q`. 3. Connect `container6` to the `local_alias` network with the network-scoped alias `scoped-app`. ```bash $ docker network connect --alias scoped-app local_alias container6 ``` Now `container6` is aliased as `app` in network `isolated_nw` and as `scoped-app` in network `local_alias`. 4. Try to reach these aliases from `container4` (which is connected to both these networks) and `container5` (which is connected only to `isolated_nw`). ```bash $ docker attach container4 / # ping -w 4 scoped-app PING foo (172.26.0.5): 56 data bytes 64 bytes from 172.26.0.5: seq=0 ttl=64 time=0.070 ms 64 bytes from 172.26.0.5: seq=1 ttl=64 time=0.080 ms 64 bytes from 172.26.0.5: seq=2 ttl=64 time=0.080 ms 64 bytes from 172.26.0.5: seq=3 ttl=64 time=0.097 ms --- foo ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max = 0.070/0.081/0.097 ms ``` Detach from `container4` and leave it running using `CTRL-p CTRL-q`. ```bash $ docker attach container5 / # ping -w 4 scoped-app ping: bad address 'scoped-app' ``` Detach from `container5` and leave it running using `CTRL-p CTRL-q`. This shows that an alias is scoped to the network where it is defined, and only containers connected to that network can access the alias. #### Resolving multiple containers to a single alias Multiple containers can share the same network-scoped alias within the same network. This example illustrates how this works. 1. Launch `container7` in `isolated_nw` with the same alias as `container6`, which is `app`. ```bash $ docker run --network=isolated_nw -itd --name=container7 --network-alias app busybox 3138c678c123b8799f4c7cc6a0cecc595acbdfa8bf81f621834103cd4f504554 ``` When multiple containers share the same alias, one of those containers will resolve to the alias. If that container is unavailable, another container with the alias will be resolved. This provides a sort of high availability within the cluster. > When the IP address is resolved, the container chosen to resolve it is random. For that reason, in the exercises below, you may get different results in some steps. If the step assumes the result returned is `container6` but you get `container7`, this is why. 2. Start a continuous ping from `container4` to the `app` alias. ```bash $ docker attach container4 $ ping app PING app (172.25.0.6): 56 data bytes 64 bytes from 172.25.0.6: seq=0 ttl=64 time=0.070 ms 64 bytes from 172.25.0.6: seq=1 ttl=64 time=0.080 ms 64 bytes from 172.25.0.6: seq=2 ttl=64 time=0.080 ms 64 bytes from 172.25.0.6: seq=3 ttl=64 time=0.097 ms ... ``` The IP address that is returned belongs to `container6`. 3. In another terminal, stop `container6`. ```bash $ docker stop container6 ``` In the terminal attached to `container4`, observe the `ping` output. It will pause when `container6` goes down, because the `ping` command looks up the IP when it is first invoked, and that IP is no longer reachable. However, the `ping` command has a very long timeout by default, so no error occurs. 4. Exit the `ping` command using `CTRL+C` and run it again. ```bash $ ping app PING app (172.25.0.7): 56 data bytes 64 bytes from 172.25.0.7: seq=0 ttl=64 time=0.095 ms 64 bytes from 172.25.0.7: seq=1 ttl=64 time=0.075 ms 64 bytes from 172.25.0.7: seq=2 ttl=64 time=0.072 ms 64 bytes from 172.25.0.7: seq=3 ttl=64 time=0.101 ms ... ``` The `app` alias now resolves to the IP address of `container7`. 5. For one last test, restart `container6`. ```bash $ docker start container6 ``` In the terminal attached to `container4`, run the `ping` command again. It might now resolve to `container6` again. If you start and stop the `ping` several times, you will see responses from each of the containers. ```bash $ docker attach container4 $ ping app PING app (172.25.0.6): 56 data bytes 64 bytes from 172.25.0.6: seq=0 ttl=64 time=0.070 ms 64 bytes from 172.25.0.6: seq=1 ttl=64 time=0.080 ms 64 bytes from 172.25.0.6: seq=2 ttl=64 time=0.080 ms 64 bytes from 172.25.0.6: seq=3 ttl=64 time=0.097 ms ... ``` Stop the ping with `CTRL+C`. Detach from `container4` and leave it running using `CTRL-p CTRL-q`. ## Disconnecting containers You can disconnect a container from a network at any time using the `docker network disconnect` command. 1. Disconnect `container2` from the `isolated_nw` network, then inspect `container2` and the `isolated_nw` network. ```bash $ docker network disconnect isolated_nw container2 $ docker inspect --format='{{json .NetworkSettings.Networks}}' container2 | python -m json.tool { "bridge": { "NetworkID":"7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", "EndpointID": "9e4575f7f61c0f9d69317b7a4b92eefc133347836dd83ef65deffa16b9985dc0", "Gateway": "172.17.0.1", "GlobalIPv6Address": "", "GlobalIPv6PrefixLen": 0, "IPAddress": "172.17.0.3", "IPPrefixLen": 16, "IPv6Gateway": "", "MacAddress": "02:42:ac:11:00:03" } } $ docker network inspect isolated_nw [ { "Name": "isolated_nw", "Id": "06a62f1c73c4e3107c0f555b7a5f163309827bfbbf999840166065a8f35455a8", "Scope": "local", "Driver": "bridge", "IPAM": { "Driver": "default", "Config": [ { "Subnet": "172.21.0.0/16", "Gateway": "172.21.0.1/16" } ] }, "Containers": { "467a7863c3f0277ef8e661b38427737f28099b61fa55622d6c30fb288d88c551": { "Name": "container3", "EndpointID": "dffc7ec2915af58cc827d995e6ebdc897342be0420123277103c40ae35579103", "MacAddress": "02:42:ac:19:03:03", "IPv4Address": "172.25.3.3/16", "IPv6Address": "" } }, "Options": {} } ] ``` 2. When a container is disconnected from a network, it can no longer communicate with other containers connected to that network, unless it has other networks in common with them. Verify that `container2` can no longer reach `container3`, which is on the `isolated_nw` network. ```bash $ docker attach container2 / # ifconfig eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:03 inet addr:172.17.0.3 Bcast:0.0.0.0 Mask:255.255.0.0 inet6 addr: fe80::42:acff:fe11:3/64 Scope:Link UP BROADCAST RUNNING MULTICAST MTU:9001 Metric:1 RX packets:8 errors:0 dropped:0 overruns:0 frame:0 TX packets:8 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:648 (648.0 B) TX bytes:648 (648.0 B) lo Link encap:Local Loopback inet addr:127.0.0.1 Mask:255.0.0.0 inet6 addr: ::1/128 Scope:Host UP LOOPBACK RUNNING MTU:65536 Metric:1 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) / # ping container3 PING container3 (172.25.3.3): 56 data bytes ^C --- container3 ping statistics --- 2 packets transmitted, 0 packets received, 100% packet loss ``` 3. Verify that `container2` still has full connectivity to the default `bridge` network. ```bash / # ping container1 PING container1 (172.17.0.2): 56 data bytes 64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.119 ms 64 bytes from 172.17.0.2: seq=1 ttl=64 time=0.174 ms ^C --- container1 ping statistics --- 2 packets transmitted, 2 packets received, 0% packet loss round-trip min/avg/max = 0.119/0.146/0.174 ms / # ``` 4. Remove `container4`, `container5`, `container6`, and `container7`. ```bash $ docker stop container4 container5 container6 container7 $ docker rm container4 container5 container6 container7 ``` ### Handling stale network endpoints In some scenarios, such as ungraceful docker daemon restarts in a multi-host network, the daemon cannot clean up stale connectivity endpoints. Such stale endpoints may cause an error if a new container is connected to that network with the same name as the stale endpoint: ```no-highlight ERROR: Cannot start container bc0b19c089978f7845633027aa3435624ca3d12dd4f4f764b61eac4c0610f32e: container already connected to network multihost ``` To clean up these stale endpoints, remove the container and disconnect it from the network forcibly (`docker network disconnect -f`). Now you can successfully connect the container to the network. ```bash $ docker run -d --name redis_db --network multihost redis ERROR: Cannot start container bc0b19c089978f7845633027aa3435624ca3d12dd4f4f764b61eac4c0610f32e: container already connected to network multihost $ docker rm -f redis_db $ docker network disconnect -f multihost redis_db $ docker run -d --name redis_db --network multihost redis 7d986da974aeea5e9f7aca7e510bdb216d58682faa83a9040c2f2adc0544795a ``` ## Remove a network When all the containers in a network are stopped or disconnected, you can remove a network. If a network has connected endpoints, an error occurs. 1. Disconnect `container3` from `isolated_nw`. ```bash $ docker network disconnect isolated_nw container3 ``` 2. Inspect `isolated_nw` to verify that no other endpoints are connected to it. ```bash $ docker network inspect isolated_nw [ { "Name": "isolated_nw", "Id": "06a62f1c73c4e3107c0f555b7a5f163309827bfbbf999840166065a8f35455a8", "Scope": "local", "Driver": "bridge", "IPAM": { "Driver": "default", "Config": [ { "Subnet": "172.21.0.0/16", "Gateway": "172.21.0.1/16" } ] }, "Containers": {}, "Options": {} } ] ``` 3. Remove the `isolated_nw` network. ```bash $ docker network rm isolated_nw ``` 4. List all your networks to verify that `isolated_nw` no longer exists: ```bash $ docker network ls NETWORK ID NAME DRIVER SCOPE 4bb8c9bf4292 bridge bridge local 43575911a2bd host host local 76b7dc932e03 local_alias bridge local b1a086897963 my-network bridge local 3eb020e70bfd none null local 69568e6336d8 simple-network bridge local ``` ## Related information * [network create](../../reference/commandline/network_create.md) * [network inspect](../../reference/commandline/network_inspect.md) * [network connect](../../reference/commandline/network_connect.md) * [network disconnect](../../reference/commandline/network_disconnect.md) * [network ls](../../reference/commandline/network_ls.md) * [network rm](../../reference/commandline/network_rm.md)