github.com/walkingsparrow/docker@v1.4.2-0.20151218153551-b708a2249bfa/docs/userguide/networking/work-with-networks.md (about) 1 <!--[metadata]> 2 +++ 3 title = "Work with network commands" 4 description = "How to work with docker networks" 5 keywords = ["commands, Usage, network, docker, cluster"] 6 [menu.main] 7 parent = "smn_networking" 8 weight=-4 9 +++ 10 <![end-metadata]--> 11 12 # Work with network commands 13 14 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: 15 16 * `docker network create` 17 * `docker network connect` 18 * `docker network ls` 19 * `docker network rm` 20 * `docker network disconnect` 21 * `docker network inspect` 22 23 While not required, it is a good idea to read [Understanding Docker 24 network](dockernetworks.md) before trying the examples in this section. The 25 examples for the rely on a `bridge` network so that you can try them 26 immediately. If you would prefer to experiment with an `overlay` network see 27 the [Getting started with multi-host networks](get-started-overlay.md) instead. 28 29 ## Create networks 30 31 Docker Engine creates a `bridge` network automatically when you install Engine. 32 This network corresponds to the `docker0` bridge that Engine has traditionally 33 relied on. In addition to this network, you can create your own `bridge` or `overlay` network. 34 35 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. 36 37 ```bash 38 $ docker network create simple-network 39 de792b8258895cf5dc3b43835e9d61a9803500b991654dacb1f4f0546b1c88f8 40 $ docker network inspect simple-network 41 [ 42 { 43 "Name": "simple-network", 44 "Id": "de792b8258895cf5dc3b43835e9d61a9803500b991654dacb1f4f0546b1c88f8", 45 "Scope": "local", 46 "Driver": "bridge", 47 "IPAM": { 48 "Driver": "default", 49 "Config": [ 50 {} 51 ] 52 }, 53 "Containers": {}, 54 "Options": {} 55 } 56 ] 57 ``` 58 59 Unlike `bridge` networks, `overlay` networks require some pre-existing conditions 60 before you can create one. These conditions are: 61 62 * Access to a key-value store. Engine supports Consul Etcd, and ZooKeeper (Distributed store) key-value stores. 63 * A cluster of hosts with connectivity to the key-value store. 64 * A properly configured Engine `daemon` on each host in the swarm. 65 66 The `docker daemon` options that support the `overlay` network are: 67 68 * `--cluster-store` 69 * `--cluster-store-opt` 70 * `--cluster-advertise` 71 72 It is also a good idea, though not required, that you install Docker Swarm 73 to manage the cluster. Swarm provides sophisticated discovery and server 74 management that can assist your implementation. 75 76 When you create a network, Engine creates a non-overlapping subnetwork for the 77 network by default. You can override this default and specify a subnetwork 78 directly using the the `--subnet` option. On a `bridge` network you can only 79 create a single subnet. An `overlay` network supports multiple subnets. 80 81 In addition to the `--subnetwork` option, you also specify the `--gateway` `--ip-range` and `--aux-address` options. 82 83 ```bash 84 $ docker network create -d overlay 85 --subnet=192.168.0.0/16 --subnet=192.170.0.0/16 86 --gateway=192.168.0.100 --gateway=192.170.0.100 87 --ip-range=192.168.1.0/24 88 --aux-address a=192.168.1.5 --aux-address b=192.168.1.6 89 --aux-address a=192.170.1.5 --aux-address b=192.170.1.6 90 my-multihost-network 91 ``` 92 93 Be sure that your subnetworks do not overlap. If they do, the network create fails and Engine returns an error. 94 95 ## Connect containers 96 97 You can connect containers dynamically to one or more networks. These networks 98 can be backed the same or different network drivers. Once connected, the 99 containers can communicate using another container's IP address or name. 100 101 For `overlay` networks or custom plugins that support multi-host 102 connectivity, containers connected to the same multi-host network but launched 103 from different hosts can also communicate in this way. 104 105 Create two containers for this example: 106 107 ```bash 108 $ docker run -itd --name=container1 busybox 109 18c062ef45ac0c026ee48a83afa39d25635ee5f02b58de4abc8f467bcaa28731 110 111 $ docker run -itd --name=container2 busybox 112 498eaaaf328e1018042c04b2de04036fc04719a6e39a097a4f4866043a2c2152 113 ``` 114 115 Then create an isolated, `bridge` network to test with. 116 117 ```bash 118 $ docker network create -d bridge isolated_nw 119 f836c8deb6282ee614eade9d2f42d590e603d0b1efa0d99bd88b88c503e6ba7a 120 ``` 121 122 Connect `container2` to the network and then `inspect` the network to verify the connection: 123 124 ``` 125 $ docker network connect isolated_nw container2 126 $ docker network inspect isolated_nw 127 [[ 128 { 129 "Name": "isolated_nw", 130 "Id": "f836c8deb6282ee614eade9d2f42d590e603d0b1efa0d99bd88b88c503e6ba7a", 131 "Scope": "local", 132 "Driver": "bridge", 133 "IPAM": { 134 "Driver": "default", 135 "Config": [ 136 {} 137 ] 138 }, 139 "Containers": { 140 "498eaaaf328e1018042c04b2de04036fc04719a6e39a097a4f4866043a2c2152": { 141 "EndpointID": "0e24479cfaafb029104999b4e120858a07b19b1b6d956ae56811033e45d68ad9", 142 "MacAddress": "02:42:ac:15:00:02", 143 "IPv4Address": "172.21.0.2/16", 144 "IPv6Address": "" 145 } 146 }, 147 "Options": {} 148 } 149 ] 150 ``` 151 152 You can see that the Engine automatically assigns an IP address to `container2`. 153 If you had specified a `--subnetwork` when creating your network, the network 154 would have used that addressing. Now, start a third container and connect it to 155 the network on launch using the `docker run` command's `--net` option: 156 157 ```bash 158 $ docker run --net=isolated_nw -itd --name=container3 busybox 159 c282ca437ee7e926a7303a64fc04109740208d2c20e442366139322211a6481c 160 ``` 161 162 Now, inspect the network resources used by `container3`. 163 164 ```bash 165 $ docker inspect --format='{{json .NetworkSettings.Networks}}' container3 166 {"isolated_nw":{"EndpointID":"e5d077f9712a69c6929fdd890df5e7c1c649771a50df5b422f7e68f0ae61e847","Gateway":"172.21.0.1","IPAddress":"172.21.0.3","IPPrefixLen":16,"IPv6Gateway":"","GlobalIPv6Address":"","GlobalIPv6PrefixLen":0,"MacAddress":"02:42:ac:15:00:03"}} 167 ``` 168 Repeat this command for `container2`. If you have Python installed, you can pretty print the output. 169 170 ```bash 171 $ docker inspect --format='{{json .NetworkSettings.Networks}}' container2 | python -m json.tool 172 { 173 "bridge": { 174 "EndpointID": "281b5ead415cf48a6a84fd1a6504342c76e9091fe09b4fdbcc4a01c30b0d3c5b", 175 "Gateway": "172.17.0.1", 176 "GlobalIPv6Address": "", 177 "GlobalIPv6PrefixLen": 0, 178 "IPAddress": "172.17.0.3", 179 "IPPrefixLen": 16, 180 "IPv6Gateway": "", 181 "MacAddress": "02:42:ac:11:00:03" 182 }, 183 "isolated_nw": { 184 "EndpointID": "0e24479cfaafb029104999b4e120858a07b19b1b6d956ae56811033e45d68ad9", 185 "Gateway": "172.21.0.1", 186 "GlobalIPv6Address": "", 187 "GlobalIPv6PrefixLen": 0, 188 "IPAddress": "172.21.0.2", 189 "IPPrefixLen": 16, 190 "IPv6Gateway": "", 191 "MacAddress": "02:42:ac:15:00:02" 192 } 193 } 194 ``` 195 196 You should find `container2` belongs to two networks. The `bridge` network 197 which it joined by default when you launched it and the `isolated_nw` which you 198 later connected it to. 199 200  201 202 In the case of `container3`, you connected it through `docker run` to the 203 `isolated_nw` so that container is not connected to `bridge`. 204 205 Use the `docker attach` command to connect to the running `container2` and 206 examine its networking stack: 207 208 ```bash 209 $ docker attach container2 210 ``` 211 212 If you look a the container's network stack you should see two Ethernet interfaces, one for the default bridge network and one for the `isolated_nw` network. 213 214 ```bash 215 / # ifconfig 216 eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:03 217 inet addr:172.17.0.3 Bcast:0.0.0.0 Mask:255.255.0.0 218 inet6 addr: fe80::42:acff:fe11:3/64 Scope:Link 219 UP BROADCAST RUNNING MULTICAST MTU:9001 Metric:1 220 RX packets:8 errors:0 dropped:0 overruns:0 frame:0 221 TX packets:8 errors:0 dropped:0 overruns:0 carrier:0 222 collisions:0 txqueuelen:0 223 RX bytes:648 (648.0 B) TX bytes:648 (648.0 B) 224 225 eth1 Link encap:Ethernet HWaddr 02:42:AC:15:00:02 226 inet addr:172.21.0.2 Bcast:0.0.0.0 Mask:255.255.0.0 227 inet6 addr: fe80::42:acff:fe15:2/64 Scope:Link 228 UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 229 RX packets:8 errors:0 dropped:0 overruns:0 frame:0 230 TX packets:8 errors:0 dropped:0 overruns:0 carrier:0 231 collisions:0 txqueuelen:0 232 RX bytes:648 (648.0 B) TX bytes:648 (648.0 B) 233 234 lo Link encap:Local Loopback 235 inet addr:127.0.0.1 Mask:255.0.0.0 236 inet6 addr: ::1/128 Scope:Host 237 UP LOOPBACK RUNNING MTU:65536 Metric:1 238 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 239 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 240 collisions:0 txqueuelen:0 241 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) 242 ``` 243 244 Display the container's `etc/hosts` file: 245 246 ```bash 247 / # cat /etc/hosts 248 172.17.0.3 498eaaaf328e 249 127.0.0.1 localhost 250 ::1 localhost ip6-localhost ip6-loopback 251 fe00::0 ip6-localnet 252 ff00::0 ip6-mcastprefix 253 ff02::1 ip6-allnodes 254 ff02::2 ip6-allrouters 255 172.21.0.3 container3 256 172.21.0.3 container3.isolated_nw 257 ``` 258 259 On the `isolated_nw` which was user defined, the Docker network feature updated the `/etc/hosts` with the proper name resolution. Inside of `container2` it is possible to ping `container3` by name. 260 261 ```bash 262 / # ping -w 4 container3 263 PING container3 (172.21.0.3): 56 data bytes 264 64 bytes from 172.21.0.3: seq=0 ttl=64 time=0.070 ms 265 64 bytes from 172.21.0.3: seq=1 ttl=64 time=0.080 ms 266 64 bytes from 172.21.0.3: seq=2 ttl=64 time=0.080 ms 267 64 bytes from 172.21.0.3: seq=3 ttl=64 time=0.097 ms 268 269 --- container3 ping statistics --- 270 4 packets transmitted, 4 packets received, 0% packet loss 271 round-trip min/avg/max = 0.070/0.081/0.097 ms 272 ``` 273 274 This isn't the case for the default bridge network. Both `container2` and `container1` are connected to the default bridge network. Docker does not support automatic service discovery on this network. For this reason, pinging `container1` by name fails as you would expect based on the `/etc/hosts` file: 275 276 ```bash 277 / # ping -w 4 container1 278 ping: bad address 'container1' 279 ``` 280 281 A ping using the `container1` IP address does succeed though: 282 283 ```bash 284 / # ping -w 4 172.17.0.2 285 PING 172.17.0.2 (172.17.0.2): 56 data bytes 286 64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.095 ms 287 64 bytes from 172.17.0.2: seq=1 ttl=64 time=0.075 ms 288 64 bytes from 172.17.0.2: seq=2 ttl=64 time=0.072 ms 289 64 bytes from 172.17.0.2: seq=3 ttl=64 time=0.101 ms 290 291 --- 172.17.0.2 ping statistics --- 292 4 packets transmitted, 4 packets received, 0% packet loss 293 round-trip min/avg/max = 0.072/0.085/0.101 ms 294 ``` 295 296 If you wanted you could connect `container1` to `container2` with the `docker 297 run --link` command and that would enable the two containers to interact by name 298 as well as IP. 299 300 Detach from a `container2` and leave it running using `CTRL-p CTRL-q`. 301 302 In this example, `container2` is attached to both networks and so can talk to 303 `container1` and `container3`. But `container3` and `container1` are not in the 304 same network and cannot communicate. Test, this now by attaching to 305 `container3` and attempting to ping `container1` by IP address. 306 307 ```bash 308 $ docker attach container3 309 / # ping 172.17.0.2 310 PING 172.17.0.2 (172.17.0.2): 56 data bytes 311 ^C 312 --- 172.17.0.2 ping statistics --- 313 10 packets transmitted, 0 packets received, 100% packet loss 314 315 ``` 316 317 To connect a container to a network, the container must be running. If you stop 318 a container and inspect a network it belongs to, you won't see that container. 319 The `docker network inspect` command only shows running containers. 320 321 ## Disconnecting containers 322 323 You can disconnect a container from a network using the `docker network 324 disconnect` command. 325 326 ``` 327 $ docker network disconnect isolated_nw container2 328 329 docker inspect --format='{{json .NetworkSettings.Networks}}' container2 | python -m json.tool 330 { 331 "bridge": { 332 "EndpointID": "9e4575f7f61c0f9d69317b7a4b92eefc133347836dd83ef65deffa16b9985dc0", 333 "Gateway": "172.17.0.1", 334 "GlobalIPv6Address": "", 335 "GlobalIPv6PrefixLen": 0, 336 "IPAddress": "172.17.0.3", 337 "IPPrefixLen": 16, 338 "IPv6Gateway": "", 339 "MacAddress": "02:42:ac:11:00:03" 340 } 341 } 342 343 344 $ docker network inspect isolated_nw 345 [[ 346 { 347 "Name": "isolated_nw", 348 "Id": "f836c8deb6282ee614eade9d2f42d590e603d0b1efa0d99bd88b88c503e6ba7a", 349 "Scope": "local", 350 "Driver": "bridge", 351 "IPAM": { 352 "Driver": "default", 353 "Config": [ 354 {} 355 ] 356 }, 357 "Containers": { 358 "c282ca437ee7e926a7303a64fc04109740208d2c20e442366139322211a6481c": { 359 "EndpointID": "e5d077f9712a69c6929fdd890df5e7c1c649771a50df5b422f7e68f0ae61e847", 360 "MacAddress": "02:42:ac:15:00:03", 361 "IPv4Address": "172.21.0.3/16", 362 "IPv6Address": "" 363 } 364 }, 365 "Options": {} 366 } 367 ] 368 ``` 369 370 Once a container is disconnected from a network, it cannot communicate with 371 other containers connected to that network. In this example, `container2` can no longer talk to `container3` on the `isolated_nw` network. 372 373 ``` 374 $ docker attach container2 375 376 / # ifconfig 377 eth0 Link encap:Ethernet HWaddr 02:42:AC:11:00:03 378 inet addr:172.17.0.3 Bcast:0.0.0.0 Mask:255.255.0.0 379 inet6 addr: fe80::42:acff:fe11:3/64 Scope:Link 380 UP BROADCAST RUNNING MULTICAST MTU:9001 Metric:1 381 RX packets:8 errors:0 dropped:0 overruns:0 frame:0 382 TX packets:8 errors:0 dropped:0 overruns:0 carrier:0 383 collisions:0 txqueuelen:0 384 RX bytes:648 (648.0 B) TX bytes:648 (648.0 B) 385 386 lo Link encap:Local Loopback 387 inet addr:127.0.0.1 Mask:255.0.0.0 388 inet6 addr: ::1/128 Scope:Host 389 UP LOOPBACK RUNNING MTU:65536 Metric:1 390 RX packets:0 errors:0 dropped:0 overruns:0 frame:0 391 TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 392 collisions:0 txqueuelen:0 393 RX bytes:0 (0.0 B) TX bytes:0 (0.0 B) 394 395 / # ping container3 396 PING container3 (172.20.0.1): 56 data bytes 397 ^C 398 --- container3 ping statistics --- 399 2 packets transmitted, 0 packets received, 100% packet loss 400 ``` 401 402 The `container2` still has full connectivity to the bridge network 403 404 ```bash 405 / # ping container1 406 PING container1 (172.17.0.2): 56 data bytes 407 64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.119 ms 408 64 bytes from 172.17.0.2: seq=1 ttl=64 time=0.174 ms 409 ^C 410 --- container1 ping statistics --- 411 2 packets transmitted, 2 packets received, 0% packet loss 412 round-trip min/avg/max = 0.119/0.146/0.174 ms 413 / # 414 ``` 415 416 ## Remove a network 417 418 When all the containers in a network are stopped or disconnected, you can remove a network. 419 420 ```bash 421 $ docker network disconnect isolated_nw container3 422 ``` 423 424 ```bash 425 docker network inspect isolated_nw 426 [ 427 { 428 "Name": "isolated_nw", 429 "Id": "f836c8deb6282ee614eade9d2f42d590e603d0b1efa0d99bd88b88c503e6ba7a", 430 "Scope": "local", 431 "Driver": "bridge", 432 "IPAM": { 433 "Driver": "default", 434 "Config": [ 435 {} 436 ] 437 }, 438 "Containers": {}, 439 "Options": {} 440 } 441 ] 442 443 $ docker network rm isolated_nw 444 ``` 445 446 List all your networks to verify the `isolated_nw` was removed: 447 448 ``` 449 $ docker network ls 450 NETWORK ID NAME DRIVER 451 72314fa53006 host host 452 f7ab26d71dbd bridge bridge 453 0f32e83e61ac none null 454 ``` 455 456 ## Related information 457 458 * [network create](../../reference/commandline/network_create.md) 459 * [network inspect](../../reference/commandline/network_inspect.md) 460 * [network connect](../../reference/commandline/network_connect.md) 461 * [network disconnect](../../reference/commandline/network_disconnect.md) 462 * [network ls](../../reference/commandline/network_ls.md) 463 * [network rm](../../reference/commandline/network_rm.md)