diff --git a/site/building.md b/site/building.md index 387e67be..6b26960e 100644 --- a/site/building.md +++ b/site/building.md @@ -1,11 +1,11 @@ --- -title: Building Weave +title: Building Weave Net layout: default --- -# Building Weave +# Building Weave Net -You only need to build weave if you want to work on the weave codebase +You only need to build Weave Net if you want to work on the Weave Net codebase (or you just enjoy building software). Apart from the `weave` shell script, weave is delivered as a set of @@ -53,7 +53,7 @@ are cached and should not need to be redone very often. ## Building using Vagrant -If you aren't running Linux, or otherwise don't want to run the docker +If you aren't running Linux, or otherwise don't want to run the Docker daemon outside a VM, you can use [Vagrant](https://www.vagrantup.com/downloads.html) to run a development environment. You'll probably need to install @@ -96,7 +96,7 @@ vm$ cd src/github.com/weaveworks/weave vm$ make ``` -The docker daemon is also running in this VM, so you can then do +The Docker daemon is also running in this VM, so you can then do ```bash vm$ sudo ./weave launch diff --git a/site/encryption/implementation.md b/site/encryption/implementation.md index ceea72ca..89ea6553 100644 --- a/site/encryption/implementation.md +++ b/site/encryption/implementation.md @@ -42,7 +42,7 @@ and the use of SHA256 reduces this back to 256 bits, to form the final ephemeral session key. This late combination with the password eliminates any "Man In The Middle" attacks: sniffing the public key exchange between the two peers and faking their responses will not -grant an attacker knowledge of the password, and therefor, an attacker would +grant an attacker knowledge of the password, and therefore, an attacker would not be able to form valid ephemeral session keys. The same ephemeral session key is used for both TCP and UDP traffic @@ -74,12 +74,12 @@ bits of entropy at startup, and uses that to seed an internal CSPRNG, which is used to generate keys. While Weave Net could have taken the same approach and built a custom CSPRNG to work around the potential `/dev/random` blocking issue, the decision was made to rely -on the [heavily scrutinised](http://eprint.iacr.org/2012/251.pdf) Linux random number +on the [heavily scrutinized](http://eprint.iacr.org/2012/251.pdf) Linux random number generator as [advised here](http://cr.yp.to/highspeed/coolnacl-20120725.pdf) (page 10, 'Centralizing randomness'). ->>**Note:**The aforementioned notwithstanding, if +>**Note:**The aforementioned notwithstanding, if Weave Net's demand on `/dev/urandom` is causing you problems with blocking `/dev/random` reads, please get in touch with us - we'd love to hear about your use case. diff --git a/site/fastdp/fastdp-how-it-works.md b/site/fastdp/fastdp-how-it-works.md index 41c262b5..c01f20c7 100644 --- a/site/fastdp/fastdp-how-it-works.md +++ b/site/fastdp/fastdp-how-it-works.md @@ -17,9 +17,9 @@ Because Weave Net issues instructions directly to the kernel, context switches a ![Weave Net Encapsulation](/site/images/weave-frame-encapsulation-178x300.png) -Prior to version 1.2, Weave Net used a custom encapsulation format. Fast data path uses VXLAN, and like Weave Net's custom encapsulation format, VXLAN is UDP-based, and therefore needs no special configuration with network infrastructure. +Prior to version 1.2, Weave Net used a custom encapsulation format. Fast datapath uses VXLAN, and like Weave Net's custom encapsulation format, VXLAN is UDP-based, and therefore needs no special configuration with network infrastructure. ->>**Note:** The required open vSwitch datapath (ODP) and VXLAN features are present in Linux kernel versions 3.12 and greater. If your kernel was built without the necessary modules Weave Net will fall back to the "user mode" packet path. +>**Note:** The required open vSwitch datapath (ODP) and VXLAN features are present in Linux kernel versions 3.12 and greater. If your kernel was built without the necessary modules Weave Net will fall back to the "user mode" packet path. **See Also** diff --git a/site/fastdp/using-fastdp.md b/site/fastdp/using-fastdp.md index 28eeb300..b2a4e336 100644 --- a/site/fastdp/using-fastdp.md +++ b/site/fastdp/using-fastdp.md @@ -8,7 +8,7 @@ The most important thing to know about fast datapath is that you don't need to c When Weave Net can't use the fast data path between two hosts, it falls back to the slower packet forwarding approach. Selecting the fastest forwarding approach is automatic, and is determined on a connection-by-connection basis. For example, a Weave network spanning two data centers might use fast data path within the data centers, but not for the more constrained network link between them. -See [How Fastdp Works](/site/fastdp/fastdp-how-it-works.md) for a more indepth discussion of this feature. +See [How Fastdp Works](/site/fastdp/fastdp-how-it-works.md) for a more in-depth discussion of this feature. ###Disabling Fast Datapath diff --git a/site/ip-addresses/configuring-weave.md b/site/ip-addresses/configuring-weave.md index 24f26150..a7d023c4 100644 --- a/site/ip-addresses/configuring-weave.md +++ b/site/ip-addresses/configuring-weave.md @@ -5,7 +5,7 @@ layout: default 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, and subsequently reduces the +addresses are never found on the public Internet, and subsequently reduces the chance of IP overlap. However, it could be that you or your hosting provider are using some of these private addresses in the same range, which will cause a clash. @@ -13,9 +13,11 @@ cause a clash. If after `weave launch`, the following error message appears: +~~~bash 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 indicates, the default range that Weave Net would like to use is `10.32.0.0/12` - a 12-bit prefix, where all addresses start with the bit diff --git a/site/ip-addresses/ip-addresses.md b/site/ip-addresses/ip-addresses.md index 8b9a9c07..af53d86b 100644 --- a/site/ip-addresses/ip-addresses.md +++ b/site/ip-addresses/ip-addresses.md @@ -42,11 +42,12 @@ Several websites offer calculators to decode this kind of address, see: [IP Addr The following is an example route table for a container that is attached to a Weave network: +~~~bash # 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 diff --git a/site/ipam/overview-init-ipam.md b/site/ipam/overview-init-ipam.md index 4357c6fa..d8feb6a0 100644 --- a/site/ipam/overview-init-ipam.md +++ b/site/ipam/overview-init-ipam.md @@ -22,7 +22,7 @@ The following automatic IP address management topics are discussed: ### Initializing Peers on a Weave Network -There are two options for initialising IPAM - with a statically +There are two options for initializing IPAM - with a statically configured seed or automatically via one-off consensus. The two options have different tradeoffs, so pick the one that suits your deployment best. @@ -44,12 +44,14 @@ outset even under conditions of partition - no consensus is required. #### Via One-off Consensus -Alternatively, you can let weave determine the seed automatically via -a consensus algorithm; since you don't need to provide it with a list -of peer names anymore you can also let weave generate those randomly -for you too. However, in order for weave to form a single consensus +Alternatively, you can let Weave Net determine the seed automatically via +a consensus algorithm. Since you don't need to provide it with a list +of peer names anymore, you can let Weave Net generate those randomly +for you as well. + +However, in order for Weave Net to form a single consensus reliably you must now instead tell each peer how many peers there are -in total either by listing them as target peers or via the +in total either by listing them as target peers or using the `--init-peer-count` parameter. Just once, when the first automatic IP address allocation is requested @@ -65,20 +67,20 @@ To illustrate, suppose you have three hosts, accessible to each other as `$HOST1`, `$HOST2` and `$HOST3`. You can start Weave Net on those three hosts using these three commands: - host1$ weave launch $HOST2 $HOST3 - - host2$ weave launch $HOST1 $HOST3 - - host3$ weave launch $HOST1 $HOST2 +~~~bash + host1$ weave launch $HOST2 $HOST3 + host2$ weave launch $HOST1 $HOST3 + host3$ weave launch $HOST1 $HOST2 +~~~ Or, if it is not convenient to name all the other hosts at launch time, you can pass the number of peers like this: +~~~bash host1$ weave launch --init-peer-count 3 - host2$ weave launch --init-peer-count 3 $HOST3 - host3$ weave launch --init-peer-count 3 $HOST2 +~~~ The consensus mechanism used to determine a majority, transitions through three states: 'deferred', 'waiting' and 'achieved': @@ -95,7 +97,9 @@ Finally, some (but never all) peers can be launched as consensus observers rather than participants by specifying the `--observer` option: +~~~bash host4$ weave launch --observer $HOST3 +~~~ You do not need to specify an initial peer count to such peers. This can be useful to add ephemeral peers to an existing fixed cluster (for @@ -133,6 +137,7 @@ independent set again. To illustrate this last point, the following sequence of operations is safe with respect to Weave Net's startup quorum: +~~~bash host1$ weave launch ...time passes... host2$ weave launch $HOST1 @@ -141,6 +146,7 @@ is safe with respect to Weave Net's startup quorum: ...time passes... ...host1 is rebooted... host1$ weave launch $HOST2 $HOST3 +~~~ ### Forcing Consensus diff --git a/site/ipam/stop-remove-peers-ipam.md b/site/ipam/stop-remove-peers-ipam.md index 0cdc6fce..1fc335a9 100644 --- a/site/ipam/stop-remove-peers-ipam.md +++ b/site/ipam/stop-remove-peers-ipam.md @@ -26,8 +26,10 @@ Assume you had started the three peers in the [overview example](/site/ipam/overview-init-ipam.md), and then host3 caught fire, you can go to one of the other hosts and run: +~~~bash host1$ weave rmpeer host3 524288 IPs taken over from host3 +~~~ Weave Net takes all the IP address ranges owned by host3 and transfers them to be owned by host1. The name "host3" is resolved via the diff --git a/site/ipam/troubleshooting-ipam.md b/site/ipam/troubleshooting-ipam.md index f35f65b0..5b0c0d6d 100644 --- a/site/ipam/troubleshooting-ipam.md +++ b/site/ipam/troubleshooting-ipam.md @@ -6,20 +6,18 @@ layout: default The command +~~~bash weave status +~~~ reports on the current status of the weave router and IP allocator: -```` -... - +~~~bash Service: ipam Status: awaiting consensus (quorum: 2, known: 0) Range: 10.32.0.0-10.47.255.255 DefaultSubnet: 10.32.0.0/12 - -... -```` +~~~ The first section covers the router; see the [troubleshooting guide](/site/troubleshooting.md#weave-status) for full details. diff --git a/site/plugin/cni-plugin-how-to.md b/site/plugin/cni-plugin-how-to.md index 8384358f..f5fa78de 100644 --- a/site/plugin/cni-plugin-how-to.md +++ b/site/plugin/cni-plugin-how-to.md @@ -13,14 +13,19 @@ manager built by Google. The Weave Net CNI plugin is installed when you run `weave setup`, if your machine has the directories normally used to host CNI plugins. + To create those directories, run (as root): +~~~bash mkdir -p /opt/cni/bin mkdir -p /etc/cni/net.d +~~~ Then run: +~~~bash weave setup +~~~ ###Launching Weave Net @@ -32,8 +37,10 @@ See [Deploying Applications to Weave Net](/site/using-weave/deploying-applicatio As well as launching Weave Net, you have to run an extra command to perform some additional configuration of the Weave bridge: +~~~bash weave launch weave expose +~~~ ###Configuring Kubernetes to use the CNI Plugin @@ -41,14 +48,16 @@ After you've launched Weave and peered your hosts, you can configure Kubernetes to use Weave, by adding the following options to the `kubelet` command: +~~~bash --network-plugin=cni --network-plugin-dir=/etc/cni/net.d +~~~ See the [`kubelet` documentation](http://kubernetes.io/v1.1/docs/admin/kubelet.html) for more details. Now, whenever Kubernetes starts a pod, it will be attached to the Weave network. -###The CNI network configuration file +###Using the CNI network configuration file All CNI plugins are configured by a JSON file in the directory `/etc/cni/net.d/`. `weave setup` installs a minimal configuration @@ -57,13 +66,13 @@ file named `10-weave.conf`, which you can alter to suit your needs. See the [CNI Spec]](https://github.com/appc/cni/blob/master/SPEC.md#network-configuration) for details on the format and contents of this file. -By default, the Weave CNI plugin will add a default route out via the Weave bridge, so your containers can access resources on the internet. If you do not want this, add a section to the config file specifying no routes: +By default, the Weave CNI plugin adds a default route out via the Weave bridge, so your containers can access resources on the internet. If you do not want this, add a section to the config file that specifies no routes: -``` +~~~bash "ipam": { "routes": [ ] } -``` +~~~ The following other fields in the spec are supported: @@ -73,5 +82,5 @@ The following other fields in the spec are supported: ###Caveats -- The Weave router container must be running for CNI to allocate addresses +- The Weave Net router container must be running for CNI to allocate addresses - The CNI plugin does not add entries to Weave DNS. diff --git a/site/plugin/plug-in-command-line.md b/site/plugin/plug-in-command-line.md index f690d8cf..ced2e81a 100644 --- a/site/plugin/plug-in-command-line.md +++ b/site/plugin/plug-in-command-line.md @@ -8,8 +8,10 @@ layout: default If you need to give additional arguments to the plugin independently, don't use `weave launch`, but instead run: +~~~bash $ weave launch-router [other peers] $ weave launch-plugin [plugin arguments] +~~~ The plugin command-line arguments are: @@ -25,7 +27,7 @@ To turn this off, e.g. you want to configure your own multicast route, add the `--no-multicast-route` flag to `weave launch-plugin`. ->>Note: When using the Docker Plugin, there is no need to run eval $(weave env) to enable the Proxy. Because Weave is running as a plugin within Docker, the Weave Docker API Proxy, at present, cannot detect between networks. +>Note: When using the Docker Plugin, there is no need to run eval $(weave env) to enable the Proxy. Because Weave is running as a plugin within Docker, the Weave Docker API Proxy, at present, cannot detect between networks. **See Also** diff --git a/site/plugin/plugin-how-it-works.md b/site/plugin/plugin-how-it-works.md index 27a76d41..30cb4445 100644 --- a/site/plugin/plugin-how-it-works.md +++ b/site/plugin/plugin-how-it-works.md @@ -24,7 +24,7 @@ There's no specific documentation from Docker on using a cluster store, but the first part of [Getting Started with Docker Multi-host Networking](https://github.com/docker/docker/blob/master/docs/userguide/networking/get-started-overlay.md) is a good place to start. ->>**Note:** In the case of multiple networks using the `weave` driver, all containers are on the same virtual network but Docker allocates their addresses on different subnets so they cannot talk to each other directly. +>**Note:** In the case of multiple networks using the `weave` driver, all containers are on the same virtual network but Docker allocates their addresses on different subnets so they cannot talk to each other directly. **See Also** diff --git a/site/plugin/weave-plugin-how-to.md b/site/plugin/weave-plugin-how-to.md index d1ee9521..7c374b4c 100644 --- a/site/plugin/weave-plugin-how-to.md +++ b/site/plugin/weave-plugin-how-to.md @@ -16,20 +16,23 @@ See [Deploying Applications to Weave Net](/site/using-weave/deploying-applicatio After you've launched Weave Net and peered your hosts, you can start containers using the following, for example: +~~~bash $ docker run --net=weave -ti ubuntu +~~~ on any of the hosts, and they can all communicate with each other. ->>**Warning!** It is inadvisable to attach containers to the Weave network using the Weave Docker Networking Plugin and Weave Docker API Proxy simultaneously. Such containers will end up with two Weave network interfaces and two IP addresses, which is rarely desirable. To ensure that the proxy is not being used, do not run eval $(weave env), or docker $(weave config). +>**Warning!** It is inadvisable to attach containers to the Weave network using the Weave Docker Networking Plugin and Weave Docker API Proxy simultaneously. Such containers will end up with two Weave network interfaces and two IP addresses, which is rarely desirable. To ensure that the proxy is not being used, do not run eval $(weave env), or docker $(weave config). In order to use Weave Net's [Service Discovery](/site/weavedns/overview-using-weavedns.md) you must pass the additional arguments `--dns` and `-dns-search`, for which a helper is provided in the Weave script: +~~~bash $ docker run --net=weave -h foo.weave.local $(weave dns-args) -tdi ubuntu $ docker run --net=weave -h bar.weave.local $(weave dns-args) -ti ubuntu # ping foo - +~~~ ###Launching Weave Net and Running Containers Using the Plugin @@ -63,7 +66,7 @@ PING 10.32.0.2 (10.32.0.2) 56(84) bytes of data. 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. -Unfortunately, [Docker 1.9 may also try to commmuncate with the plugin before it has even started it](https://github.com/docker/libnetwork/issues/813). +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]`: diff --git a/site/router-topology/network-topology.md b/site/router-topology/network-topology.md index d836ecca..59ac59ee 100644 --- a/site/router-topology/network-topology.md +++ b/site/router-topology/network-topology.md @@ -1,5 +1,5 @@ --- -title: How Weave Net Inteprets Network Topology +title: How Weave Net Interprets Network Topology layout: default --- @@ -20,7 +20,7 @@ entire topology. Communication between peers occurs over TCP links using: a) a spanning-tree based broadcast mechanism, and b) a -neighour gossip mechanism. +neighbor gossip mechanism. Topology messages are sent by a peer in the following instances: @@ -34,7 +34,7 @@ Topology messages are sent by a peer in the following instances: - when a connection has been torn down; an update containing just information about the local peer is broadcast, - periodically, on a timer, the entire topology is "gossiped" to a - subset of neighbours, based on a topology-sensitive random + subset of neighbors, based on a topology-sensitive random distribution. This is done in case some of the aforementioned broadcasts do not reach all peers, due to rapid changes in the topology causing broadcast routing tables to become outdated. @@ -130,7 +130,7 @@ knowledge of that second peer. ####What Happens When The Topology is Out of Date? The propagation of topology changes to all peers is not instantaneous. -Therefor, it is very possible for a node elsewhere in the network to have an +Therefore, it is very possible for a node elsewhere in the network to have an out-of-date view. If the destination peer for a packet is still reachable, then diff --git a/site/systemd.md b/site/systemd.md index efc60df0..d5a471cc 100644 --- a/site/systemd.md +++ b/site/systemd.md @@ -5,13 +5,11 @@ layout: default Having installed `weave` as per [Installing Weave](/site/installing-weave.md), you might find it convenient to configure the -init daemon to start Weave on boot. Most recent Linux distribution releases are -shipping with [systemd](http://www.freedesktop.org/wiki/Software/systemd/). The information below should provide you with some -initial guidance on getting a Weave service configured on a systemd-based OS. +init daemon to start Weave on boot. Most recent Linux distribution releases ship with [systemd](http://www.freedesktop.org/wiki/Software/systemd/). The information below provides you with some initial guidance on getting a Weave Net service configured on a systemd-based OS. -## Weave Service Unit and Configuration +## Weave Net Service Unit and Configuration -A regular service unit definition for Weave is shown below. This file is +A regular service unit definition for Weave Net is shown below. This file is normally placed in `/etc/systemd/system/weave.service`. [Unit] @@ -35,24 +33,24 @@ create the `/etc/sysconfig/weave` environment file using the following format: You can also use the [`weave connect`](/site/using-weave/finding-adding-hosts-dynamically.md) command to add participating hosts dynamically. -Additionally, if you want to enable [encryption](/site/using-weave/security-untrusted-networks.md) you can specify a -password with e.g. `WEAVE_PASSWORD="wfvAwt7sj"` in the `/etc/sysconfig/weave` environment file, and it will get picked up by -Weave on launch. Recommendations for choosing a suitably strong password can be found [here](/site/using-weave/security-untrusted-networks.md). +Additionally, if you want to enable [encryption](/site/using-weave/security-untrusted-networks.md) specify a +password using `WEAVE_PASSWORD="wfvAwt7sj"` in the `/etc/sysconfig/weave` environment file, and it will get picked up by +Weave Net on launch. Recommendations for choosing a suitably strong password can be found [here](/site/using-weave/security-untrusted-networks.md). -You can now launch Weave using +You can now launch Weave Net using sudo systemctl start weave -To ensure Weave launches after reboot, run: +To ensure Weave Net launches after reboot, run: sudo systemctl enable weave For more information on systemd, please refer to the documentation supplied -by your distribution of Linux. +with your distribution of Linux. ## SELinux Tweaks -If your OS has SELinux enabled and you want to run Weave as a systemd unit, +If your OS has SELinux enabled and you want to run Weave Net as a systemd unit, then follow the instructions below. These instructions apply to CentOS and RHEL as of 7.0. On Fedora 21, there is no need to do this. diff --git a/site/troubleshooting.md b/site/troubleshooting.md index a84a1d6c..3686a363 100644 --- a/site/troubleshooting.md +++ b/site/troubleshooting.md @@ -19,7 +19,9 @@ layout: default Check the version of Weave Net you are running using: - weave version +~~~bash +weave version +~~~ If it is not the latest version, as shown in the list of [releases](https://github.com/weaveworks/weave/releases), then it is @@ -28,7 +30,9 @@ recommended you upgrade using the To check the Weave Net container logs: - docker logs weave +~~~bash +docker logs weave +~~~ A reasonable amount of information, and all errors, get logged there. @@ -45,7 +49,7 @@ capture and analysis tools, such as tcpdump and wireshark, to the A status summary can be obtained using `weave status`: -```` +~~~bash $ weave status Version: 1.1.0 @@ -76,7 +80,7 @@ $ weave status Service: plugin DriverName: weave -```` +~~~ The terms used here are explained further at [How Weave Net Works](/site/router-topology/overview.md). @@ -93,7 +97,7 @@ can be overridden by using the `--nickname` argument at `weave launch`. * **Encryption** - indicates whether -[encryption](/site/encryption/crypto-overview) is in use for communication +[encryption](/site/encryption/crypto-overview.md) is in use for communication between peers. * **PeerDiscovery** - indicates whether @@ -126,17 +130,16 @@ in both directions. Weave Net routers check this regularly with heartbeats. Failed connections are automatically retried, with an exponential back-off. -Detailed information on the local Weave Net router's connections can be -obtained using `weave status connections`: +To view detailed information on the local Weave Net router's type `weave status connections`: -```` +~~~bash $ weave status connections <- 192.168.48.12:33866 established unencrypted fastdp 7e:21:4a:70:2f:45(host2) <- 192.168.48.13:60773 pending encrypted fastdp 7e:ae:cd:d5:23:8d(host3) -> 192.168.48.14:6783 retrying dial tcp4 192.168.48.14:6783: no route to host -> 192.168.48.15:6783 failed dial tcp4 192.168.48.15:6783: no route to host, retry: 2015-08-06 18:55:38.246910357 +0000 UTC -> 192.168.48.16:6783 connecting -```` +~~~ The columns are as follows: @@ -160,7 +163,7 @@ The columns are as follows: Detailed information on peers can be obtained with `weave status peers`: -```` +~~~bash $ weave status peers ce:31:e0:06:45:1a(host1) <- 192.168.48.12:39634 ea:2d:b2:e6:e4:f5(host2) established @@ -171,7 +174,7 @@ ea:2d:b2:e6:e4:f5(host2) ee:38:33:a7:d9:71(host3) -> 192.168.48.12:6783 ea:2d:b2:e6:e4:f5(host2) established -> 192.168.48.11:6783 ce:31:e0:06:45:1a(host1) established -```` +~~~ This lists all peers known to this router, including itself. Each peer is shown with its name and nickname, then each line thereafter @@ -180,12 +183,12 @@ address and port number of the connection. In the above example, `host3` has connected to `host1` at `192.168.48.11:6783`; `host1` sees the `host3` end of the same connection as `192.168.48.13:49619`. -### List DNS Entries +### Listing DNS Entries Detailed information on DNS registrations can be obtained with `weave status dns`: -```` +~~~bash $ weave status dns one 10.32.0.1 eebd81120ee4 4a:0f:f6:ec:1c:93 one 10.43.255.255 4fcec78d2a9b 66:c4:47:c6:65:bf @@ -196,7 +199,7 @@ three 10.40.0.2 8a9c2e2ef00f ba:98:d0:37:4f:1c two 10.32.0.2 83689b8f34e0 4a:0f:f6:ec:1c:93 two 10.44.0.0 7edc306cb668 66:c4:47:c6:65:bf two 10.40.0.1 68a5e9c2641b ba:98:d0:37:4f:1c -```` +~~~ The columns are as follows: @@ -205,9 +208,11 @@ The columns are as follows: * Registering entity identifier (typically a container ID) * Name of peer from which the registration originates -### JSON Report +### Producing a JSON Report - $ weave report +~~~bash +$ weave report +~~~ Produces a comprehensive dump of the internal state of the router, IPAM and DNS services in JSON format, including all the information @@ -215,27 +220,35 @@ available from the `weave status` commands. You can also supply a Golang text template to `weave report` in a similar fashion to `docker inspect`: - $ weave report -f {% raw %}'{{.DNS.Domain}}'{% endraw %} - weave.local. +~~~bash +$ weave report -f {% raw %}'{{.DNS.Domain}}'{% endraw %} weave.local. +~~~ Weave Net adds a template function, `json`, which can be applied to get results in JSON format. +~~~bash $ weave report -f {% raw %}'{{json .DNS}}'{% endraw %} {% raw %}{"Domain":"weave.local.","Upstream":["8.8.8.8","8.8.4.4"],"Address":"172.17.0.1:53","TTL":1,"Entries":null}{% endraw %} +~~~ -### List Attached Containers +### Listing Attached Containers + +~~~bash +weave ps +~~~ - weave ps Produces a list of all containers running on this host that are connected to the Weave network, like this: +~~~bash weave:expose 7a:c4:8b:a1:e6:ad 10.2.5.2/24 b07565b06c53 ae:e3:07:9c:8c:d4 5245643870f1 ce:15:34:a9:b5:6d 10.2.5.1/24 e32a7d37a93a 7a:61:a2:49:4b:91 10.2.8.3/24 caa1d4ee2570 ba:8c:b9:dc:e1:c9 10.2.1.1/24 10.2.2.1/24 +~~~ On each line are the container ID, its MAC address, then the list of IP address/routing prefix length ([CIDR @@ -246,9 +259,11 @@ displays the Weave bridge MAC and any IP addresses added to it via the You can also supply a list of container IDs/names to `weave ps`, like this: +~~~bash $ weave ps able baker able ce:15:34:a9:b5:6d 10.2.5.1/24 baker 7a:61:a2:49:4b:91 10.2.8.3/24 +~~~ ## Stopping Weave Net @@ -256,11 +271,15 @@ To stop Weave Net, if you have configured your environment to use the Weave Docker API Proxy, e.g. by running `eval $(weave env)` in your shell, you must first restore the environment using: +~~~bash eval $(weave env --restore) +~~~ Then run: +~~~bash weave stop +~~~ Note that this leaves the local application container network intact. Containers on the local host can continue to communicate, whereas @@ -270,7 +289,9 @@ export/import, is disrupted but resumes once Weave is relaunched. To stop Weave Net and to completely remove all traces of the Weave network on the local host, run: +~~~bash weave reset +~~~ Any running application containers permanently lose connectivity with the Weave network and will have to be restarted in order to @@ -278,11 +299,11 @@ re-connect. ## Reboots -The router and proxy containers do not have Docker restart policies -set, because the process of getting everything re-started and -re-connected via restart policies is not entirely reliable. Until that -changes, we recommend you create appropriate startup scripts to launch -Weave and run application containers from +because the process of getting everything re-started and +re-connected via restart policies is not entirely reliable, the router and +proxy containers do not have Docker restart policies +set. Until that changes, we recommend that you create appropriate startup scripts to launch +Weave Net and run application containers from [your favourite process manager](/site/systemd.md). If you are shutting down or restarting a host deliberately, run `weave @@ -298,9 +319,11 @@ Snapshot releases are published at times to provide previews of new features, assist in the validation of bug fixes, etc. One can install the latest snapshot release using: +~~~bash sudo curl -L git.io/weave-snapshot -o /usr/local/bin/weave sudo chmod a+x /usr/local/bin/weave weave setup +~~~ Snapshot releases report the script version as "(unreleased version)", and the container image versions as git hashes. diff --git a/site/using-weave/deploying-applications.md b/site/using-weave/deploying-applications.md index 8beda3a1..94ba683c 100644 --- a/site/using-weave/deploying-applications.md +++ b/site/using-weave/deploying-applications.md @@ -27,11 +27,12 @@ Where, * The second line configures the Weave Net environment, so that containers launched via the Docker command line are automatically attached to the Weave network, and, * The third line runs the application container using [Docker commands](https://docs.Docker.com/engine/reference/commandline/daemon/). ->>**Note:** If the first command results in an error like +>**Note:** If the first command results in an error like `http:///var/run/Docker.sock/v1.19/containers/create: dial unix /var/run/Docker.sock: permission denied. Are you trying to connect to a TLS-enabled daemon without TLS?` then you likely need to be 'root' in order to connect to the Docker daemon. If so, run the above and all subsequent commands in a *single* root shell (e.g. one created with `sudo -s`). Do *not* prefix individual commands with `sudo`, since some commands modify environment entries and hence they all need to be executed from the same shell. + ->>**Important!** if you are running the Weave Docker Network Plugin do not run `eval $(weave env)`. See [Using the Weave Net Docker Network Plugin](/site/pluing/weave-plugin-how-to.md) for more information. +>**Important!** if you are running the Weave Docker Network Plugin do not run `eval $(weave env)`. See [Using the Weave Net Docker Network Plugin](/site/pluing/weave-plugin-how-to.md) for more information. Weave Net must be launched once per host. The relevant container images will be pulled down from Docker Hub on demand during `weave launch`. @@ -52,7 +53,7 @@ As noted above, the same steps are repeated for `$HOST2`. The only difference, b You can also peer with other hosts by specifying the IP address, and a `:port` by which `$HOST2` can reach `$HOST1`. ->>**Note:** If there is a firewall between `$HOST1` and `$HOST2`, you must permit traffic to flow through TCP 6783 and UDP 6783/6798, which are Weave’s control nd data ports. +>**Note:** If there is a firewall between `$HOST1` and `$HOST2`, you must permit traffic to flow through TCP 6783 and UDP 6783/6798, which are Weave’s control and data ports. There are a number of different ways that you can specify peers on a Weave network. You can launch Weave Net on `$HOST1` and then peer with `$HOST2`, or you can launch on `$HOST2` and peer with `$HOST1` or you can tell both hosts about each other at launch. The order in which peers are specified is not important. Weave Net automatically (re)connects to peers when they become available. @@ -61,6 +62,7 @@ There are a number of different ways that you can specify peers on a Weave netwo To specify multiple peers, supply a list of addresses to which you want to connect, all separated by spaces. For example: + ~~~bash `host2$:weave launch` ~~~ @@ -74,19 +76,24 @@ With two containers running on separate hosts, test that both containers are abl From the container started on `$HOST1`... + +~~~bash root@a1:/# ping -c 1 -q a2 PING a2.weave.local (10.40.0.2) 56(84) bytes of data. --- a2.weave.local ping statistics --- 1 packets transmitted, 1 received, 0% packet loss, time 0ms rtt min/avg/max/mdev = 0.341/0.341/0.341/0.000 ms +~~~ Similarly, in the container started on `$HOST2`... +~~~bash root@a2:/# ping -c 1 -q a1 PING a1.weave.local (10.32.0.2) 56(84) bytes of data. --- a1.weave.local ping statistics --- 1 packets transmitted, 1 received, 0% packet loss, time 0ms rtt min/avg/max/mdev = 0.366/0.366/0.366/0.000 ms +~~~ ###Starting the Netcat Service diff --git a/site/using-weave/dynamically-attach-containers.md b/site/using-weave/dynamically-attach-containers.md index 44280789..dcc29368 100644 --- a/site/using-weave/dynamically-attach-containers.md +++ b/site/using-weave/dynamically-attach-containers.md @@ -8,9 +8,11 @@ When containers may not know the network to which they will be attached, Weave N To illustrate... +~~~bash host1$ C=$(docker run -e WEAVE_CIDR=none -dti ubuntu) host1$ weave attach $C 10.2.1.3 +~~~ where, @@ -24,31 +26,39 @@ where, A container can be detached from a subnet, by using the `weave detach` command: +~~~bash host1$ weave detach $C 10.2.1.3 +~~~ You can also detach a container from one network and then attach it to a different one: +~~~bash host1$ weave detach net:default $C 10.2.1.3 host1$ weave attach net:10.2.2.0/24 $C 10.2.2.3 +~~~ or, attach a container to multiple application networks, effectively sharing the same container between applications: +~~~bash host1$ weave attach net:default 10.2.1.3 host1$ weave attach net:10.2.2.0/24 10.2.2.3 +~~~ Finally, multiple addresses can be attached or detached using a single command: +~~~bash host1$ weave attach net:default net:10.2.2.0/24 net:10.2.3.0/24 $C 10.2.1.3 10.2.2.3 10.2.3.1 host1$ weave detach net:default net:10.2.2.0/24 net:10.2.3.0/24 $C 10.2.1.3 10.2.2.3 10.2.3.1 +~~~ ->>**Important!** Any addresses that were dynamically attached will not be re-attached if the container restarts. +>**Important!** Any addresses that were dynamically attached will not be re-attached if the container restarts. **See Also** diff --git a/site/using-weave/finding-adding-hosts-dynamically.md b/site/using-weave/finding-adding-hosts-dynamically.md index 823c6681..6d9646d3 100644 --- a/site/using-weave/finding-adding-hosts-dynamically.md +++ b/site/using-weave/finding-adding-hosts-dynamically.md @@ -20,7 +20,9 @@ To accomplish this, launch Weave Net onto the new host without supplying any additional addresses. And then, from one of the existing hosts run: +~~~bash host# weave connect $NEW_HOST +~~~ Other hosts on the Weave network will automatically attempt to establish connections to the new host as well. @@ -29,17 +31,21 @@ Alternatively, you can also instruct a peer to forget a particular host specified to it via `weave launch` or `weave connect` by running: +~~~bash host# weave forget $DECOMMISSIONED_HOST +~~~ This prevents the peer from trying to reconnect to that host -once connectivity to it is lost, and therfore can be used +once connectivity to it is lost, and therefore can be used to administratively remove any decommissioned peers from the network. Hosts may also be bulk-replaced. All existing hosts will be forgotten, and the new hosts will be added: +~~~bash host# weave connect --replace $NEW_HOST1 $NEW_HOST2 +~~~ For complete control over the peer topology, automatic discovery can be disabled using the `--no-discovery` @@ -50,9 +56,11 @@ addresses specified at launch time and with `weave connect`. A list of all hosts that a peer has been asked to connect to with `weave launch` and `weave connect` -can be obtained with +can be obtained using: +~~~bash host# weave status targets +~~~ **See Also** diff --git a/site/using-weave/host-network-integration.md b/site/using-weave/host-network-integration.md index bb397cd1..01c0e0fc 100644 --- a/site/using-weave/host-network-integration.md +++ b/site/using-weave/host-network-integration.md @@ -9,36 +9,44 @@ For example, returning to the [netcat example](/site/using-weave/deploying-appli On `$HOST2` run: +~~~bash host2$ weave expose 10.2.1.132 +~~~ This command grants the host access to all of the application containers in the default subnet. An IP address is allocated by Weave Net especially for that purpose, and is returned after running `weave expose`. Now you are able to ping the host: +~~~bash host2$ ping 10.2.1.132 +~~~ And you can also ping the `a1` netcat application container residing on `$HOST1`: +~~~bash host2$ ping $(weave dns-lookup a1) - +~~~ ###Exposing Multiple Subnets Multiple subnet addresses can be exposed or hidden using a single command: +~~~bash host2$ weave expose net:default net:10.2.2.0/24 10.2.1.132 10.2.2.130 host2$ weave hide net:default net:10.2.2.0/24 10.2.1.132 10.2.2.130 - +~~~ ###Adding Exposed Addresses to weavedns Exposed addresses can also be added to `weavedns` by supplying fully qualified domain names: +~~~bash host2$ weave expose -h exposed.weave.local 10.2.1.132 +~~~ **See Also** diff --git a/site/using-weave/isolating-applications.md b/site/using-weave/isolating-applications.md index 351ffabb..d594e46a 100644 --- a/site/using-weave/isolating-applications.md +++ b/site/using-weave/isolating-applications.md @@ -66,9 +66,9 @@ Where, *`net:default` is used to request the allocation of an address from the default subnet in addition to one from an explicitly specified range. ->>Note: By default Docker permits communication between containers on the same host, via their Docker-assigned IP addresses. For complete isolation between application containers, that feature _must_ to be disabled by [setting `--icc=false`](https://docs.Docker.com/engine/userguide/networking/default_network/container-communication/#communication-between-containers) in the Docker daemon configuration. +>Note: By default Docker permits communication between containers on the same host, via their Docker-assigned IP addresses. For complete isolation between application containers, that feature _must_ to be disabled by [setting `--icc=false`](https://docs.Docker.com/engine/userguide/networking/default_network/container-communication/#communication-between-containers) in the Docker daemon configuration. ->>**Important:!** Containers must not be allowed to capture and inject raw network packets. This can be prevented by starting the containers with the `--cap-drop net_raw` option. +>**Important:!** Containers must not be allowed to capture and inject raw network packets. This can be prevented by starting the containers with the `--cap-drop net_raw` option. **See Also** diff --git a/site/using-weave/manual-ip-address.md b/site/using-weave/manual-ip-address.md index 43cf746c..470b93a1 100644 --- a/site/using-weave/manual-ip-address.md +++ b/site/using-weave/manual-ip-address.md @@ -5,8 +5,10 @@ layout: default Containers are automatically allocated an IP address that is unique across the Weave network. You can see which address was allocated by running, [`weave ps`](/site/troubleshooting.md#weave-status): +~~~bash host1$ weave ps a1 a7aee7233393 7a:44:d3:11:10:70 10.32.0.2/12 +~~~ Weave Net detects when a container has exited and releases its allocated addresses so they can be re-used by the network. diff --git a/site/using-weave/multi-cloud-multi-hop.md b/site/using-weave/multi-cloud-multi-hop.md index 214177eb..7e1e7ad0 100644 --- a/site/using-weave/multi-cloud-multi-hop.md +++ b/site/using-weave/multi-cloud-multi-hop.md @@ -16,7 +16,7 @@ the `WEAVE_PORT` setting. For example, if WEAVE_PORT is set to `9000`, then Weave uses TCP 9000 for its control port and UDP 9000/9001 for its data port. ->>**Important!** It is recommended that all peers be given +>**Important!** It is recommended that all peers be given the same setting. diff --git a/site/using-weave/security-untrusted-networks.md b/site/using-weave/security-untrusted-networks.md index 17ff1891..5d977fba 100644 --- a/site/using-weave/security-untrusted-networks.md +++ b/site/using-weave/security-untrusted-networks.md @@ -8,12 +8,16 @@ To connect containers across untrusted networks, Weave Net peers can be instruct For example: +~~~bash host1$ weave launch --password wfvAwt7sj +~~~ or +~~~bash host1$ export WEAVE_PASSWORD=wfvAwt7sj host1$ weave launch +~~~ >NOTE: The command line option takes precedence over the environment variable._ @@ -24,7 +28,9 @@ or To guard against dictionary attacks, the password needs to be reasonably strong with at least 50 bits of entropy is recommended. An easy way to generate a random password that satisfies this requirement is: +~~~bash < /dev/urandom tr -dc A-Za-z0-9 | head -c9 ; echo +~~~ The same password must be specified for all Weave Net peers, by default both control and data plane traffic will then use authenticated encryption. @@ -32,9 +38,9 @@ Fast datapath does not support encryption. If you supply a password at `weave launch` the router falls back to a slower `sleeve` mode that does support encryption. -If some of your peers are co-located in a trusted network (for example within the boundary of your own datacenter) you can use the `--trusted-subnets` argument to `weave launch` to selectively disable data plane encryption as an optimization. +If some of your peers are co-located in a trusted network (for example within the boundary of your own data center) you can use the `--trusted-subnets` argument to `weave launch` to selectively disable data plane encryption as an optimization. ->>**Note:** Both peers must consider the other to be in a trusted subnet for this to take place - if they do not agree, Weave Net [falls back to a slower method](/site/fastdp/using-fastdp.md) for transporting data between peers, since fast datapath does not support encryption. +>**Note:** Both peers must consider the other to be in a trusted subnet for this to take place - if they do not agree, Weave Net [falls back to a slower method](/site/fastdp/using-fastdp.md) for transporting data between peers, since fast datapath does not support encryption. Be aware that: diff --git a/site/using-weave/service-export.md b/site/using-weave/service-export.md index 45480476..622f5d2d 100644 --- a/site/using-weave/service-export.md +++ b/site/using-weave/service-export.md @@ -13,21 +13,27 @@ you can expose the netcat service running on `HOST1` and make it accessible to t First, expose the application network to `$HOST2`, as explained in [Integrating a Host Network with a Weave Net](/site/using-weave/host-network-integration.md): +~~~bash host2$ weave expose 10.2.1.132 +~~~ Then add a NAT rule that routes the traffic from the outside world to the destination container service. +~~~bash host2$ iptables -t nat -A PREROUTING -p tcp -i eth0 --dport 2211 \ -j DNAT --to-destination $(weave dns-lookup a1):4422 +~~~ In this example, it is assumed that the "outside world" is connecting to `$HOST2` via 'eth0'. The TCP traffic to port 2211 on the external IPs will be routed to the 'nc' service running on port 4422 in the container a1. With the above in place, you can connect to the 'nc' service from anywhere using: +~~~bash echo 'Hello, world.' | nc $HOST2 2211 +~~~ ->>**Note:** Due to the way routing is handled in the Linux kernel, this won't work when run *on* `$HOST2`. +>**Note:** Due to the way routing is handled in the Linux kernel, this won't work when run *on* `$HOST2`. Similar NAT rules to the above can be used to expose services not just to the outside world but also to other, internal, networks. diff --git a/site/using-weave/service-management.md b/site/using-weave/service-management.md index 5126ad6f..2050b98d 100644 --- a/site/using-weave/service-management.md +++ b/site/using-weave/service-management.md @@ -21,25 +21,30 @@ Turning back to the [netcat example](/site/using-weave/deploying-applications.md To do this, expose the application network to `$HOST2`, as explained in [Host Network Integration](/site/using-weave/host-network-integration.md) by running: +~~~bash host2$ weave expose 10.2.1.132 +~~~ Then add a NAT rule to route from the outside world to the destination container service. +~~~bash host2$ iptables -t nat -A PREROUTING -p tcp -i eth0 --dport 2211 \ -j DNAT --to-destination $(weave dns-lookup a1):4422 +~~~ Here it is assumed that the "outside world" is connecting to `$HOST2` via 'eth0'. The TCP traffic to port 2211 on the external IPs will be routed to the 'nc' service, running in the a1 container and listening on port 4422. With the above in place, you are ready to connect to the 'nc' service from anywhere using: +~~~bash echo 'Hello, world.' | nc $HOST2 2211 +~~~ ->>**Note:** Due to the way routing is handled in the Linux kernel, this won't work when run *on* `$HOST2`. +>**Note:** Due to the way routing is handled in the Linux kernel, this won't work when run *on* `$HOST2`. Similar NAT rules to the above can used to expose services not just to the outside world but also other, internal, networks. - ###Importing Services Applications running in containers on a Weave network can be given access to services, which are only reachable from certain @@ -51,22 +56,30 @@ An additional caveat is that `$HOST3` can only be reached from `$HOST1`, which i To satisfy this scenario, first [expose the application network to the host](/site/using-weave/host-network-integration.md) by running the following on `$HOST1`: +~~~bash host1$ weave expose -h host1.weave.local 10.2.1.3 +~~~ Then add a NAT rule, which routes from the above IP to the destination service. +~~~bash host1$ iptables -t nat -A PREROUTING -p tcp -d 10.2.1.3 --dport 3322 \ -j DNAT --to-destination $HOST3:2211 +~~~ This allows any application container to reach the service by connecting to 10.2.1.3:3322. So if `$HOST3` is running a netcat service on port 2211: +~~~bash host3$ nc -lk -p 2211 +~~~ You can now connect to it from the application container running on `$HOST2` using: +~~~bash root@a2:/# echo 'Hello, world.' | nc host1 3322 +~~~ Note that you should be able to run this command from any application container. @@ -88,18 +101,23 @@ Expanding on the [netcat example](/site/using-weave/deploying-applications.md), Begin importing the service onto `$HOST2` by first exposing the application network: +~~~bash host2$ weave expose 10.2.1.3 +~~~ Then add a NAT rule which routes traffic from the `$HOST2` network (for example, anything that can connect to `$HOST2`) to the service endpoint on the Weave network: +~~~bash host2$ iptables -t nat -A PREROUTING -p tcp -i eth0 --dport 4433 \ -j DNAT --to-destination 10.2.1.3:3322 +~~~ Now any host on the same network as `$HOST2` is able to access the service: +~~~bash echo 'Hello, world.' | nc $HOST2 4433 - +~~~ ###Dynamically Changing Service Locations diff --git a/site/weave-docker-api/automatic-discovery-proxy.md b/site/weave-docker-api/automatic-discovery-proxy.md index 9057d0e0..9b85d6e2 100644 --- a/site/weave-docker-api/automatic-discovery-proxy.md +++ b/site/weave-docker-api/automatic-discovery-proxy.md @@ -28,27 +28,33 @@ Additionally, the hostname is matched against a regular expression `` an For example, you can launch the proxy using all three flags, as follows: +~~~bash host1$ weave launch-router && weave launch-proxy --hostname-from-label hostname-label --hostname-match '^aws-[0-9]+-(.*)$' --hostname-replacement 'my-app-$1' host1$ eval $(weave env) +~~~ ->>**Note:** regexp substitution groups must be pre-pended with a dollar sign +>**Note:** regexp substitution groups must be pre-pended with a dollar sign (for example, `$1`). For further details on the regular expression syntax see [Google's re2 documentation](https://github.com/google/re2/wiki/Syntax). After launching the Weave Net proxy with these flags, running a container named `aws-12798186823-foo` without labels results in weavedns registering the hostname `my-app-foo` and not `aws-12798186823-foo`. +~~~bash host1$ docker run -ti --name=aws-12798186823-foo ubuntu ping my-app-foo PING my-app-foo.weave.local (10.32.0.2) 56(84) bytes of data. 64 bytes from my-app-foo.weave.local (10.32.0.2): icmp_seq=1 ttl=64 time=0.027 ms 64 bytes from my-app-foo.weave.local (10.32.0.2): icmp_seq=2 ttl=64 time=0.067 ms +~~~ Also, running a container named `foo` with the label `hostname-label=aws-12798186823-foo` leads to the same hostname registration. +~~~bash host1$ docker run -ti --name=foo --label=hostname-label=aws-12798186823-foo ubuntu ping my-app-foo PING my-app-foo.weave.local (10.32.0.2) 56(84) bytes of data. 64 bytes from my-app-foo.weave.local (10.32.0.2): icmp_seq=1 ttl=64 time=0.031 ms 64 bytes from my-app-foo.weave.local (10.32.0.2): icmp_seq=2 ttl=64 time=0.042 ms +~~~ This is because, as explained above, if providing `--hostname-from-label` to the proxy, the specified label takes precedence over the container's name. diff --git a/site/weave-docker-api/ipam-proxy.md b/site/weave-docker-api/ipam-proxy.md index 6c5f2576..1a73d9a9 100644 --- a/site/weave-docker-api/ipam-proxy.md +++ b/site/weave-docker-api/ipam-proxy.md @@ -8,24 +8,31 @@ If [automatic IP address allocation](/site/ipam/overview-init-ipam.md) is enable then containers started via the proxy are automatically assigned an IP address, *without having to specify any special environment variables or any other options*. +~~~bash host1$ docker run -ti ubuntu +~~~ To use a specific subnet, you can pass a `WEAVE_CIDR` to the container, for example: +~~~bash host1$ docker run -ti -e WEAVE_CIDR=net:10.32.2.0/24 ubuntu +~~ To start a container without connecting it to the Weave network, pass `WEAVE_CIDR=none`, for example: +~~~bash host1$ docker run -ti -e WEAVE_CIDR=none ubuntu - +~~~ ###Disabling Automatic IP Address Allocation If you do not want an IP to be assigned by default, the proxy needs to be passed the `--no-default-ipalloc` flag, for example: +~~~bash host1$ weave launch-proxy --no-default-ipalloc +~~~ In this configuration, containers using no `WEAVE_CIDR` environment variable are not connected to the Weave network. @@ -34,7 +41,9 @@ Containers started with a `WEAVE_CIDR` environment variable are handled as befor To automatically assign an address in this mode, start the container with a blank `WEAVE_CIDR`, for example: +~~~bash host1$ docker run -ti -e WEAVE_CIDR="" ubuntu +~~~ **See Also** diff --git a/site/weave-docker-api/launching-without-proxy.md b/site/weave-docker-api/launching-without-proxy.md index ef37c6fa..24f55f26 100644 --- a/site/weave-docker-api/launching-without-proxy.md +++ b/site/weave-docker-api/launching-without-proxy.md @@ -7,7 +7,9 @@ layout: default If you don't want to use the proxy, you can also launch containers on to the Weave network using `weave run`: +~~~bash $ weave run -ti ubuntu +~~~ The arguments after `run` are passed through to `docker run`. Therefore you can freely specify whatever Docker options you need. @@ -17,14 +19,18 @@ this example, it obtains an automatically allocated IP. You can specify IP addresses manually instead: +~~~bash $ weave run 10.2.1.1/24 -ti ubuntu +~~~ `weave run` rewrites `/etc/hosts` in the same way [the proxy does](/site/weave-docker-api/name-resolution-proxy.md). If you need to keep the original file, specify `--no-rewrite-hosts` when running the container: +~~~bash $ weave run --no-rewrite-hosts 10.2.1.1/24 -ti ubuntu +~~~ There are some limitations to starting containers using `weave run`: diff --git a/site/weave-docker-api/name-resolution-proxy.md b/site/weave-docker-api/name-resolution-proxy.md index 4020d0b9..79d0e1c3 100644 --- a/site/weave-docker-api/name-resolution-proxy.md +++ b/site/weave-docker-api/name-resolution-proxy.md @@ -26,7 +26,9 @@ IP instead of the Weave IP, or you require name resolution for Docker-managed networks), the proxy must be launched using the `--no-rewrite-hosts` flag. +~~~bash host1$ weave launch-router && weave launch-proxy --no-rewrite-hosts +~~~ **See Also** diff --git a/site/weave-docker-api/securing-proxy.md b/site/weave-docker-api/securing-proxy.md index 542164e3..4abf5bbe 100644 --- a/site/weave-docker-api/securing-proxy.md +++ b/site/weave-docker-api/securing-proxy.md @@ -11,7 +11,9 @@ attempts to duplicate it. In the standard auto-detection case you can launch a TLS-enabled proxy as follows: +~~~bash host1$ weave launch-proxy +~~~ To disable auto-detection of TLS configuration, you can either pass the `--no-detect-tls` flag, or you can manually configure the proxy's TLS using @@ -21,8 +23,10 @@ daemon. For example, if you generated your certificates and keys into the Docker host's `/tls` directory, launch the proxy using: +~~~bash host1$ weave launch-proxy --tlsverify --tlscacert=/tls/ca.pem \ --tlscert=/tls/server-cert.pem --tlskey=/tls/server-key.pem +~~~ The paths to your certificates and key must be provided as absolute paths as they exist on the Docker host. @@ -37,18 +41,20 @@ for an example. With the proxy running over TLS, you can configure the Docker client to use TLS on a per-invocation basis by running: +~~~bash $ docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem \ --tlskey=key.pem -H=tcp://host1:12375 version - ... +~~~ or, [by default](https://docs.docker.com/articles/https/#secure-by-default), using: +~~~bash $ mkdir -pv ~/.docker $ cp -v {ca,cert,key}.pem ~/.docker $ eval $(weave env) $ export DOCKER_TLS_VERIFY=1 $ docker version - ... +~~~ This is exactly the same configuration used when connecting to the Docker daemon directly, except that the specified port is the Weave diff --git a/site/weave-docker-api/set-up-proxy.md b/site/weave-docker-api/set-up-proxy.md index 7db598ff..0638310e 100644 --- a/site/weave-docker-api/set-up-proxy.md +++ b/site/weave-docker-api/set-up-proxy.md @@ -17,14 +17,18 @@ The proxy sits between the Docker client (command line or API) and the Docker daemon, and intercepts the communication between the two. You can start it simultaneously with the router and weavedns via `launch`: +~~~bash host1$ weave launch +~~~ or independently via `launch-proxy`: +~~~bash host1$ weave launch-router && weave launch-proxy +~~~ The first form is more convenient. But only `launch-proxy` can be passed configuration arguments. -Therefor if you need to modify the default behaviour of the proxy, you must use `launch-proxy`. +Therefore if you need to modify the default behaviour of the proxy, you must use `launch-proxy`. By default, the proxy decides where to listen based on how the launching client connects to Docker. If the launching client connected @@ -33,11 +37,13 @@ the launching client connects over TCP, the proxy listens on port 12375, on all network interfaces. This can be adjusted using the `-H` argument, for example: +~~~bash host1$ weave launch-proxy -H tcp://127.0.0.1:9999 +~~~ -If no TLS or listening interfaces are set, TLS is autoconfigured +If no TLS or listening interfaces are set, TLS is auto-configured based on the Docker daemon's settings, and the listening interfaces are -autoconfigured based on your Docker client's settings. +auto-configured based on your Docker client's settings. Multiple `-H` arguments can be specified. If you are working with a remote docker daemon, then any firewalls in between need to be @@ -47,23 +53,30 @@ All docker commands can be run via the proxy, so it is safe to adjust your `DOCKER_HOST` to point at the proxy. Weave Net provides a convenient command for this: +~~~bash host1$ eval $(weave env) host1$ docker ps - ... +~~~ The prior settings can be restored with +~~~bash host1$ eval $(weave env --restore) +~~~ Alternatively, the proxy host can be set on a per-command basis with +~~~bash host1$ docker $(weave config) ps +~~~ The proxy can be stopped independently with +~~~bash host1$ weave stop-proxy +~~~ -or in conjunction with the router and weaveDNS via `stop`. +or in conjunction with the router and weavedns via `stop`. If you set your `DOCKER_HOST` to point at the proxy, you should revert to the original settings prior to stopping the proxy. diff --git a/site/weave-docker-api/troubleshooting-proxy.md b/site/weave-docker-api/troubleshooting-proxy.md index b8c6ded0..764719dc 100644 --- a/site/weave-docker-api/troubleshooting-proxy.md +++ b/site/weave-docker-api/troubleshooting-proxy.md @@ -5,20 +5,23 @@ layout: default The command +~~~bash weave status +~~~ reports on the current status of various Weave Net components, including the proxy, if it is running: -```` -... +~~~bash weave proxy is running -```` +~~~ Information on the operation of the proxy can be obtained from the weaveproxy container logs using: +~~~bash docker logs weaveproxy +~~~ **See Also** diff --git a/site/weave-docker-api/using-proxy.md b/site/weave-docker-api/using-proxy.md index 70c54d83..585fc720 100644 --- a/site/weave-docker-api/using-proxy.md +++ b/site/weave-docker-api/using-proxy.md @@ -16,18 +16,24 @@ Weave network. To create and start a container via the Weave Net proxy run: +~~~bash host1$ docker run -ti ubuntu +~~~ or, equivalently run: +~~~bash host1$ docker create -ti ubuntu 5ef831df61d50a1a49272357155a976595e7268e590f0a2c75693337b14e1382 host1$ docker start 5ef831df61d50a1a49272357155a976595e7268e590f0a2c75693337b14e1382 +~~~ Specific IP addresses and networks can be supplied in the `WEAVE_CIDR` environment variable, for example: +~~~bash host1$ docker run -e WEAVE_CIDR=10.2.1.1/24 -ti ubuntu +~~~ Multiple IP addresses and networks can be supplied in the `WEAVE_CIDR` variable by space-separating them, as in @@ -45,8 +51,9 @@ This command substitutes the Weave network settings when the container has a Weave Net IP. If a container has more than one Weave Net IP, then the inspect call only includes one of them. +~~~bash host1$ weave launch-router && weave launch-proxy --rewrite-inspect - +~~~ ###Multicast Traffic and Launching the Weave Proxy diff --git a/site/weavedns/managing-entries-weavedns.md b/site/weavedns/managing-entries-weavedns.md index 3331fe96..228d8378 100644 --- a/site/weavedns/managing-entries-weavedns.md +++ b/site/weavedns/managing-entries-weavedns.md @@ -53,8 +53,10 @@ which they were added. You can resolve entries from any host running weaveDNS with `weave dns-lookup`: +~~~bash host1$ weave dns-lookup pingme 10.40.0.1 +~~~ ### Hot-swapping service containers diff --git a/site/weavedns/overview-using-weavedns.md b/site/weavedns/overview-using-weavedns.md index d4f3ba3c..57f257ff 100644 --- a/site/weavedns/overview-using-weavedns.md +++ b/site/weavedns/overview-using-weavedns.md @@ -32,7 +32,7 @@ root@ubuntu:/# ping pingme ... ``` ->> **Note** If both hostname and container name are specified at +> **Note** If both hostname and container name are specified at the same time, the hostname takes precedence. In this circumstance, if the hostname is not in the weavedns domain, the container is *not* registered, but it will still use weavedns for resolution. diff --git a/site/weavedns/troubleshooting-weavedns.md b/site/weavedns/troubleshooting-weavedns.md index 77c418a2..4dd251b9 100644 --- a/site/weavedns/troubleshooting-weavedns.md +++ b/site/weavedns/troubleshooting-weavedns.md @@ -10,22 +10,20 @@ layout: default The command: +~~~bash weave status +~~~ reports on the current status of various Weave Net components, including DNS: -```` -... - +~~~bash Service: dns Domain: weave.local. Upstream: 8.8.8.8, 8.8.4.4 TTL: 1 Entries: 9 - -... -```` +~~~ The first section covers the router; see the [troubleshooting guide](/site/troubleshooting.md#weave-status) for more details. @@ -43,7 +41,9 @@ dump](/site/troubleshooting.md#weave-status-dns) of all DNS registrations. Information on the processing of queries, and the general operation of weaveDNS, can be obtained from the container logs with +~~~bash docker logs weave +~~~ ### Present Limitations