From f90390974a0cf08ceb131a1aab2574d98ee9c0c1 Mon Sep 17 00:00:00 2001 From: Bryan Boreham Date: Mon, 11 Jan 2016 10:22:28 +0000 Subject: [PATCH 1/3] Add page explaining IP addresses, networks and routes --- site/features.md | 2 +- site/ip-addresses.md | 88 ++++++++++++++++++++++++++++++++++++++++++++ site/ipam.md | 2 +- 3 files changed, 90 insertions(+), 2 deletions(-) create mode 100644 site/ip-addresses.md diff --git a/site/features.md b/site/features.md index a6115196..73691bce 100644 --- a/site/features.md +++ b/site/features.md @@ -115,7 +115,7 @@ Weave detects when a container has exited and releases its automatically allocated addresses so they can be re-used. See the [Automatic IP Address Management](ipam.html) documentation for -further details. +further details. We also have a page on [the basics of IP addressing](ip-addresses.html) Instead of getting weave to allocate IP addresses automatically, it is also possible to specify an address and network explicitly, expressed diff --git a/site/ip-addresses.md b/site/ip-addresses.md new file mode 100644 index 00000000..da5438c6 --- /dev/null +++ b/site/ip-addresses.md @@ -0,0 +1,88 @@ +--- +title: IP Addresses, routes and networks +layout: default +--- + +# IP Addresses, routes and networks + +Weave Net lets you run containers on a private network, and so the IP +addresses those containers use are insulated from the rest of the +Internet, and you don't have to worry about them clashing. Except, if +they actually do clash with some addresses that you'd like the +containers to talk to. + +Some definitions: + +- _IP_ is the Internet Protocol, the fundamental basis of network + communication between billions of connected devices. +- The _IP address_ is (for most purposes) the four numbers separated + by dots, like `192.168.48.12`. Each number is one byte in size, so can + be between 0 and 255. +- Each IP address lives on a _Network_, which is some set of those + addresses that all know how talk to each other. The network address + is some prefix of the IP address, like `192.168.48`. To indicate + which part of the address indicates the network, we append a slash + and then the number of bits in the network prefix, like + `/24`. Another example would be `10.4.2.6/8`, where the network + prefix is the first 8 bits - `10`. Written out in full, the address + of this network is `10.0.0.0/8`. The most common prefix lengths are + 8, 16 and 24, but there is nothing stopping you using a /9 network + or a /26. +- A _route_ is an instruction for how to deal with traffic destined + for somewhere else - it specifies a Network, and a way to talk to + that network. Every device using IP has a table of routes, so for + any destination address it looks up that table, finds the right + route, and sends it in the direction indicated. + +Quick example: this is the route table for a container that I just started: + +```` +# ip route show +default via 172.17.42.1 dev eth0 +10.2.2.0/24 dev ethwe proto kernel scope link src 10.2.2.1 +172.17.0.0/16 dev eth0 proto kernel scope link src 172.17.0.170 +```` + +It has two interfaces: one that Docker gave it called `eth0`, and one +that weave gave it called `ethwe`. They are on networks +`172.17.0.0/16` and `10.2.2.0/24` respectively, and if you want to +talk to any other address on those networks then the routing table +tells it to send directly down that interface. If you want to talk to +anything else not matching those rules, the default rule says to send +it to `172.17.42.1` down the eth0 interface. + +So, suppose this container wants to talk to another container at +address `10.2.2.9`; it will send down the ethwe interface and weave +Net will take care of routing the traffic. To talk an external server +at address `74.125.133.128`, it looks in its routing table, doesn't +find a match, so uses the default rule. + +The default configurations for both weave Net and Docker use [Private +Networks](https://en.wikipedia.org/wiki/Private_network), whose +addresses are never used on the public internet, so that reduces the +chances of overlap. But it could be that you or your hosting provider +are using some of these private addresses in the same range, which would +cause a clash. + +Here's an example that came up recently: on `weave launch`, the +following error message appeared: + +```` +Network 10.32.0.0/12 overlaps with existing route 10.0.0.0/8 on host. +ERROR: Default --ipalloc-range 10.32.0.0/12 overlaps with existing route on host. +You must pick another range and set it on all hosts. +```` + +As the message says, the default that weave Net would like to use is +`10.32.0.0/12` - a 12-bit prefix so all addresses starting with the bit +pattern 000010100010, or in decimal everything from 10.32 through +10.47. But the user's host already has a route for `10.0.0.0/8`, +which overlaps, because the first 8 bits are the same. If we went +ahead and used the default network, then for an address like +`10.32.5.6` the kernel would never be sure whether this meant the +weave Net network of `10.32.0.0/12` or the hosting network of +10.0.0.0/8. + +If you're in this situation, the best option is, as the message says, +to pick a different range. In this example, a different private range +such as `172.30/16` would work. diff --git a/site/ipam.md b/site/ipam.md index 7f19ffc5..30901fbf 100644 --- a/site/ipam.md +++ b/site/ipam.md @@ -109,7 +109,7 @@ The range parameter is written in [CIDR notation](http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) - in this example "/16" means the first 16 bits of the address form the network address and the allocator is to allocate container addresses -that all start 10.2. +that all start 10.2. [More information on IP addresses and routes](ip-addresses.html) Weave shares the IP address range across all peers, dynamically according to their needs. If a group of peers becomes isolated from From a1dff70ba2a2ef90ec9e8bff390d82cef2c4e40f Mon Sep 17 00:00:00 2001 From: Bryan Boreham Date: Mon, 11 Jan 2016 11:55:11 +0000 Subject: [PATCH 2/3] Review feedback --- site/features.md | 3 ++- site/ip-addresses.md | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/site/features.md b/site/features.md index 73691bce..aaa1a43c 100644 --- a/site/features.md +++ b/site/features.md @@ -115,7 +115,8 @@ Weave detects when a container has exited and releases its automatically allocated addresses so they can be re-used. See the [Automatic IP Address Management](ipam.html) documentation for -further details. We also have a page on [the basics of IP addressing](ip-addresses.html) +further details. We also have an explanation of +[the basics of IP addressing](ip-addresses.html) Instead of getting weave to allocate IP addresses automatically, it is also possible to specify an address and network explicitly, expressed diff --git a/site/ip-addresses.md b/site/ip-addresses.md index da5438c6..41ca345b 100644 --- a/site/ip-addresses.md +++ b/site/ip-addresses.md @@ -64,8 +64,8 @@ chances of overlap. But it could be that you or your hosting provider are using some of these private addresses in the same range, which would cause a clash. -Here's an example that came up recently: on `weave launch`, the -following error message appeared: +Here's an example: on `weave launch`, the following error message +can appear: ```` Network 10.32.0.0/12 overlaps with existing route 10.0.0.0/8 on host. From 0d0fc392369cdc196e76a07ad83ca5da87c40028 Mon Sep 17 00:00:00 2001 From: Bryan Boreham Date: Tue, 12 Jan 2016 15:32:18 +0000 Subject: [PATCH 3/3] More review feedback --- site/ip-addresses.md | 47 +++++++++++++++++++++++++++++--------------- site/ipam.md | 3 ++- 2 files changed, 33 insertions(+), 17 deletions(-) diff --git a/site/ip-addresses.md b/site/ip-addresses.md index 41ca345b..791f19f3 100644 --- a/site/ip-addresses.md +++ b/site/ip-addresses.md @@ -11,7 +11,7 @@ Internet, and you don't have to worry about them clashing. Except, if they actually do clash with some addresses that you'd like the containers to talk to. -Some definitions: +### Some definitions - _IP_ is the Internet Protocol, the fundamental basis of network communication between billions of connected devices. @@ -20,21 +20,30 @@ Some definitions: be between 0 and 255. - Each IP address lives on a _Network_, which is some set of those addresses that all know how talk to each other. The network address - is some prefix of the IP address, like `192.168.48`. To indicate - which part of the address indicates the network, we append a slash + is some prefix of the IP address, like `192.168.48`. To show + which part of the address is the network, we append a slash and then the number of bits in the network prefix, like - `/24`. Another example would be `10.4.2.6/8`, where the network - prefix is the first 8 bits - `10`. Written out in full, the address - of this network is `10.0.0.0/8`. The most common prefix lengths are - 8, 16 and 24, but there is nothing stopping you using a /9 network - or a /26. + `/24`. - A _route_ is an instruction for how to deal with traffic destined for somewhere else - it specifies a Network, and a way to talk to that network. Every device using IP has a table of routes, so for any destination address it looks up that table, finds the right route, and sends it in the direction indicated. -Quick example: this is the route table for a container that I just started: +### Examples + +In the IP address `10.4.2.6/8`, the network prefix is the first 8 bits +- `10`. Written out in full, that network is `10.0.0.0/8`. + +The most common prefix lengths are 8, 16 and 24, but there is nothing +stopping you using a /9 network or a /26. E.g. `6.250.3.1/9` is on the +`6.128.0.0/9` network. + +Several websites offer calculators to decode this kind of address; for +example [IP Address Guide](http://www.ipaddressguide.com/cidr). + +Here is an example route table for a container attached to the Weave +network: ```` # ip route show @@ -57,9 +66,11 @@ Net will take care of routing the traffic. To talk an external server at address `74.125.133.128`, it looks in its routing table, doesn't find a match, so uses the default rule. +### Configuring Weave + The default configurations for both weave Net and Docker use [Private Networks](https://en.wikipedia.org/wiki/Private_network), whose -addresses are never used on the public internet, so that reduces the +addresses are never found on the public internet, so that reduces the chances of overlap. But it could be that you or your hosting provider are using some of these private addresses in the same range, which would cause a clash. @@ -75,14 +86,18 @@ You must pick another range and set it on all hosts. As the message says, the default that weave Net would like to use is `10.32.0.0/12` - a 12-bit prefix so all addresses starting with the bit -pattern 000010100010, or in decimal everything from 10.32 through -10.47. But the user's host already has a route for `10.0.0.0/8`, +pattern 000010100010, or in decimal everything from 10.32.0.0 through +10.47.255.255. But the user's host already has a route for `10.0.0.0/8`, which overlaps, because the first 8 bits are the same. If we went ahead and used the default network, then for an address like `10.32.5.6` the kernel would never be sure whether this meant the weave Net network of `10.32.0.0/12` or the hosting network of -10.0.0.0/8. +`10.0.0.0/8`. -If you're in this situation, the best option is, as the message says, -to pick a different range. In this example, a different private range -such as `172.30/16` would work. +If you're sure the addresses you want are not really in use, then +explicitly setting the range with `--ipalloc-range` in the +command-line arguments to `weave launch` on all hosts will force Weave +Net to use that range, even though it overlaps. Otherwise, you can +pick a different range, preferrably another subset of the [Private +Networks](https://en.wikipedia.org/wiki/Private_network). For example +172.30.0.0/16. diff --git a/site/ipam.md b/site/ipam.md index 30901fbf..74288e93 100644 --- a/site/ipam.md +++ b/site/ipam.md @@ -109,7 +109,8 @@ The range parameter is written in [CIDR notation](http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) - in this example "/16" means the first 16 bits of the address form the network address and the allocator is to allocate container addresses -that all start 10.2. [More information on IP addresses and routes](ip-addresses.html) +that all start 10.2. We have [a page with more information on IP +addresses and routes](ip-addresses.html). Weave shares the IP address range across all peers, dynamically according to their needs. If a group of peers becomes isolated from