From f90390974a0cf08ceb131a1aab2574d98ee9c0c1 Mon Sep 17 00:00:00 2001 From: Bryan Boreham Date: Mon, 11 Jan 2016 10:22:28 +0000 Subject: [PATCH] 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