Merge pull request #2188 from weaveworks/doc-improvements

Minor improvements to docs

docs/ipam.md

@@ -210,11 +210,3 @@ reached the peer that does the `rmpeer`, then we get an inconsistent
 ring.  We could make it safe, up to partitions, by inquiring of every
 live peer what its view of the dead peer is, and making sure we use
 the latest info.)
-
-## Limitations
-
-Nothing is persisted. If one peer restarts it should receive gossip
-from other peers showing what it used to own, and in that case it can
-recover quite well. If, however, there are no peers left alive, or
-this peer cannot establish network communication with those that are,
-then it cannot recover.

site/cni-plugin.md

@@ -29,7 +29,7 @@ Then run:
 To create a network which can span multiple hosts, the Weave peers must be connected to each other, by specifying the other hosts during `weave launch` or via
 [`weave connect`](/site/using-weave/finding-adding-hosts-dynamically.md).
 
-See [Deploying Applications to Weave Net](/site/using-weave/deploying-applications.md#peer-connections) for a discussion on peer connections. 
+See [Using Weave Net](/site/using-weave.md#peer-connections) for a discussion on peer connections. 
 
 As well as launching Weave Net, you have to run an extra command to
 perform some additional configuration of the Weave bridge:

site/faq.md

@@ -69,7 +69,7 @@ For more information about fast datapath see [How Fast Datapath Works](/site/how
 
 To view whether Weave is using fastdp or not, you can run, `weave status connections`
 
-For more information on this command, see [Using Fast Datapath](/using-weave/fastdp.md)
+For more information on this command, see [Using Fast Datapath](/site/using-weave/fastdp.md)
 
 
 **Q: Does encryption work with fastdp?**
@@ -78,7 +78,7 @@ Encryption does not work with fast datapath. If you enable encryption using the
 
 You can however have a mixture of fast datapath connections over trusted links, as well as, encrypted connections over untrusted links.
 
-See [Using Fast Datapath](/using-weave/fastdp.md) for more information
+See [Using Fast Datapath](/site/using-weave/fastdp.md) for more information
 
 **Q: Can I create multiple networks where containers can communicate on one network, but are isolated from containers on other networks?**
 

site/features.md

@@ -3,9 +3,6 @@ title: Feature Overview
 menu_order: 20
 ---
 
-The following is a comprehensive list and overview of all the features available in Weave 
-Net:
-
  * [Virtual Ethernet Switch](#virtual-ethernet-switch)
  * [Fast Data Path](#fast-data-path)
  * [Seamless Docker Integration](#docker)
@@ -42,11 +39,11 @@ tools and applications, developed over decades, can still
 be used to configure, secure, monitor, and troubleshoot 
 a container network. 
 
-Broadcast and Multicast protocols can also be implemented 
+Broadcast and Multicast protocols can also be used
 over Weave Net.
 
 To start using Weave Net, see [Installing Weave Net](/site/installing-weave.md) 
-and [Deploying Applications to Weave Net](/site/using-weave/deploying-applications.md).
+and [Using Weave Net](/site/using-weave.md).
 
 ###<a name="fast-data-path"></a>Fast Datapath
 
@@ -58,15 +55,15 @@ Fast datapath does not support encryption. For full details on configuring
 Weave when you have connections that traverse untrusted networks,
 see [Securing Connections Across Untrusted Networks](/site/using-weave/security-untrusted-networks.md) for more details.
 
-See [Using Fast Datapath](/using-weave/fastdp.md) and
+See [Using Fast Datapath](/site/using-weave/fastdp.md) and
 [How Fast Datapath Works](/site/how-it-works/fastdp-how-it-works.md).
 
 ###<a name="docker"></a>Seamless Docker Integration (Weave Docker API Proxy)
 
 Weave Net includes a [Docker API Proxy](/site/weave-docker-api.md), which can be 
 used to start containers using the Docker [command-line interface](https://docs.docker.com/reference/commandline/cli/) or the [remote API](https://docs.docker.com/reference/api/docker_remote_api/), and attach them to the Weave network before they begin execution.
 
-To use the proxy run:
+To use the proxy, run:
 
     host1$ eval $(weave env)
 
@@ -138,8 +135,8 @@ to communicate with each other but not with the containers
 of other applications.
 
 To isolate applications, Weave Net can make use of the 
-`isolation-through-subnets` technique. This common strategy
- is an example of how with Weave many of your `on metal` 
+_isolation-through-subnets_ technique. This common strategy
+ is an example of how with Weave many "on metal"
  techniques can be used to deploy your applications to 
  containers.
 
@@ -179,7 +176,7 @@ mechanism which you can use in conjunction with or as an
 alternative to any other security technologies you have 
 running alongside Weave. 
 
-Weave Net implements encryption and security using [Daniel J. Bernstein's NaCl library](http://nacl.cr.yp.to/index.html).
+Weave Net implements encryption and security using the Go version of [Daniel J. Bernstein's NaCl library](http://nacl.cr.yp.to/index.html).
 
 For information on how to secure your Docker network connections, see [Securing Connections Across Untrusted Networks](/site/using-weave/security-untrusted-networks.md) and for a more technical discussion on how Weave implements encryption see, [Weave Encryption](/how-it-works/encryption.md) and [How Weave Implements Encryption](/site/how-it-works/encryption-implementation.md).
 

site/how-it-works.md

@@ -27,7 +27,7 @@ is given an IP address and netmask supplied either by the user or
 by Weave Net's IP address allocator.
 
 Weave Net routes packets between containers on different hosts via two
-methods: a [fast data path](/using-weave/fastdp.md) method, which operates
+methods: a [fast data path](/site/using-weave/fastdp.md) method, which operates
 entirely in kernel space, and a fallback `sleeve` method, in which
 packets destined for non-local containers are captured by the kernel
 and processed by the Weave Net router in user space, forwarded over

site/how-it-works/fastdp-how-it-works.md

@@ -24,7 +24,7 @@ Prior to version 1.2, Weave Net used a custom encapsulation format. Fast datapat
 
 **See Also**
 
- * [Deploying Applications to Weave](/site/using-weave/deploying-applications.md)
- * [Using Fast Datapath](/using-weave/fastdp.md)
+ * [Using Weave Net](/site/using-weave.md)
+ * [Using Fast Datapath](/site/using-weave/fastdp.md)
 
 

site/how-it-works/router-encapsulation.md

@@ -4,7 +4,7 @@ menu_order: 10
 ---
 
 When the Weave Net router forwards packets to peers in `sleeve` mode
-(rather than via the [fast data path](/using-weave/fastdp.md)), the
+(rather than via the [fast data path](/site/using-weave/fastdp.md)), the
 encapsulation looks something like this:
 
     +-----------------------------------+

site/installing-weave.md

@@ -12,28 +12,29 @@ Install Weave Net by running the following:
     sudo curl -L git.io/weave -o /usr/local/bin/weave
     sudo chmod a+x /usr/local/bin/weave
 
-If you are on OSX and are using Docker Machine) you need to make sure
+If you are on OSX and are using Docker Machine you need to make sure
 that a VM is running and configured before getting Weave Net. Setting up a VM is shown in [the Docker Machine
 documentation](https://docs.docker.com/installation/mac/#from-your-shell).
 After the VM is configured with Docker Machine, Weave Net can be launched directly from the OSX host.
 
 Weave Net respects the environment variable `DOCKER_HOST`, so that you can run
 and control a Weave Network locally on a remote host. See [Using The Weave Docker API Proxy](/site/weave-docker-api/using-proxy.md).
 
-With Weave Net downloaded onto your VMs or hosts, you are ready to launch a Weave network and deploy apps onto it. See [Deploying Applications to Weave](/site/using-weave/deploying-applications.md).
-
-CoreOS users see [here](https://github.com/fintanr/weave-gs/blob/master/coreos-simple/user-data) for an example of installing Weave using cloud-config.
-
-Amazon ECS users see [here](https://github.com/weaveworks/integrations/blob/master/aws/ecs/README.md)
-for the latest Weave AMIs and [here](http://weave.works/guides/service-discovery-with-weave-aws-ecs.html) to get started with Weave Net on ECS.
-
+With Weave Net downloaded onto your VMs or hosts, you are ready to launch a Weave network and deploy apps onto it. See [Using Weave Net](/site/using-weave.md).
 
 ###Quick Start Screencast
 
 <a href="https://youtu.be/kihQCCT1ykE" alt="Click to watch the screencast" target="_blank">
   <img src="hello-screencast.png" />
 </a>
 
+###Guides for specific platforms
+
+CoreOS users see [here](/guides/networking-docker-containers-with-weave-on-coreos/) for an example of installing Weave using cloud-config.
+
+Amazon ECS users see [here](https://github.com/weaveworks/integrations/blob/master/aws/ecs/README.md)
+for the latest Weave AMIs and [here](http://weave.works/guides/service-discovery-with-weave-aws-ecs.html) to get started with Weave Net on ECS.
+
 **See Also** 
 
  * [Using Weave Net](/site/using-weave.md)

site/introducing-weave.md

@@ -4,7 +4,7 @@ menu_order: 10
 ---
 
 
-Weave Net creates a virtual network that connects Docker containers deployed across multiple hosts and enables their automatic discovery. With Weave Net, portable microservices-based applications consisting of multiple containers can run anywhere: on one host, multiple hosts or even across cloud providers and data centers. Applications use the network just as if the containers were all plugged into the same network switch, without having to configure port mappings, or ambassador links. 
+Weave Net creates a virtual network that connects Docker containers across multiple hosts and enables their automatic discovery. With Weave Net, portable microservices-based applications consisting of multiple containers can run anywhere: on one host, multiple hosts or even across cloud providers and data centers. Applications use the network just as if the containers were all plugged into the same network switch, without having to configure port mappings, ambassadors or links.
 
 Services provided by application containers on the weave network can be exposed to the outside world, regardless of where they are running. Similarly, existing internal systems can be opened to accept connections from application containers irrespective of their location.
 
@@ -36,7 +36,7 @@ Weave Net can forward traffic between nodes, and it works even if the mesh netwo
 
 Weave Net automatically chooses the fastest path between two hosts, offering near native throughput and latency, all without your intervention.  
 
-See [How Fast Datapath Works](/using-weave/fastdp.md) for more information.
+See [How Fast Datapath Works](/site/using-weave/fastdp.md) for more information.
 
 ###Network Operations Friendly
 
@@ -52,9 +52,9 @@ Multicast addressing and routing is fully supported in Weave Net. Data can be se
 
 ###NAT Traversal
 
-With Weave Net, deploy your peer-to-peer file sharing applications and voice over IP and take advantage of built-in NAT traversal. With Weave your app is portable, containerized and with its standardized approach to networking it gives you one less thing to worry about. 
+With Weave Net, deploy your applications - whether peer-to-peer file sharing, voice over IP or anything else - and take advantage of built-in NAT traversal. With Weave your app is portable, containerized and with its standardized approach to networking it gives you one less thing to worry about.
 
-###Run with Anything: Kubernetes, Mesos, Amazon ECS
+###Run with Anything: Kubernetes, Mesos, Amazon ECS, ...
 
 Weave Net is a good choice if you want one tool for everything.  For example: In addition to Docker plugins, you can also use Weave as a Kubernetes plugin.  You can also use Weave with Amazon ECS or with Mesos and Marathon.  
 Refer to our Getting Started and Integration Guides for more information.

site/ipam.md

@@ -175,6 +175,18 @@ the rest (a partition), they can continue to work with the address
 ranges they had before isolation, and can subsequently be re-connected
 to the rest of the network without any conflicts arising.
 
+### <a name="persistence"></a>Data persistence
+
+Key IPAM data is saved to disk, so that it is immediately available
+when the peer restarts:
+
+* The division of the IP allocation range amongst peers
+* Allocation of addresses to containers on the local peer
+
+A [data volume
+container](https://docs.docker.com/engine/userguide/containers/dockervolumes/#creating-and-mounting-a-data-volume-container)
+named `weavedb` is used to store this data.
+
  **See Also**
 
  * [Automatic Allocation Across Multiple Subnets](/site/ipam/allocation-multi-ipam.md)

site/plugin.md

@@ -12,7 +12,7 @@ best of all doesn't require an external cluster store in order to use it.
 To create a network which can span multiple Docker hosts, Weave Net peers must be connected to each other, by specifying the other hosts during `weave launch` or via
 [`weave connect`](/site/using-weave/finding-adding-hosts-dynamically.md).
 
-See [Deploying Applications to Weave Net](/site/using-weave/deploying-applications.md#peer-connections) for a discussion on peer connections. 
+See [Using Weave Net](/site/using-weave.md#peer-connections) for a discussion on peer connections. 
 
 After you've launched Weave Net and peered your hosts,  you can start containers using the following, for example:
 
@@ -54,11 +54,11 @@ then run your containers using the Docker command-line:
 
 ### Restarting the Plugin
 
-The plugin is started with a policy of `--restart=always`, so that it is always there after a restart or reboot. If you remove this container (for example, when using `weave reset`) before removing all endpoints created using `--net=weave`, Docker may hang for a long time when it subsequently tries to re-establish communications to the plugin.
+The plugin, like all Weave Net components, is started with a policy of `--restart=always`, so that it is always there after a restart or reboot. If you remove this container (for example, when using `weave reset`) before removing all endpoints created using `--net=weave`, Docker may hang for a long time when it subsequently tries to re-establish communications to the plugin.
 
 Unfortunately, [Docker 1.9 may also try to communicate with the plugin before it has even started it](https://github.com/docker/libnetwork/issues/813).
 
-If you are using `systemd`, it is advised that you modify the Docker unit to remove the timeout on startup. This gives Docker enough time to abandon its attempts. For example, in the file `/lib/systemd/system/docker.service`, add the following under `[Service]`: 
+If you are using `systemd` with Docker 1.9, it is advised that you modify the Docker unit to remove the timeout on startup. This gives Docker enough time to abandon its attempts. For example, in the file `/lib/systemd/system/docker.service`, add the following under `[Service]`:
 
     TimeoutStartSec=0
 

site/troubleshooting.md

@@ -279,7 +279,9 @@ re-connect.
 
 All the containers started by `weave launch` are configured with the
 Docker restart policy `--restart=always`, so they will come back again
-on reboot.
+on reboot. This can be disabled via:
+
+    weave launch --no-restart
 
 Note that the
 [Weave Net Docker API Proxy](/site/weave-docker-api/set-up-proxy.md)