Merge branch '1.4'

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.
+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

site/ip-addresses.md

@@ -0,0 +1,103 @@
+---
+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 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`.
+- 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.
+
+### 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
+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.
+
+### 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 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.
+
+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.
+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.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`.
+
+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.

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.
+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