Several Orchestra servers can be connected together to share the same knowledge space.
Each Entity is identifyied by an EUID, which is made of three parts: <NID|HID|UID>.
The NID is the Network Identifyer, which indicates which Orchestra network the entity is in.
The HID is the Host Identifyer, which indicates which host (Orchestra server) in that Orchestra network the entity is in.
The UID is the Unique Identifyer, which indicates which entity of that host of that Orchestra network the entity is.
The combinaison of NID and HID uniquely identifies the Orchestra server in charge of the entity. If a server receives a request about an entity that server is not in charge of, then it will route the request to the correct server and return its answer. This mechanism allows anyone to interract with any entity on any server without having to worry about whether the entity does reside on that particular server or not.
How an Orchestra server manages to route a request about an entity to the server managing that entity is deterined by the addressing mode.
¶ Addressing mode
The Addressing mode determines how an Orchestra server will route to other servers of the network when inquired about an entity that does not reside locally.
It is set via the avu command routing (see "help routing")
Here are the different routing mode:
¶ Physical
Physical addressing (the default) simply interprets the NID and HID as 32-bit unsigned IP addresses. The entity ID for Orchestra.net, for example, would be <2907014155|2907014155|0>. Physical addressing is the most efficient, but if ever a server’s IP were to change, all of its entity identifiers would be invalid.
This works perfectly fine for standalone because the null entity <0|0|0> is interpreted as the local server. However Logical is the recommanded mode for non-standalone server.
¶ Logical
Logical addressing uses network and host tables to map logical NIDs and HIDs to physical IP addresses. Servers have an extra step to go through, but presumably the extra effort is worth not having chunks of the knowledge space blown away simply due to an IP address change. If the IP address of a server change, we just need to update the host table to map its logical NID and HID to its new physical IP address.
¶ Virtual
Virtual is similar to Logical, except that instead of using IP addresses in the network/host tables, domain names are used (e.g. avesterra.net). Unfortunately, not all hosts on the Internet, nor hosts of local area networks have accessible domain names, therefore using Logical is more common.
¶ Network
Orchestra servers are groupped by network, behind the same NID.
In logical and virtual mode, it would be impossible for servers to maintain a mapping of every single Orchestra server's IP address and their unique NIDxHID combinaison. Instead, the servers have a list of one Orchestra server per network (per NID), and the list of all hosts of their current network.
An Orchestra server can be a Gateway.
¶ Gateway
A gateway is an Orchestra server that is able to route traffic to another network by looking up the IP on its network table, or to a certain host within its network by looking up the IP on its host table.
If an Orchestra server needs to forward traffic to a server in another Orchestra network, it needs to either have a reachable gateway of that Orchestra network in its network table, or to have a gateway that can do that work for it.
If an Orchestra server needs to forward traffic to a server in another Orchestra host within the same network, it needs to either have it in its host table, or have a gateway that knows that host.
Usually, every Orchestra server on a same network know about all of the other host of the network, so they can talk to them directly, and every Orchestra network has one server that acts as a gateway to route traffic in to that network and out to other networks.
Here is an example of how HGTP request routing works:
Imagine a client connects to the server <550|2|0> and invokes the entity <2300|5|100432>. That entity resides on the server <2300|5|0>.
The entity resides on a different network than <550|2|0>, in our case, <550|2|0> does not have a network table, so it forwards the request to its network's gateway: <550|4|0>.
Then, <550|4|0> looks in its network table and forward the request to the gateway it knows for the network NID=2300, which is <2300|1|0>.
Then, <2300|1|0> needs to forward to a server on the same network, it looks at its host table and forwards the request to <2300|5|0>.
Finally, <2300|5|0> is able to answer the invoke on <2300|5|100432>, and the response is forwarded back all the way to the original client.
¶ Setting up an Orchestra network
For each Orchestra server, there are 3 configuration steps to setup its networking.
If not done, the default configuration is that the server is standalone, not aware to any other server.
These three steps are:
- Configure - sets up the addressing mode
- networks - sets up the network table (usually only done in one server per network, which will be the gateway of that network)
- hosts - sets up the host table
Even though it is possible to do everything from the avu or through other means, the standard way of doing things is to record the avu commands in the files Local/configure.txt, Local/networks.txt and Local/hosts.txt respectively. The reason for doing so is that even if the data of the Orchestra server is wiped clean, it is very easy to execute these scripts with the avu to setup the networking again.
Note: If you just want to add a new host in an existing network, you only already know the NID of the network and you can simply add the new host
To be able to configure a server, you first need to know what NID to use. There are two scenarios:
- You want to be connected to the global knowledge space, therefore you need to have a unique NID. J Smart's is the de facto coordinator of the global knowledge space, and he can attribute you a NID. For example, LEDR's NID is 1000.
- You want a standalone network that will never be connected to the global knowledge space. In that case, nobody from outside your network can talk to you, therefore you don't need a NID. You NID is simply
0.
Now that you know the NID of your network, The network administrator (you) can manually attribute the HID to all of the servers of the network, and ensure each is unique. HID can be any number greater than 0.
Usually, the first server is <NID|1|0>, then <NID|2|0>, <NID|3|0> etc...
Now that you know the NID and HID of all of your servers, you can start configuring them.
Note that we assume all servers have static IP available through the public internet
¶ Step 1 - Setup the Addressing mode
In our case, it is recommanded to set the mode to Virtual.
see [Addressing mode](#Addressing mode).
assuming NID=1000
example of Local/configure.txt:
root
routing "LOGICAL" <1000|2|0> <1000|1|0>
where <1000|2|0> is the EUID of the server, and <1000|1|0> is the EUID of the gateway.
The gateway can be any server of the network, conventionnaly it is the server of HID 1, but any HID works.
the Local/configure.txt script can be executed with the avu with the configure command in older version of avu, or the @configure command in newer version.
¶ Step 2 - Setup the network table
WARNING: This section is innacurate, the commands don't work as-is, however the general concepts are still valid.
This step is only necessary for the gateway of the network.
example of Local/networks.txt:
root
network "2907014155" <1|1|0>
network "583772649" <1000|1|0>
see help network
The number between quote is the decimal representation of the IP address of the remote server, which can be obtained with tools such as https://dnschecker.org/ip-to-decimal.php
2907014155 is the decimal representation of avesterra.net (173.69.132.11)
583772649 is the decimal representation of gw.ledr.io (34.203.169.233)
You are free to chose which other Orchestra network you will be able to route to. It is not clear how we're supposed to keep that list up to date, nor how to find the list of existing Orchestra networks.
By default, we don't trust the server of our network table. 2
The Local/networks.txt script can be executed with the avu with the networks command in older version of avu, or the @networks command in newer version.
¶ Step 3 - Setup the host table
This is usually done for every server of the network, and every server of the network can have a copy of the same file.
assuming NID=1000
example of Local/hosts.txt:
root
host "657188174" <1000|1|0> TRUE
host "2787486030" <1000|2|0> TRUE
host "3952468123" <1000|3|0> TRUE
see help host
Similar to when setting up networks, the number between quote is the decimal representation of the IP address of the server. The second argument is the EUID of the server in question. The last argument TRUE indicates that we trust that server.
The Local/hosts.txt script can be executed with the avu with the hosts command in older version of avu, or the @hosts command in newer version.
¶ HGTP Tunneling
HGTP Tunneling is used to register a host server that either does not have a static IP address or whose IP address is not available through the open internet (port 20057 is closed, there are multiple servers behind a NAT, ...).
The trick is that instead of knowing the IP address of that server and open a connection to it if we need to talk, we do the opposite. Instead of registring the IP address for that host, the gateway (here called 'server') will register an 'HGTP Portal' for that host. The appliance (the server whose IP is dynamic/inaccesible from the internet) can connect to that portal by open a connection with the server. The connection is called a Tunnel. As long as that connection is open, the server can forward any traffic through it without having to initiate a TLS connection to the appliance, which may not be reachable through the internet.
Each portal has an authority, which is an authorization code a server needs to open a tunnel to that portal.
Generally, a server opens multiple tunnels to a portal to be able to handle multiple in/out requests at the same time. Whenever a tunnel connection breaks, because the appliance changes network or anything, the tunnel will try to reconnect after a certain timeout. Because tunnels are entities, they are persistent on server reboot, and therefore will automatically try to reconnect to their portal if the server restarts.
¶ Trust
By default, when adding a server to the network or host table, it makes the server able to forward traffic to these servers, but it "foreign" (opposite of "trusted").
If a server is foreign, only transactions with NULL or public authorizations can be transmitted.
Since 2024-02, there are "coupling" and "pairing" operation that provide improvement on these limitations.
TODO: understand that
The general idea is that a server would maintain a mapping table of "internal" to "external" authorization for each server they may route requests to. Before routing an HGTP request to another server, the server may swap out the "internal" authorization to the "external" authorization.
