mykola/lux
7
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions

Grammar fixes

Browse source 
Signed-off-by: hax <hax@lainlounge.xyz>
This commit is contained in:
h@x 2025-01-01 14:56:07 +00:00
parent bd15749c24
commit 2174dded49
1 changed files with 23 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
README.md
View file

@ -31,22 +31,19 @@ Lain Uplink eXchange
## Node
Each node receives heartbeats from different hosts, registering their state, name, WAN IP and uptime over Exterior connections. Each host can request information about other host only over interior connection. The state must be kept same across all nodes, so fail-over can be configured.
Node can also provide DNS server front-end for ease integration into DNS resolvers such as unbound, dnsmasq or systemd-resolved.
Each node receives heartbeats from various hosts and registers their status, name, WAN IP and operating time via external connections. Each host can only query information about other hosts via internal connections. The status must remain the same for all nodes so that a failover can be configured.
The node can also provide a DNS server front-end for easy integration with DNS resolvers such as unbound, dnsmasq or systemd-resolved.
## Exterior and Interior
Exterior connections are made over low-trust medium, such as WAN internet, therefore encryption layer must protect from replay attacks and ensure unique packets.
Interior connections are made over high-trust medium, like VPN tunnels, such as OpenVPN or Tailscale. Only interior connection can be used to sync state between nodes.
An external connection is made via a medium with low trustworthiness, e.g. the WAN Internet, which is why the encryption layer protects against replay attacks and ensures the uniqueness of the packets.
Internal connections are established via a medium with high trustworthiness, e.g. VPN tunnels such as OpenVPN or Tailscale. Only internal connections can be used to synchronize the status between the nodes.
## Host
Each host "heartbeats" it's state - such as WAN IP, uptime, resource usage. Host can heartbeat over exterior and interior connections, but information request can only be made through interior, and state must be synced only over interior, since, at moment of request or sync, the exterior uplink information, such as WAN IP, may not be availble, thus, interior connection must be always available and low-cost.
Each host sends a heartbeat and thus transmits its status - such as WAN IP, operating time, resource utilization. Hosts can send a heartbeat via external and internal connections, but the information request can only be made via internal connections, and the status can only be synchronized via internal connections, because at the time of the request or synchronization, the external uplink information, such as the WAN IP, may not be read out; therefore, the internal connection must always be available and cost-effective.
## State
@ -54,43 +51,42 @@ Host's state consists of:
- Hostname(+.lux)
- WAN IP
Node's state is table of hosts' states + their last heartbeat time.
Node state must also include generation ID, which must be guaranteed to be unique in scope of last 128 generations.
A new generation should only happen when any of the hosts has new heartbeat.
The state of the node is a table of the states of the hosts + their last heartbeat time.
The state of the node must also contain the generation ID, which must be guaranteed to be unique within the last 128 generations.
A new generation should only take place if one of the hosts has a new heartbeat.
## Sync state broadcast
When consensus met state must be synchronized across all nodes. In order to that happen, neighbor nodes must be discovered.
Once consensus has been reached, the state must be synchronized across all nodes. To achieve this, neighbouring nodes must be recognized and registered.
The broadcast procedure is follow.
1. List of neighbor list must be already established (through neighbor discovery)
2. Sync packet formed including the list of nodes it's targeted to: all neighbor (excluding broadcasting node)
3. Send sync packet over interior connections to all nodes
4. In order for broadcast to not loop and be short, each node, on sync packet arrival, must
- Merge it's neighbor list - that way neighbor discovery will also happen, update node neighbor list and/or add new nodes to broadcast
- Remember generation ID of sync packet and ignore any other sync packets with same generation ID.
The sending process is as follows.
1. the list of neighbors must already be created (through neighbor discovery)
2. the sync packet is formed and contains the list of nodes to which it is addressed: all neighbors (except the sending node)
3. the sync packet is sent to all nodes via internal connections
4. so that the transmission does not end in a loop and is short, each node must merge its neighbor list when the sync packet arrives - in this way, neighbor discovery will also take place, update the node's neighbor list and/or add new nodes to the broadcast
- remember the generation ID of the sync packet and ignore all other sync packets with the same generation ID.
This procedure will cause tolerable amount of packet storm, but it will also serve good purpose of re-sending packet if previous was dropped on network path
This procedure will cause a tolerable but still good amount of packet storms, but it will also serve to resend packets if they are lost on the network path.
# Encryption
For host-to-node and node-to-node communication AES-256 symmetric cipher is used.
The symmetric cipher AES-256 is used for communication from host to node and from node to node.
Each node has node key, and for each host node stores host key. The host must be configured with its host key, provided by node.
Each node has a node key and the node stores the host key for each host. The host must be configured with its host key, which is provided by the node.
Node key is used only for node-to-node and must be kept private, unless another node is being deployed.
The node key is only used for node-to-node communication and must be kept secret unless another node is used.
# Identification
Each host and each node has its own unique UUID that is used in packet addressing.
Each host and each node has its own unique UUID, which is used for packet addressing.
## Software architecture
- Config are INI files.
- Daemon, that constantly runs and serves protocol. Also provides UNIX socket for cli configuration
- CLI to communicate with UNIX socket and issue commands
- Config are defined as INI files.
- Daemon that runs continuously and operates the protocol. Also provides a UNIX socket for the CLI configuration
- CLI for communication with UNIX socket and for issuing commands