diff --git a/README.md b/README.md index 6b468a7..c7e72a3 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,225 @@ -# lux +# LUX + +Lain Uplink eXchange + +## Problem + +When networking is not bound to static IPs, or some home deployment lacking proper network equipment, Lain Uplink eXchange aims to resolve these issues by providing distributed host information resolution. + +## LUX - The solution + +Nodes are able to discover other nodes by pre-configured neighbors, while holding information about all hosts equally in each host, thus distributed. + +Host information can be anything that is implemented with LuxOption. Current implementation provides a way to determine and encapsulate such information as +- Hostname +- WAN IPv4/IPv6 +- Host's network interfaces + + +While nodes providing convinient way of accessing and managing informaton, such as +- XML RPC +- DNS frontend + +As well capable calling external scripts whenever update of host information. This is primary goal, to be able update IPFW/PF/nftables rules dynamically and/or reconfigure tunnel devices. + +## Layout + +LUX network can be configured as shown here + +``` + [HOST test-laptop] --exterior--> [NODE Linux] + || + || + [NODE DFly BSD]_<-interior->________**________<-interior->_[NODE FreeBSD] + ^ + | + + [NODE OpenBSD] <-exterior-- [HOST openbsd-host] +``` + +## Exterior and Interior + +Exterior channels are used for host to node communication. Interior channels are used for node-to-node sync. Sync packets are big, since they bear all hosts, therefore + +INTERIOR LINK MUST HAVE HIGH MTU OR IP FRAGMENTATION. If this is not done, large packets will be dropped and sync to be lost. + +## Setup + +To begin with, first you need to install appropriate for your platform binary, found in releases. + +Then, you need first, initial node, from which later nodes and hosts will be deducted through RPC commands. + +A LUX node config must look like this + +```xml + + + /var/lux/lux-node.dat + {YOUR ID} + + unix:///var/run/lux-node.sock + 127.0.0.1:9953 + 127.0.0.1:9979 + 10.1.0.254:9979 + 127.0.0.1:9980 + 1 + +``` + +Note that keystore is important file. + +To generate first node keystore and obtain ID, use +```lux --node --config --bootstrap``` + +Then put ID into config. + +## Adding hosts + +Host must be added via node RPC, so node keystore has host key. + +```lux --rpc unix:///var/run/lux-node.sock --rpc-new-host /tmp/host-keystore.dat``` + +Output will show ID of new host that must be used in host config. + +(Currently, the new created keystore in /tmp is useless due to limitations and work-in-progress.) + +Copy node's keystore to host location + +```cp /var/lux/lux-node.dat /var/lux/lux-host.dat``` + +Then, a host must be configured like this + +```xml + + + /var/lux/lux-host.dat + {host ID from rpc-new-host} + acer-laptop + + + 1 + + {NODE'S ID} + {NODE'S EXTERIOR CHANNEL IP:PORT} + + +``` + +## Adding new neighboring nodes + +Procedure is similar to creating host + +```lux --rpc unix:///var/run/lux-node.sock --rpc-new-node /tmp/new-keystore.dat``` + +New keystore must be used in neighbor node config + +New node's config must be configured like this + +```xml + + + /var/lux/new-keystore.dat + {new node ID from RPC output} + + unix:///var/run/lux-neighbor.sock + 127.0.0.1:9953 + 10.1.0.6:9979 + 10.1.0.6:9980 + 1 + + {ID of initial node} +
{exterior IP:Port of initial node}
+ + + +``` + +## Update hook + +Into the node tag of config, a hooks can be added + +```xml + + 48d14b3a-e737-4914-9f14-d9906eebbf82 + + +``` + +Where `````` is ID of the host, and ```