Added documentation website content, and a workflow to publish it to GitHub Pages
* Copied, rearranged and modified the contents of the old site directory for Jekyll static site generator, into the website directory * Added some Jekyll-specific things for looks, including: * _config.yaml, Gemfile.* and 404.html files * _data, _layouts and assets directories and their content * Added .github/workflows/github-pages-publish.yml workflow
This commit is contained in:
1 parent
92779f3e57
commit
e2db8a25bd
82 files changed
+6162
No files matched your search
@@ -0,0 +1,214 @@
|
||||
---
|
||||
title: How Weave Net Implements Encryption
|
||||
menu_order: 60
|
||||
search_type: Documentation
|
||||
---
|
||||
|
||||
This section describes some details of Weave Net's built-in
|
||||
[encryption]({{ '/concepts/encryption' | relative_url }}):
|
||||
|
||||
* [Establishing the Ephemeral Session Key](#ephemeral-key)
|
||||
* [Key Generation](#csprng)
|
||||
* [Encypting and Decrypting TCP Messages](#tcp)
|
||||
* [Encypting and Decrypting UDP Messages](#udp)
|
||||
|
||||
|
||||
|
||||
#### <a name="ephemeral-key"></a>Establishing the Ephemeral Session Key
|
||||
|
||||
For every connection between peers, a fresh public/private key pair is
|
||||
created at both ends, using NaCl's `GenerateKey` function. The public
|
||||
key portion is sent to the other end as part of the initial handshake
|
||||
performed over TCP. Peers that were started with a password do not
|
||||
continue with connection establishment unless they receive a public
|
||||
key from the remote peer. Thus either all peers in a weave network
|
||||
must be supplied with a password, or none.
|
||||
|
||||
When a peer has received a public key from the remote peer, it uses
|
||||
this to form the ephemeral session key for this connection. The public
|
||||
key from the remote peer is combined with the private key for the
|
||||
local peer in the usual [Diffie-Hellman way](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange),
|
||||
resulting in both peers arriving at the same shared key. To this is appended the supplied
|
||||
password, and the result is hashed through SHA256, to form the final
|
||||
ephemeral session key.
|
||||
|
||||
The supplied password is never exchanged directly, and is thoroughly
|
||||
mixed into the shared secret. Furthermore, the rate at which TCP connections
|
||||
are accepted is limited by Weave to 10Hz, which thwarts online
|
||||
dictionary attacks on reasonably strong passwords.
|
||||
|
||||
The shared key formed by Diffie-Hellman is 256 bits long. Appending
|
||||
the password to this obviously makes it longer by an unknown amount,
|
||||
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 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
|
||||
between two peers.
|
||||
|
||||
### <a name="csprng"></a> Key Generation and The Linux CSPRNG
|
||||
|
||||
Generating fresh keys for every connection
|
||||
provides forward secrecy at the cost of placing a demand on the Linux
|
||||
CSPRNG (accessed by `GenerateKey` via `/dev/urandom`) proportional to
|
||||
the number of inbound connection attempts. Weave Net has accept throttling
|
||||
to mitigate against denial of service attacks that seek to deplete the
|
||||
CSPRNG entropy pool, however even at the lower bound of ten requests
|
||||
per second, there may not be enough entropy gathered on a headless
|
||||
system to keep pace.
|
||||
|
||||
Under such conditions, the consequences will be limited to slowing
|
||||
down processes reading from the blocking `/dev/random` device as the
|
||||
kernel waits for enough new entropy to be harvested. It is important
|
||||
to note that contrary to intuition, this low entropy state does not
|
||||
compromise the ongoing use of `/dev/urandom`. [Expert
|
||||
opinion](http://blog.cr.yp.to/20140205-entropy.html)
|
||||
asserts that as long as the CSPRNG is seeded with enough entropy (for example,
|
||||
256 bits) before random number generation commences, then the output is
|
||||
entirely safe for use as key material.
|
||||
|
||||
By way of comparison, this is exactly how OpenSSL works - it reads 256
|
||||
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 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
|
||||
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.
|
||||
|
||||
#### <a name="tcp"></a>Encypting and Decrypting TCP Messages
|
||||
|
||||
TCP connection are only used to exchange topology information between
|
||||
peers, via a message-based protocol. Encryption of each message is
|
||||
carried out by NaCl's `secretbox.Seal` function using the ephemeral
|
||||
session key and a nonce. The nonce contains the message sequence
|
||||
number, which is incremented for every message sent, and a bit
|
||||
indicating the polarity of the connection at the sender ('1' for
|
||||
outbound). The latter is required by the
|
||||
[NaCl Security Model](http://nacl.cr.yp.to/box.html) in order to
|
||||
ensure that the two ends of the connection do not use the same nonces.
|
||||
|
||||
Decryption of a message at the receiver is carried out by NaCl's
|
||||
`secretbox.Open` function using the ephemeral session key and a
|
||||
nonce. The receiver maintains its own message sequence number, which
|
||||
it increments for every message it decrypted successfully. The nonce
|
||||
is constructed from that sequence number and the connection
|
||||
polarity. As a result the receiver will only be able to decrypt a
|
||||
message if it has the expected sequence number. This prevents replay
|
||||
attacks.
|
||||
|
||||
#### <a name="udp"></a>Encrypting and Decrypting UDP Packets
|
||||
|
||||
##### Sleeve
|
||||
|
||||
UDP connections carry captured traffic between peers. For a UDP packet
|
||||
sent between peers that are using crypto, the encapsulation looks as
|
||||
follows:
|
||||
|
||||
+-----------------------------------+
|
||||
| Name of sending peer |
|
||||
+-----------------------------------+
|
||||
| Message Sequence No and flags |
|
||||
+-----------------------------------+
|
||||
| NaCl SecretBox overheads |
|
||||
+-----------------------------------+ -+
|
||||
| Frame 1: Name of capturing peer | |
|
||||
+-----------------------------------+ | This section is encrypted
|
||||
| Frame 1: Name of destination peer | | using the ephemeral session
|
||||
+-----------------------------------+ | key between the weave peers
|
||||
| Frame 1: Captured payload length | | sending and receiving this
|
||||
+-----------------------------------+ | packet.
|
||||
| Frame 1: Captured payload | |
|
||||
+-----------------------------------+ |
|
||||
| Frame 2: Name of capturing peer | |
|
||||
+-----------------------------------+ |
|
||||
| Frame 2: Name of destination peer | |
|
||||
+-----------------------------------+ |
|
||||
| Frame 2: Captured payload length | |
|
||||
+-----------------------------------+ |
|
||||
| Frame 2: Captured payload | |
|
||||
+-----------------------------------+ |
|
||||
| ... | |
|
||||
+-----------------------------------+ |
|
||||
| Frame N: Name of capturing peer | |
|
||||
+-----------------------------------+ |
|
||||
| Frame N: Name of destination peer | |
|
||||
+-----------------------------------+ |
|
||||
| Frame N: Captured payload length | |
|
||||
+-----------------------------------+ |
|
||||
| Frame N: Captured payload | |
|
||||
+-----------------------------------+ -+
|
||||
|
||||
This is very similar to the [non-crypto encapsulation]({{ '/concepts/router-encapsulation' | relative_url }}).
|
||||
|
||||
All of the frames on a connection are encrypted with the same
|
||||
ephemeral session key, and a nonce constructed from a message sequence
|
||||
number, flags and the connection polarity. This is very similar to the
|
||||
TCP encryption scheme, and encryption is again done with the NaCl
|
||||
`secretbox.Seal` function. The main difference is that the message
|
||||
sequence number and flags are transmitted as part of the message,
|
||||
unencrypted.
|
||||
|
||||
The receiver uses the name of the sending peer to determine which
|
||||
ephemeral session key and local cryptographic state to use for
|
||||
decryption. Frames which are to be forwarded on to some further peer
|
||||
will be re-encrypted with the relevant ephemeral session keys for the
|
||||
onward connections. Thus all traffic is fully decrypted on every peer
|
||||
it passes through.
|
||||
|
||||
Decryption is once again carried out by NaCl's `secretbox.Open`
|
||||
function using the ephemeral session key and nonce. The latter is
|
||||
constructed from the message sequence number and flags that appeared
|
||||
in the unencrypted portion of the received message, and the connection
|
||||
polarity.
|
||||
|
||||
To guard against replay attacks, the receiver maintains some state in
|
||||
which it remembers the highest message sequence number seen. It could
|
||||
simply reject messages with lower sequence numbers, but that could
|
||||
result in excessive message loss when messages are re-ordered. The
|
||||
receiver therefore additionally maintains a set of received message
|
||||
sequence numbers in a window below the highest number seen, and only
|
||||
rejects messages with a sequence number below that window, or
|
||||
contained in the set. The window spans at least 2^20 message sequence
|
||||
numbers, and hence any re-ordering between the most recent ~1 million
|
||||
messages is handled without dropping messages.
|
||||
|
||||
##### Fast Datapath
|
||||
|
||||
Encryption in fastdp uses [the ESP protocol of IPsec](https://tools.ietf.org/html/rfc2406)
|
||||
in the transport mode. Each VXLAN packet is encrypted with
|
||||
[AES in GCM mode](https://tools.ietf.org/html/rfc4106aesgcm), with 32 byte key and
|
||||
4 byte salt. This combo provides the following security properties:
|
||||
|
||||
* Data confidentiality.
|
||||
* Data origin authentication.
|
||||
* Integrity.
|
||||
* Anti-replay.
|
||||
* Limited traffic flow confidentiality as VXLAN packets are fully encrypted.
|
||||
|
||||
For each connection direction, a different AES-GCM key and salt is used.
|
||||
The pairs are derived with [HKDF](https://tools.ietf.org/html/rfc5869)
|
||||
to which we pass a randomly generated 32 byte salt transferred over the encrypted
|
||||
control plane channel between peers.
|
||||
|
||||
To prevent from replay attacks, which are possible because of the size of
|
||||
sequence number field in ESP (4 bytes), we use extended sequence numbers
|
||||
implemented by [ESN](https://tools.ietf.org/html/rfc4304).
|
||||
|
||||
Authentication of ESP packet integrity and origin is ensured by 16 byte
|
||||
Integrity Check Value of AES-GCM.
|
||||
|
||||
**See Also**
|
||||
|
||||
* [architecture documentation](https://github.com/rajch/weave/blob/master/docs/architecture.txt)
|
||||
* [fastdp encryption](https://github.com/rajch/weave/blob/master/docs/fastdp-crypto.md)
|
||||
* [Securing Containers Across Untrusted Networks]({{ '/tasks/manage/security-untrusted-networks' | relative_url }})
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: Encryption and Weave Net
|
||||
menu_order: 50
|
||||
search_type: Documentation
|
||||
---
|
||||
|
||||
|
||||
Weave Net peers
|
||||
[communicate with each other over both TCP and UDP]({{ '/concepts/how-it-works' | relative_url }}). This
|
||||
communication
|
||||
[can be encrypted]({{ '/tasks/manage/security-untrusted-networks' | relative_url }}).
|
||||
|
||||
Encryption of control plane traffic (TCP) and data plane traffic (UDP) of sleeve
|
||||
overlay is accomplished using the [NaCl](http://nacl.cr.yp.to/)
|
||||
crypto libraries, employing Curve25519, XSalsa20 and Poly1305 to
|
||||
encrypt and authenticate messages. Weave Net protects against
|
||||
injection and replay attacks for traffic forwarded between peers.
|
||||
|
||||
NaCl was selected because of its good reputation both in terms of
|
||||
selection and implementation of ciphers, but equally importantly, its
|
||||
clear APIs, good documentation and high-quality
|
||||
[go implementation](https://godoc.org/golang.org/x/crypto/nacl). It is
|
||||
quite difficult to use NaCl incorrectly. Contrast this with libraries
|
||||
such as OpenSSL where the library and its APIs are vast in size,
|
||||
poorly documented, and easily used wrongly.
|
||||
|
||||
There are some similarities between Weave Net's crypto and
|
||||
[TLS](https://tools.ietf.org/html/rfc4346). Weave Net does not need to cater
|
||||
for multiple cipher suites, certificate exchange and other
|
||||
requirements emanating from X509, and a number of other features. This
|
||||
simplifies the protocol and implementation considerably. On the other
|
||||
hand, Weave Net needs to support UDP transports, and while there are
|
||||
extensions to TLS such as [DTLS](https://tools.ietf.org/html/rfc4347)
|
||||
which can operate over UDP, these are not widely implemented and
|
||||
deployed.
|
||||
|
||||
In the case of fast datapath, data plane traffic is encrypted by using
|
||||
[ESP of IPsec](https://tools.ietf.org/html/rfc2406).
|
||||
The process of encryption is handled by the Linux kernel and is controlled via
|
||||
the IP transformation framework (XFRM).
|
||||
|
||||
**See Also**
|
||||
|
||||
* [How Weave Implements Encryption]({{ '/concepts/encryption-implementation' | relative_url }})
|
||||
* [Securing Containers Across Untrusted Networks]({{ '/tasks/manage/security-untrusted-networks' | relative_url }})
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Fast Datapath & Weave Net
|
||||
menu_order: 30
|
||||
search_type: Documentation
|
||||
---
|
||||
|
||||
|
||||
Weave Net implements an overlay network between Docker hosts. Without fast datapath enabled, each packet is encapsulated in a tunnel protocol header and sent to the destination host, where the header is removed. The Weave router is a user space process, which means that the packet follows a winding path in and out of the Linux kernel:
|
||||
|
||||

|
||||
|
||||
|
||||
The fast datapath in Weave Net uses the Linux kernel's [Open vSwitch datapath module](https://www.kernel.org/doc/Documentation/networking/openvswitch.txt). This module enables the Weave Net router to tell the kernel how to process packets:
|
||||
|
||||

|
||||
|
||||
Because Weave Net issues instructions directly to the kernel, context switches are decreased, and so by using `fast datapath` CPU overhead and latency is reduced. The packet goes straight from your application to the kernel, where the Virtual Extensible Lan (VXLAN) header is added (the NIC does this if it offers VXLAN acceleration). VXLAN is an IETF standard UDP-based tunneling protocol that enable you to use common networking tools like [Wireshark](https://www.wireshark.org/) to inspect the tunneled packets.
|
||||
|
||||

|
||||
|
||||
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.
|
||||
|
||||
|
||||
**See Also**
|
||||
|
||||
* [Launching Weave Net]({{ '/install/using-weave' | relative_url }})
|
||||
* [Using Fast Datapath]({{ '/tasks/manage/fastdp' | relative_url }})
|
||||
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: Understanding Weave Net
|
||||
menu_order: 10
|
||||
search_type: Documentation
|
||||
---
|
||||
|
||||
A Weave network consists of a number of 'peers' - Weave Net routers
|
||||
residing on different hosts. Each peer has a name, which tends to
|
||||
remain the same over restarts, a human friendly nickname for use in
|
||||
status and logging output and a unique identifier (UID) that is
|
||||
different each time it is run. These are opaque identifiers as far as
|
||||
the router is concerned, although the name defaults to a MAC address.
|
||||
|
||||
Weave Net routers establish TCP connections with each other, over which they
|
||||
perform a protocol handshake and subsequently exchange
|
||||
[topology]({{ '/concepts/network-topology' | relative_url }}) information.
|
||||
These connections are encrypted if
|
||||
so configured. Peers also establish UDP "connections", possibly
|
||||
encrypted, which carry encapsulated network packets. These
|
||||
"connections" are duplex and can traverse firewalls.
|
||||
|
||||
Weave Net creates a network bridge on the host. Each container is
|
||||
connected to that bridge via a veth pair, the container side of which
|
||||
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]({{ '/tasks/manage/fastdp' | relative_url }}) 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
|
||||
UDP to weave router peers running on other hosts, and there injected
|
||||
back into the kernel which in turn passes them to local destination
|
||||
containers.
|
||||
|
||||
Weave Net routers learn which peer host a particular MAC address resides
|
||||
on. They combine this knowledge with topology information in order to
|
||||
make routing decisions and thus avoid forwarding every packet to every
|
||||
peer. Weave Net can route packets in partially connected networks with
|
||||
changing topology. For example, in this network, peer 1 is connected
|
||||
directly to 2 and 3, but if 1 needs to send a packet to 4 or 5 it must
|
||||
first send it to peer 3:
|
||||
|
||||

|
||||
|
||||
**See Also**
|
||||
|
||||
* [Weave Router Sleeve Encapsulation]({{ '/concepts/router-encapsulation' | relative_url }})
|
||||
* [How Weave Interprets Network Topology]({{ '/concepts/network-topology' | relative_url }})
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: Concepts in Weave Net
|
||||
menu_order: 20
|
||||
search_type: Documentation
|
||||
---
|
||||
|
||||
The section contains topics about how Weave Net works as well as providing a technical deep dive on how Weave Net implements fast datapath, and encryption.
|
||||
|
||||
* [Understanding Weave Net]({{ '/concepts/how-it-works' | relative_url }})
|
||||
* [Weave Net Router Sleeve Encapsulation]({{ '/concepts/router-encapsulation' | relative_url }})
|
||||
* [How Weave Net Interprets Network Topology]({{ '/concepts/network-topology' | relative_url }})
|
||||
* [Communicating Topology Among Peers]({{ '/concepts/network-topology#topology' | relative_url }})
|
||||
* [How Messages are Formed]({{ '/concepts/network-topology#messages' | relative_url }})
|
||||
* [Removing Peers]({{ '/concepts/network-topology#removing-peers' | relative_url }})
|
||||
* [What Happens When The Topology is Out of Date?]({{ '/concepts/network-topology#out-of-date-topology' | relative_url }})
|
||||
* [Fast Datapath & Weave Net]({{ '/concepts/fastdp-how-it-works' | relative_url }})
|
||||
* [IP Addresses, Routes and Networks]({{ '/concepts/ip-addresses' | relative_url }})
|
||||
* [Encryption and Weave Net]({{ '/concepts/encryption' | relative_url }})
|
||||
* [How Weave Net Implements Encryption]({{ '/concepts/encryption-implementation' | relative_url }})
|
||||
* [Establishing the Emphemeral Session Key]({{ '/concepts/network-topology#ephemeral-key' | relative_url }})
|
||||
* [Key Generation and the Linux CSPRIN]({{ '/concepts/network-topology#cspring' | relative_url }})
|
||||
* [Encrypting and Decrypting TCP Messages]({{ '/concepts/network-topology#tcp' | relative_url }})
|
||||
* [Encrypting and Decrypting UDP Messages]({{ '/concepts/network-topology#udp' | relative_url }})
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: IP Addresses, Routes and Networks
|
||||
menu_order: 40
|
||||
search_type: Documentation
|
||||
---
|
||||
|
||||
|
||||
Weave Net runs containers on a private network, which means that IP addresses are isolated from the rest of the
|
||||
Internet, and that you don't have to worry about addresses clashing.
|
||||
|
||||
You can of course also manually change the IP of any given container or subnet on a Weave network. See, [How to Manually Specify IP Addresses and Subnets]({{ '/tasks/ipam/manual-ip-address' | relative_url }})
|
||||
|
||||
### 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.
|
||||
|
||||
### IP Address Notation in Weave
|
||||
|
||||
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. For example, `6.250.3.1/9` is on the
|
||||
`6.128.0.0/9` network.
|
||||
|
||||
Several websites offer calculators to decode this kind of address, see, for example: [IP Address Guide](http://www.ipaddressguide.com/cidr).
|
||||
|
||||
The following is an example route table for a container that is attached to a 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.
|
||||
|
||||
**See Also**
|
||||
|
||||
* [Allocating IPs in a Specific Range]({{ '/tasks/ipam/configuring-weave' | relative_url }})
|
||||
@@ -0,0 +1,160 @@
|
||||
---
|
||||
title: How Weave Net Interprets Network Topology
|
||||
menu_order: 20
|
||||
search_type: Documentation
|
||||
---
|
||||
|
||||
This section contains the following topics:
|
||||
|
||||
* [Communicating Topology Among Peers](#topology)
|
||||
* [How Messages are Formed](#messages)
|
||||
* [Removing Peers](#removing-peers)
|
||||
* [What Happens When The Topology is Out of Date?](#out-of-date-topology)
|
||||
|
||||
|
||||
### <a name="topology"></a>Communicating Topology Among Peers
|
||||
|
||||
Topology messages capture which peers are connected to other peers.
|
||||
Weave peers communicate their knowledge of the topology
|
||||
(and changes to it) to others, so that all peers learn about the
|
||||
entire topology.
|
||||
|
||||
Communication between peers occurs over TCP links using:
|
||||
a) a spanning-tree based broadcast mechanism, and b) a
|
||||
neighbor gossip mechanism.
|
||||
|
||||
Topology messages are sent by a peer in the following instances:
|
||||
|
||||
- when a connection has been added; if the remote peer appears to be
|
||||
new to the network, the entire topology is sent to it, and an
|
||||
incremental update, containing information on just the two peers at
|
||||
the ends of the connection, is broadcast,
|
||||
- when a connection has been marked as 'established', indicating that
|
||||
the remote peer can receive UDP traffic from the peer; an update
|
||||
containing just information about the local peer is broadcast,
|
||||
- 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 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.
|
||||
|
||||
The receiver of a topology update merges that update with its own
|
||||
topology model, adding peers hitherto unknown to it, and updating
|
||||
peers for which the update contains a more recent version than known
|
||||
to it. If there were any such new/updated peers, and the topology
|
||||
update was received over gossip (rather than broadcast), then an
|
||||
improved update containing them is gossiped.
|
||||
|
||||
If the update mentions a peer that the receiver does not know, then
|
||||
the entire update is ignored.
|
||||
|
||||
#### <a name="messages"></a>How Messages Are Formed
|
||||
|
||||
Every gossip message is structured as follows:
|
||||
|
||||
+-----------------------------------+
|
||||
| 1-byte message type - Gossip |
|
||||
+-----------------------------------+
|
||||
| 4-byte Gossip channel - Topology |
|
||||
+-----------------------------------+
|
||||
| Peer Name of source |
|
||||
+-----------------------------------+
|
||||
| Gossip payload (topology update) |
|
||||
+-----------------------------------+
|
||||
|
||||
The topology update payload is laid out like this:
|
||||
|
||||
+-----------------------------------+
|
||||
| Peer 1: Name |
|
||||
+-----------------------------------+
|
||||
| Peer 1: NickName |
|
||||
+-----------------------------------+
|
||||
| Peer 1: UID |
|
||||
+-----------------------------------+
|
||||
| Peer 1: Version number |
|
||||
+-----------------------------------+
|
||||
| Peer 1: List of connections |
|
||||
+-----------------------------------+
|
||||
| ... |
|
||||
+-----------------------------------+
|
||||
| Peer N: Name |
|
||||
+-----------------------------------+
|
||||
| Peer N: NickName |
|
||||
+-----------------------------------+
|
||||
| Peer N: UID |
|
||||
+-----------------------------------+
|
||||
| Peer N: Version number |
|
||||
+-----------------------------------+
|
||||
| Peer N: List of connections |
|
||||
+-----------------------------------+
|
||||
|
||||
Each List of connections is encapsulated as a byte buffer, within
|
||||
which the structure is:
|
||||
|
||||
+-----------------------------------+
|
||||
| Connection 1: Remote Peer Name |
|
||||
+-----------------------------------+
|
||||
| Connection 1: Remote IP address |
|
||||
+-----------------------------------+
|
||||
| Connection 1: Outbound |
|
||||
+-----------------------------------+
|
||||
| Connection 1: Established |
|
||||
+-----------------------------------+
|
||||
| Connection 2: Remote Peer Name |
|
||||
+-----------------------------------+
|
||||
| Connection 2: Remote IP address |
|
||||
+-----------------------------------+
|
||||
| Connection 2: Outbound |
|
||||
+-----------------------------------+
|
||||
| Connection 2: Established |
|
||||
+-----------------------------------+
|
||||
| ... |
|
||||
+-----------------------------------+
|
||||
| Connection N: Remote Peer Name |
|
||||
+-----------------------------------+
|
||||
| Connection N: Remote IP address |
|
||||
+-----------------------------------+
|
||||
| Connection N: Outbound |
|
||||
+-----------------------------------+
|
||||
| Connection N: Established |
|
||||
+-----------------------------------+
|
||||
|
||||
#### <a name="removing-peers"></a>Removing Peers
|
||||
|
||||
If a peer, after receiving a topology update, sees that another peer
|
||||
no longer has any connections within the network, it drops all
|
||||
knowledge of that second peer.
|
||||
|
||||
|
||||
#### <a name="out-of-date-topology"></a>What Happens When The Topology is Out of Date?
|
||||
|
||||
The propagation of topology changes to all peers is not instantaneous.
|
||||
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
|
||||
out-of-date topology can result in it taking a less efficient route.
|
||||
|
||||
If the out-of-date topology makes it look as if the destination peer
|
||||
is not reachable, then the packet is dropped. For most protocols
|
||||
(for example, TCP), the transmission will be retried a short time later, by
|
||||
which time the topology should have updated.
|
||||
|
||||
#### <a name="connection-limit"></a>Connection Limit
|
||||
|
||||
In a fully connected mesh of N peers, this would mean N^2 connections. To constrain the resource consumption and
|
||||
communication between the peers and complexity of route calculation there is a configurable upper limit on the
|
||||
maximum number of connections that a peer can make to the remote peers. There is safe default value (100) which works
|
||||
for most deployment. However if you would like to increase the number of peers, you should be able to explicitly override the
|
||||
default value by passing the value through `connlimit` flag for e.g.`weave launch --connlimit=100`. If you are using Weave with
|
||||
Kubernetes using [Kubernetes Addon]({{ '/kubernetes/kube-addon' | relative_url }}) then you can set CONN_LIMIT environment variable to set
|
||||
the connection limit.
|
||||
|
||||
**See Also**
|
||||
|
||||
* [Weave Net Router Encapsulation]({{ '/concepts/router-encapsulation' | relative_url }})
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Weave Net Router Sleeve Encapsulation
|
||||
menu_order: 15
|
||||
search_type: Documentation
|
||||
---
|
||||
|
||||
When the Weave Net router forwards packets to peers in `sleeve` mode
|
||||
(rather than via the [fast data path]({{ '/tasks/manage/fastdp' | relative_url }})), the
|
||||
encapsulation looks something like this:
|
||||
|
||||
+-----------------------------------+
|
||||
| Name of sending peer |
|
||||
+-----------------------------------+
|
||||
| Frame 1: Name of capturing peer |
|
||||
+-----------------------------------+
|
||||
| Frame 1: Name of destination peer |
|
||||
+-----------------------------------+
|
||||
| Frame 1: Captured payload length |
|
||||
+-----------------------------------+
|
||||
| Frame 1: Captured payload |
|
||||
+-----------------------------------+
|
||||
| Frame 2: Name of capturing peer |
|
||||
+-----------------------------------+
|
||||
| Frame 2: Name of destination peer |
|
||||
+-----------------------------------+
|
||||
| Frame 2: Captured payload length |
|
||||
+-----------------------------------+
|
||||
| Frame 2: Captured payload |
|
||||
+-----------------------------------+
|
||||
| ... |
|
||||
+-----------------------------------+
|
||||
| Frame N: Name of capturing peer |
|
||||
+-----------------------------------+
|
||||
| Frame N: Name of destination peer |
|
||||
+-----------------------------------+
|
||||
| Frame N: Captured payload length |
|
||||
+-----------------------------------+
|
||||
| Frame N: Captured payload |
|
||||
+-----------------------------------+
|
||||
|
||||
The name of the sending peer enables the receiving peer to identify
|
||||
the sender of the UDP packet. This is followed by the meta data and
|
||||
a payload for one or more captured frames. The router will perform batching
|
||||
if it captures several frames very quickly which all need forwarding to
|
||||
the same peer. And in this instance, it will fit as many frames as possible into a single
|
||||
UDP packet.
|
||||
|
||||
The meta data for each frame contains the names of the capturing and
|
||||
the destination peers. Since the name of the capturing peer is
|
||||
associated with the source MAC of the captured payload, it allows
|
||||
receiving peers to build up their mappings of which client MAC
|
||||
addresses are local to which peers.
|
||||
|
||||
The destination peer name enables the receiving peer to identify whether this frame is destined for
|
||||
itself or whether it should be forwarded on to some other peer, and
|
||||
accommodate multi-hop routing. This works even when the receiving
|
||||
intermediate peer has no knowledge of the destination MAC: only the
|
||||
original capturing peer needs to determine the destination peer from
|
||||
the MAC. In this way Weave peers never need to exchange the MAC addresses
|
||||
of clients and need not take any special action for ARP traffic and
|
||||
MAC discovery.
|
||||
|
||||
**See Also**
|
||||
|
||||
* [How Weave Net Interprets Network Topology]({{ '/concepts/network-topology' | relative_url }})
|
||||
@@ -0,0 +1,9 @@
|
||||
graph weave {
|
||||
rankdir=LR;
|
||||
"peer 1" -- "peer 2" ;
|
||||
"peer 1" -- "peer 3" ;
|
||||
"peer 2" -- "peer 3" ;
|
||||
"peer 3" -- "peer 4" ;
|
||||
"peer 4" -- "peer 5" ;
|
||||
"peer 3" -- "peer 5" ;
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 9.2 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
Reference in new issue
Block a user