Repository : ssh://git@diktynna/doc

On branches: backup-redmine/2020-07-12,master

commit f048cd93cc0376fec3d9c1878f58a9c5960ae44a Author: Sven Eckelmann sven@narfation.org Date: Sat Jun 20 22:24:04 2020 +0000

doc: alfred/Alfred_architecture

f048cd93cc0376fec3d9c1878f58a9c5960ae44a alfred/Alfred_architecture.textile | 54 +++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 27 deletions(-)

diff --git a/alfred/Alfred_architecture.textile b/alfred/Alfred_architecture.textile index f735d1f..aba3b83 100644 --- a/alfred/Alfred_architecture.textile +++ b/alfred/Alfred_architecture.textile @@ -15,8 +15,8 @@ h2. Alfred specific terms | node | a node is a device able to run alfred | | server | an alfred instance running on a node, able to communicate with alfred processes on other nodes and with clients running on the same node | | client | a program which supports the alfred protocol and communicates with the alfred server on the same node | -| master | an alfred server process which stores incoming data, synchronizes it with other master servers and accepts requests/data from slaves | -| slave | an alfred server process which only manages its own data, pushes/requests the data to/from *its* master server | +| primary | an alfred server process which stores incoming data, synchronizes it with other primary servers and accepts requests/data from secondaries | +| secondary | an alfred server process which only manages its own data, pushes/requests the data to/from *its* primary server |

h2. Network

@@ -26,9 +26,9 @@ An alfred network used for exchanging data is built using different nodes runnin

!general_structure.png!

-Such a network has to contain at least one master server. Master servers are used as global data storage and help to synchronize data with other nodes. This role is so important that they actively announce there presence to all nodes. Other master servers are automatically synchronizing their stored data to have it distributed to all reachable master nodes. +Such a network has to contain at least one primary server. Primary servers are used as global data storage and help to synchronize data with other nodes. This role is so important that they actively announce there presence to all nodes. Other primary servers are automatically synchronizing their stored data to have it distributed to all reachable primary nodes.

-The second type of servers are slaves. Slaves don't try to gather all data stored in the alfred network. Instead they only connect to their best master server to request data when required and to push the data from local clients to the alfred network through master servers. +The second type of servers are secondaries. Secondaries don't try to gather all data stored in the alfred network. Instead they only connect to their best primary server to request data when required and to push the data from local clients to the alfred network through primary servers.

h3. Network layer

@@ -40,17 +40,17 @@ All the messages are sent through the IANA unregistered UDP/IPv6 port 0x4242 (in

h3. Detection of neighbors

-The master server will announce itself using IPv6 link-local multicast messages. This makes it possible to reach all nodes with a single message unless it is dropped while being forwarded/transmitted. +The primary server will announce itself using IPv6 link-local multicast messages. This makes it possible to reach all nodes with a single message unless it is dropped while being forwarded/transmitted.

-!announce_master.png! +!announce_primary.png!

-The periodically (10s) transmitted announcement multicast messages will be received by the other alfred servers and be store for later. Master servers use this information to synchronize data and slave servers use it to have access to the global data. +The periodically (10s) transmitted announcement multicast messages will be received by the other alfred servers and be store for later. Primary servers use this information to synchronize data and secondary servers use it to have access to the global data.

-!master_selection.png! +!primary_selection.png!

-The slave servers need therefore a way to find their best master server. The current strategy for non-batman-adv server is to choose one server randomly and and don't use an extra metric. But batman-adv networks already provide the TQ value to quantify the quality to a master server. The best master server is just the server with the best TQ for a slave node. +The secondary servers need therefore a way to find their best primary server. The current strategy for non-batman-adv server is to choose one server randomly and and don't use an extra metric. But batman-adv networks already provide the TQ value to quantify the quality to a primary server. The best primary server is the server with the best TQ for a secondary node.

-The mac address is used by alfred to associate the messages with an unique data source. It is calculated by evaluating the received UDP/IPv6 packet source address. This mac address can then be used to retrieve the master server TQ from the batman-adv debug tables. +The mac address is used by alfred to associate the messages with an unique data source. It is calculated by evaluating the received UDP/IPv6 packet source address. This mac address can then be used to retrieve the primary server TQ from the batman-adv debug tables.

Detected neighbor servers are automatically dropped after a timeout of 60s since the last announcement was received.

@@ -60,29 +60,29 @@ The client communication to the alfred server is done through unix sockets on th

The used packet format is shared between the server2server and the client2server communication. There are some minor differences which will be explained later.

-The easiest communication is the push of data to an server. The client just has to create a <code>alfred_push_data</code> packet with the attached data at the end. The server receives it, stores it, closes the client connection and handles the forwarding of the data to the other servers in the alfred network. +The easiest communication is the push of data to an server. The client has to create a <code>alfred_push_data</code> packet with the attached data at the end. The server receives it, stores it, closes the client connection and handles the forwarding of the data to the other servers in the alfred network.

-Slightly more complicated is the request of data from a master server. The client has to send an <code>alfred_request</code> packet to the master server with the type it requests. The reply will be an arbitrary number of <code>alfred_push_data</code> packets of the requested type which contain the data set by the clients on this node and from other nodes. The data from other servers will only be as new as the latest successful data synchronization. +Slightly more complicated is the request of data from a primary server. The client has to send an <code>alfred_request</code> packet to the primary server with the type it requests. The reply will be an arbitrary number of <code>alfred_push_data</code> packets of the requested type which contain the data set by the clients on this node and from other nodes. The data from other servers will only be as new as the latest successful data synchronization.

-!node_architecture_master.png! +!node_architecture_primary.png!

-The alfred request to an slave server looks exactly the same as the request to a master server. But the slave server doesn't store all data which is currently in the alfred network. Instead the slave server has to ask its master server to send information for this type to the slave server. This is done the same way as a client would do it but through a link-local UDP/IPv6 message. The request will be replied by the server with <code>alfred_push_data</code> packets and a single <code>alfred_status</code> end packet containing the number of sent <code>alfred_push_data</code> packets. +The alfred request to an secondary server looks exactly the same as the request to a primary server. But the secondary server doesn't store all data which is currently in the alfred network. Instead the secondary server has to ask its primary server to send information for this type to the secondary server. This is done the same way as a client would do it but through a link-local UDP/IPv6 message. The request will be replied by the server with <code>alfred_push_data</code> packets and a single <code>alfred_status</code> end packet containing the number of sent <code>alfred_push_data</code> packets.

-This request can obviously fail for different reasons. The slave server uses an timeout (10s) for these requests and informs the client using an <code>alfred_packet_status</code> error message that the request failed. Otherwise the slave server will reply with <code>alfred_push_data</code> packets the same way as a master server. +This request can fail for different reasons. The secondary server uses an timeout (10s) for these requests and informs the client using an <code>alfred_packet_status</code> error message that the request failed. Otherwise the secondary server will reply with <code>alfred_push_data</code> packets the same way as a primary server.

-!node_architecture_slave.png! +!node_architecture_secondary.png!

-The best practice for a client is to implement the handling of error messages even when it is only used together with master servers. +The best practice for a client is to implement the handling of error messages even when it is only used together with primary servers.

h3. Synchronization

-Data synchronizations are done master2master and slave2master. The slave will only send data from its clients to a single server. Master servers are sending their stored data to all other known master servers. This only contains the data from their local clients and data pushed from slave server. +Data synchronizations are done primary2primary and secondary2primary. The secondary will only send data from its clients to a single server. Primary servers are sending their stored data to all other known primary servers. This only contains the data from their local clients and data pushed from secondary server.

!synchronization.png!

-The synchronization is started pro-actively by the slave or master server every 10s. It is initiated by an <code>alfred_push_data</code> packet with a transaction id and the first data blocks. This transaction id should be unique for the time of the synchronization but the same for all packets of a synchronization transaction. +The synchronization is started pro-actively by the secondary or primary server every 10s. It is initiated by an <code>alfred_push_data</code> packet with a transaction id and the first data blocks. This transaction id should be unique for the time of the synchronization but the same for all packets of a synchronization transaction.

-The last packet is an <code>alfred_status</code> end packet with the number of sent <code>alfred_push_data</code> packets during this synchronization transaction. If it doesn't match with the number of packets the master server received, then the transaction failed and the remote master server drops the received data. +The last packet is an <code>alfred_status</code> end packet with the number of sent <code>alfred_push_data</code> packets during this synchronization transaction. If it doesn't match with the number of packets the primary server received, then the transaction failed and the remote primary server drops the received data.

Data is automatically pruned from the server storage 600s after the last time it was received/refreshed.

@@ -90,23 +90,23 @@ h2. Packet formats

h3. General format

-The data stored in the packet headers is always stored in network byte order (big endian). The packet format is TLV based (type, value, length) which appears in different headers. The type is only defined by alfred for the outer TLV and can be <code>PUSH_DATA(0)</code>, <code>ANNOUNCE_MASTER(1)</code>, <code>REQUEST(2)</code>, <code>STATUS_TXEND(3)</code>, <code>STATUS_ERROR(4)</code>. The only special type is <code>MODESWITCH(5)</code> which is used internally to switch a server between master and slave mode. +The data stored in the packet headers is always stored in network byte order (big endian). The packet format is TLV based (type, value, length) which appears in different headers. The type is only defined by alfred for the outer TLV and can be <code>PUSH_DATA(0)</code>, <code>ANNOUNCE_PRIMARY(1)</code>, <code>REQUEST(2)</code>, <code>STATUS_TXEND(3)</code>, <code>STATUS_ERROR(4)</code>. The only special type is <code>MODESWITCH(5)</code> which is used internally to switch a server between primary and secondary mode.

The length value is always the length of the payload following the TLV. This is especially important when multiple TLV + payload blocks appear after each other.

The version field is also only defined for the outer TLV and has to be 0 for the specified first packet format.

-h3. Master announcement +h3. Primary announcement

-!packet_announce_master_v0.png! +!packet_announce_primary_v0.png!

-The announcement is only done by the master servers to announce themselves via link-local UDP/IPv6 multicast. It doesn't contain any more information. The receiver has to calculate the mac address of the sender by decoding the link-local IPv6 sender address. +The announcement is only done by the primary servers to announce themselves via link-local UDP/IPv6 multicast. It doesn't contain any more information. The receiver has to calculate the mac address of the sender by decoding the link-local IPv6 sender address.

h3. Request data

!packet_request_v0.png!

-Requests are done by clients via unix socket or by slave servers via link-local UDP/IPv6 unicast. +Requests are done by clients via unix socket or by secondary servers via link-local UDP/IPv6 unicast.

The requested type is the type of data which the transmitter wants to receive. The <code>alfred_push_data packets</code> sent as reply must only contain data blocks from this type.

@@ -120,7 +120,7 @@ Servers send status end packets via link-local UDP/IPv6 unicast. It is the last

h3. Inform about an error

-Slave servers send error messages via unix sockets to clients. This tells the client that the request of data from the master server failed. The transaction id has to be same as the transaction id of the <code>alfred_request</code> packet. +Secondary servers send error messages via unix sockets to clients. This tells the client that the request of data from the primary server failed. The transaction id has to be same as the transaction id of the <code>alfred_request</code> packet.

!packet_status_v0_error.png!

@@ -130,7 +130,7 @@ h3. Push data

Push data packets are sent/received by clients to send data via unix sockets to/from servers. Clients send it to store data on a server. Servers send it to clients as answer to <code>alfred_request</code> packets.

-Servers sent push data packets via UDP/IPv6 to synchronize data between them. Master server also sent them to slave server as answer to <code>alfred_request</code> packets. +Servers sent push data packets via UDP/IPv6 to synchronize data between them. Primary server also sent them to secondary server as answer to <code>alfred_request</code> packets.

The transaction id has to be unique during the time of the transaction but the same for all packets of one transaction. The sequence number has to be increased for each packet of a transaction.