Add details to doc (#569)

README.md

@@ -84,7 +84,7 @@ hostname and the community name optionally can be encrypted applying `-H` on the
 
 ## Advanced Configuration
 
-More information about communities, routing, traffic restrictions and on how to run an edge as 
+More information about communities, support for multiple supernodes, routing, traffic restrictions and on how to run an edge as 
 a service is available in the [more detailed documentation](doc/Advanced.md).
 
 

doc/Advanced.md

@@ -18,6 +18,10 @@ starting it with `sudo systemctl start edge@instance1`.
 You might be interested to learn some [details about Communities](Communities.md) and understand how to limit supernodes' services to only a specified set of communities.
 
 
+## Federation
+
+It is available a special community which provides interconnection between supernodes. Details about how it works and how you can use it are available in [Federation](Federation.md).
+
 ## Virtual Network Device Configuration
 
 The [TAP Configuration Guide](TapConfiguration.md) contains hints on various settings that can be applied to the virtual network device, including IPv6 addresses as well as notes on MTU and on how to draw IP addresses from DHCP servers.

doc/Federation.md

@@ -1,9 +1,7 @@
 # Supernode Federation
 
 ## Idea
-Supernodes should be able to communicate each other as regular edges already do. For this purpose it has been created a special community, called **federation**. Supernodes inside the federation then are able to do any action an edge inside a regular community can perform. 
+To enhance resilience in terms of backup and fail-over, also for load-balancing, multiple supernodes can easily interconnect and form a special community, called **federation**.
-
-Federation provides mechanisms to connect the supernodes of the network, as backup, fail-over and for load-sharing, without any visible behavioral change. 
 
 
 ## Using Multiple Supernodes
@@ -13,8 +11,6 @@ To form a federation, multiple supernodes need to be aware of each other. To get
 
 This option takes the IP address (or name) and the UDP port of a known supernode (e.g., `-l <192.168.1.1:1234>`) and connect to it.
 
-The default name for the federation is `*Federation`. There is a special character at the beginning of the name: that way, an edge won't be able to provide a regular community with the same name of the federation. Optionally, a user can choose a federation name (same on all supernodes) and provide it via `-F` option at the supernode. 
-
 ### Use a Federation
 Supernodes that are part of the federation take care of the knowledge about other supernodes get propagated to the edges. 
 So, edges only need to connect to one supernode (called anchor supernode), using `-l` option, although that supernode needs to be present at start-up. 
@@ -22,10 +18,18 @@ So, edges only need to connect to one supernode (called anchor supernode), using
 Optionally, more anchor supernodes from the same federation using several `-l` options can be provided an edge to counter a scenario in which initial supernode availability is less assured. 
 
 ## How It Works
+Supernodes should be able to communicate each other as regular edges already do. For this purpose it has been created a special community, called federation. Supernodes inside the federation then are able to do any action an edge inside a regular community can perform. 
+
+Federation provides mechanisms to connect the supernodes of the network, and enhance backup, fail-over and load-sharing, without any visible behavioral change. 
+
+The default name for the federation is `*Federation`. There is a special character at the beginning of the name: that way, an edge won't be able to provide a regular community with the same name of the federation. Optionally, a user can choose a federation name (same on all supernodes) and provide it via `-F` option at the supernode. 
+
 Federated supernodes register to each other using REGISTER_SUPER message type. The answer, REGISTER_SUPER_ACK, contains a payload with informations about other supernodes in the network.
 
-This specific mechanism is used also during the registration between edges and supernodes, so that way edges are able to learn about other supernodes. 
+This specific mechanism is used also during the registration between edges and supernodes, so that way edges are able to learn about other supernodes.
 
-Edges save the informations in a specific list and ping the supernodes time to time. Then, they gather information about supernodes' workload and, on that basis, they decide to which one to connect. 
+Once edges have saved those informations, it is up to them choosing the supernode they want to connect. Each edge pings supernodes from time to time and receives information about them inside the answer. We decided to implement a work-load based selection strategy because it is more in line with the idea of keeping the workload low on supernodes. Moreover, that way the entire load of the network is distributed evenly on all available supernodes.
+
+An edge connects to the supernode with the lowest work-load and it is re-considered from time to time, with each re-registration. We used a stickyness factor to avoid too much jumping between supernodes.
 
 Thanks to this last feature, n2n is now able to handle security attacks (e.g., DoS against supernodes) and it can redistribute the entire load of the network in a fair manner between all the supernodes.