Reticulum/docs/source/networks.rst

.. _networks-main:

*****************
Building Networks
*****************

This chapter will provide you with the knowledge needed to build networks with
Reticulum, which can often be easier than using traditional stacks, since you
don't have to worry about coordinating addresses, subnets and routing for an
entire network that you might not know how will evolve in the future. With
Reticulum, you can simply add more segments to your network when it becomes
necesarry, and Reticulum will handle the convergence of the entire network
automatically.

Concepts & Overview
--------------------

There are important points that need to be kept in mind when building networks
with Reticulum:

 * | In a Reticulum network, any node can autonomously generate as many adresses
     (called *destinations* in Reticulum terminology) as it needs, which become
     globally reachable to the rest of the network. There is no central point of
     control over the adress space.

 * | Reticulum was designed to handle both very small, and very large networks.
     While the adress space can support billions of endpoints, Reticulum is
     also very useful when just a few devices needs to communicate.

 * | Reticulum provides sender/initiator anonymity by default. There is no way
     to filter traffic or discriminate it based on the source of the traffic.

 * | All traffic is encrypted using ephemeral keys generated by an Elliptic Curve
     Diffie-Hellman key exchange on Curve25519. There is no way to inspect traffic
     contents, and no way to prioritise or throttle certain kinds of traffic.
     All transport and routing layers are thus completely agnostic to traffic type,
     and will pass all traffic equally.

 * | Reticulum can function both with and without infrastructure. When *transport
     nodes* are available, they can route traffic over multiple hops for other
     nodes, and will function as a distributed cryptographic keystore. When there
     is no transport nodes available, all nodes that are within communication range
     can still communicate.

 * | Every node can become a transport node, simply by enabling it in it's
     configuration, but there is no need for every node on the network to be a
     transport node. Letting every node be a transport node will in most cases
     degrade the performance and reliability of the network.

     In general terms, if a node is stationary, well-connected and kept running
     most of the time, it is a good candidate to be a transport node. For optimal
     performance, a network should contain the amount of transport nodes that
     provides connectivity to the intended area / topography, and not many more
     than that. 


Reticulum allows you to mix very different kinds of networking mediums into a
unified mesh, or to keep everything within one medium. You could build a "virtual
network" running entirely over the Internet, where all nodes communicate over TCP
and UDP "channels". You could also build such a network using MQTT or ZeroMQ as
the underlying carrier for Reticulum.

However, most real-world networks will probably involve either some form of
wireless or direct hardline communications. To allow Reticulum to communicate
over any type of medium, you must specify it in the configuration file, by default
located at ``~/.reticulum/config``.

Any number of interfaces can be configured, and Reticulum will automatically
decide which are suitable to use in any given situation, depending on where
traffic needs to flow.

Example Scenarios
-----------------

This section illustrates a few example scenarios, and how they would, in general
terms, be planned, implemented and configured.

Interconnected LoRa Sites
=========================

An organisation wants to provide communication and information services to it's
members, which are located mainly in three separate areas. Three suitable hill-top
locations are found, where the organisation can install equipment: Site A, B and C.

Since the amount of data that needs to be exchanged between users is mainly text-
based, the bandwidth requirements are low, and LoRa radios are chosen to connect
users to the network.

Due to the hill-top locations found, there is radio line-of-sight between site A
and B, and also between site B and C. Because of this, the organisation does not
need to use the Internet to interconnect the sites, but purchases four Point-to-Point
WiFi based radios for interconnecting the sites.

At each site, a Raspberry Pi is installed to function as a gateway. A LoRa radio
is connected to the Pi with a USB cable, and the WiFi radio is connected to the
ethernet port of the Pi. At site B, two WiFi radios are needed to be able to reach
both site A and site C, so an extra ethernet adapter is connected to the Pi in
this location.

Once the hardware has been installed, Reticulum is installed on all the Pis, and at
site A and C, one interface is added for the LoRa radio, as well as one for the WiFi
radio. At site B, an interface for the LoRa radio, and one interface for each WiFi
radio is added to the Reticulum configuration file. The transport node option is
enabled in the configuration of all three gateways.

The network is now operational, and ready to serve users across all three areas.
The organisation prepares a LoRa radio that is supplied to the end users, along
with a Reticulum configuration file, that contains the right parameters for
communicating with the LoRa radios installed at the gateway sites.

Once users connect to the network, anyone will be able to communicate with anyone
else across all three sites.

Bridging Over the Internet
==========================

As the organisation grows, several new communities form in places too far away
from the core network to be reachable over WiFi links. New gateways similar to those
previously installed are set up for the new communities at the new sites D and E, but
they are islanded from the core network, and only serve the local users.

After investigating the options, it is found that it is possible to install an
Internet connection at site A, and an interface on the Internet connection is
configured for Reticulum on the Raspberry Pi at site A.

A member of the organisation at site D, named Dori, is willing to help by sharing
the Internet connection she already has in her home, and is able to leave a Raspberry
Pi running. A new Reticulum interface is configured on her Pi, connecting to the newly
enabled Internet interface on the gateway at site A. Dori is now connected to both
all the nodes at her own local site (through the hill-top LoRa gateway), and all the
combined users of sites A, B and C. She then enables transport on her node, and
traffic from site D can now reach everyone at site A, B and C, and vice versa.

Growth and Convergence
======================

As the organisation grows, more gateways are added to keep up with the growing user
base. Some local gateways even add VHF radios and packet modems to reach outlying users
and communities that are out of reach for the LoRa radios and WiFi backhauls.

As more sites, gateways and users are connected, the amount of coordination required
is kept to a minimum. If one community wants to add connectivity to the next one
over, it can simply be done without having to involve everyone or coordinate address
space or routing tables.

With the added geographical coverage, the operators at site A one day find that
the original internet bridged interfaces are no longer utilised. The network has
converged to be completely self-connected, and the sites that were once poorly
connected outliers are now an integral part of the network.