Repository : ssh://git@open-mesh.org/doc

On branch : master

commit 31d78e541dd357ba56d838140b1a401cc1bcd0e7 Author: Sven Eckelmann sven@narfation.org Date: Thu Jul 13 23:17:37 2017 +0200

doc: Cleanup of alfred documentation

Signed-off-by: Sven Eckelmann sven@narfation.org

31d78e541dd357ba56d838140b1a401cc1bcd0e7 alfred/Alfred-gpsd.rst | 1 + alfred/Alfred-output-format-proposal.rst | 7 +- alfred/Alfred.rst | 131 ------------------------------- alfred/Alfred_architecture.rst | 50 ++++++------ alfred/Batadv-vis.rst | 1 + alfred/Building_information.rst | 36 ++++----- alfred/Wiki.rst | 50 ------------ alfred/index.rst | 44 ++++++++++- 8 files changed, 88 insertions(+), 232 deletions(-)

diff --git a/alfred/Alfred-gpsd.rst b/alfred/Alfred-gpsd.rst index 0079490..1bfbbfb 100644 --- a/alfred/Alfred-gpsd.rst +++ b/alfred/Alfred-gpsd.rst @@ -1,3 +1,4 @@ +=========== Alfred-gpsd ===========

diff --git a/alfred/Alfred-output-format-proposal.rst b/alfred/Alfred-output-format-proposal.rst index c86a5ea..302da52 100644 --- a/alfred/Alfred-output-format-proposal.rst +++ b/alfred/Alfred-output-format-proposal.rst @@ -1,3 +1,4 @@ +========================================= Alfred output format enhancement proposal =========================================

@@ -13,7 +14,7 @@ Here's a proposal which aims for the following three key benefits: - Binary data can be inserted, queried and piped on the shell.

Valid UTF8 text only by default -------------------------------- +===============================

*Valid UTF8 text, ASCII, example 1:*

@@ -78,7 +79,7 @@ Simply fail with an error return code and message, example: Invalid UTF8 input! Consider using --binary

Binary mode switch ------------------- +==================

*Store:*

@@ -100,7 +101,7 @@ So '$ alfred -r 64' displays the data in base64 (or some other suitable, json string compatible format).

Namespaces ----------- +==========

*Store:*

diff --git a/alfred/Alfred.rst b/alfred/Alfred.rst deleted file mode 100644 index 81db303..0000000 --- a/alfred/Alfred.rst +++ /dev/null @@ -1,131 +0,0 @@ -A.L.F.R.E.D - Almighty Lightweight Fact Remote Exchange Daemon -============================================================== - -| "alfred is a user space daemon to efficiently[tm] flood the network - with useless data - like vis, weather data, network notes, etc" -| > - Marek Lindner, 2012 - -Introduction ------------- - -alfred is a user space daemon for distributing arbitrary local -information over the mesh/network in a decentralized fashion. This data -can be anything which appears to be useful - originally designed to -replace the batman-adv visualization (vis), you may distribute -hostnames, phone books, administration information, DNS information, the -local weather forecast ... - -Typically, alfred runs as unix daemon in the background of the system. A -user may insert information by using the alfred binary on the command -line, or use custom written programs to communicate with alfred directly -through unix sockets. Once the local data is received, the alfred daemon -takes care of distributing this information to other alfred servers on -other nodes somewhere in the network. As addressing scheme IPv6 -link-local multicast addresses are used which do not require any manual -configuration. A user can request data from alfred, and will receive the -information available from all alfred servers in the network. - -See the -`README https://git.open-mesh.org/alfred.git/blob_plain/refs/heads/master:/README`__ -for more information or the -`manpage https://downloads.open-mesh.org/batman/manpages/alfred.8.html`__ -for usage. - -Further resources ------------------ - -| * alfred slave on android: https://github.com/basros/alfreda -| * Wireshark dissector for alfred: - https://github.com/basros/alfred-dissector -| * [[alfred:alfred architecture|Alfred architecture]] - technical - information about alfred - -Current applications --------------------- - -There are a few applications currently implemented on top of alfred: - -batadv-vis -~~~~~~~~~~ - -batadv-vis can be used to visualize your batman-adv mesh network. It -read the neighbor information and local client table and distributes -this information via alfred in the network. By gathering this local -information, any vis node can get the whole picture of the network. - -It allows output of different formats (json, graphviz) and replaces the -in-kernel vis functionality found in older batman-adv kernel modules -(<2014). See the sample picture below. For more information, please read -the vis section of the -`README https://git.open-mesh.org/alfred.git/blob_plain/refs/heads/master:/README`__ -or the -`manpage https://downloads.open-mesh.org/batman/manpages/batadv-vis.html`__ -for usage. - -|image0| - -alfred-gpsd -~~~~~~~~~~~ - -Alfred-gpsd can be used to distibute GPS location information about your -batman-adv mesh network. This information could be, for example, -combined with Vis to visualize your mesh topology with true geographic -layout. For mobile or nomadic nodes, Alfred-gpsd, can get location -information from gpsd. Alternatively, a static location can be passed on -the command line, which is useful for static nodes without a GPS. - -For more information, please read the alfred-gpsd section of the -`README https://git.open-mesh.org/alfred.git/blob_plain/refs/heads/master:/README`__ -or the -`manpage https://downloads.open-mesh.org/batman/manpages/alfred-gpsd.html`__ -for usage. - -Download --------- - -Release tarballs as well as snapshots are available: - -| * release tarballs: - [[open-mesh:Download#Download-Released-Source-Code|Check the Download - page]] -| * git web directory: https://git.open-mesh.org/alfred.git -| * git download: git clone git://git.open-mesh.org/alfred.git -| * - snapshot:https://git.open-mesh.org/alfred.git/snapshot/refs/heads/master.tar.gz - -OpenWRT installation from routing feed -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Alfred is also part of the routing feed of OpenWRT. For newer OpenWRT, -just use: - -1. Install the alfred package: - -./scripts/feeds install alfred - -3. Run "make menuconfig" and select alfred (available under "Network ---->") - -OpenWRT development feed -~~~~~~~~~~~~~~~~~~~~~~~~ - -There is also a development packet feed for OpenWRT available for -alfred: - -1. add the alfred feed by adding the following line into your -feeds.conf: - -src-git batman git://git.open-mesh.org/openwrt-feed-devel.git - -2. Update and install the feed: - -| ./scripts/feeds update -| ./scripts/feeds install alfred - -3. Run "make menuconfig" and select alfred (available under "Network ---->") - -Finally, re-build Openwrt and enjoy using alfred! :) - -.. |image0| image:: batman-adv-vis-example.png - diff --git a/alfred/Alfred_architecture.rst b/alfred/Alfred_architecture.rst index 26f0a01..c8325e6 100644 --- a/alfred/Alfred_architecture.rst +++ b/alfred/Alfred_architecture.rst @@ -1,8 +1,9 @@ +=================== alfred architecture ===================

Introduction ------------- +============

alfred is a user space daemon for distributing arbitrary local information over the mesh/network in a decentralized fashion. This data @@ -25,19 +26,18 @@ More user related information can be found in the [[alfred:Alfred]] overview page.

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 | -+----------+--------------------------------------------------------------------------------------------------------------------------------------------+ +===================== + +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

Network ------- @@ -64,7 +64,7 @@ best master server to request data when required and to push the data from local clients to the alfred network through master servers.

Network layer -~~~~~~~~~~~~~ +-------------

All communication between servers in an alfred network is done through IPv6 link-local UDP messages. This only allows communication in the @@ -84,7 +84,7 @@ All the messages are sent through the IANA unregistered UDP/IPv6 port 0x4242 (in decimal: 16962).

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 @@ -115,7 +115,7 @@ Detected neighbor servers are automatically dropped after a timeout of 60s since the last announcement was received.

Client data exchange -~~~~~~~~~~~~~~~~~~~~ +--------------------

The client communication to the alfred server is done through unix sockets on the same node. The path is defined as /var/run/alfred.sock @@ -161,7 +161,7 @@ The best practice for a client is to implement the handling of error messages even when it is only used together with master servers.

Synchronization -~~~~~~~~~~~~~~~ +---------------

Data synchronizations are done master2master and slave2master. The slave will only send data from its clients to a single server. Master servers @@ -187,10 +187,10 @@ Data is automatically pruned from the server storage 600s after the last time it was received/refreshed.

Packet formats --------------- +==============

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) @@ -208,7 +208,7 @@ The version field is also only defined for the outer TLV and has to be 0 for the specified first packet format.

Master announcement -~~~~~~~~~~~~~~~~~~~ +-------------------

|image6|

@@ -218,7 +218,7 @@ more information. The receiver has to calculate the mac address of the sender by decoding the link-local IPv6 sender address.

Request data -~~~~~~~~~~~~ +------------

|image7|

@@ -233,7 +233,7 @@ The transaction id must be unique during the time the request is made and answered.

Finish transaction -~~~~~~~~~~~~~~~~~~ +------------------

|image8|

@@ -245,7 +245,7 @@ packets has to be equal to the number of alfred_push_data packets with the same transaction id to accept the transaction as successful.

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. @@ -257,7 +257,7 @@ alfred_request packet. The only currently used error code is 1.

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. diff --git a/alfred/Batadv-vis.rst b/alfred/Batadv-vis.rst index e44869b..64914d2 100644 --- a/alfred/Batadv-vis.rst +++ b/alfred/Batadv-vis.rst @@ -1,3 +1,4 @@ +========== Batadv-vis ==========

diff --git a/alfred/Building_information.rst b/alfred/Building_information.rst index 5a8e441..9ea7d55 100644 --- a/alfred/Building_information.rst +++ b/alfred/Building_information.rst @@ -1,46 +1,44 @@ +==================== Building information ====================

Release tarballs as well as snapshots are available:

-| * release tarballs: +* release tarballs: [[open-mesh:Download#Download-Released-Source-Code|Check the Download page]] -| * git web directory: https://git.open-mesh.org/alfred.git -| * git download: git clone git://git.open-mesh.org/alfred.git -| * - snapshot:https://git.open-mesh.org/alfred.git/snapshot/refs/heads/master.tar.gz +* git web directory: https://git.open-mesh.org/alfred.git +* git download: ``git clone git://git.open-mesh.org/alfred.git`` +* `snapshot https://git.open-mesh.org/alfred.git/snapshot/refs/heads/master.tar.gz`__

OpenWRT installation from routing feed -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +======================================

Alfred is also part of the routing feed of OpenWRT. For newer OpenWRT, just use:

-1. Install the alfred package: +#. Install the alfred package::

-./scripts/feeds install alfred + ./scripts/feeds install alfred

-3. Run "make menuconfig" and select alfred (available under "Network ---->") +#. Run "make menuconfig" and select alfred (available under ``Network --->``)

OpenWRT development feed -~~~~~~~~~~~~~~~~~~~~~~~~ +========================

There is also a development packet feed for OpenWRT available for alfred:

-1. add the alfred feed by adding the following line into your -feeds.conf: +#. add the alfred feed by adding the following line into your + feeds.conf::

-src-git batman git://git.open-mesh.org/openwrt-feed-devel.git + src-git batman git://git.open-mesh.org/openwrt-feed-devel.git

-2. Update and install the feed: +#. Update and install the feed::

-| ./scripts/feeds update -| ./scripts/feeds install alfred + ./scripts/feeds update + ./scripts/feeds install alfred

-3. Run "make menuconfig" and select alfred (available under "Network ---->") +#. Run ``make menuconfig`` and select alfred (available under ``Network --->``)

Finally, re-build Openwrt and enjoy using alfred! :) diff --git a/alfred/Wiki.rst b/alfred/Wiki.rst deleted file mode 100644 index b75e15e..0000000 --- a/alfred/Wiki.rst +++ /dev/null @@ -1,50 +0,0 @@ -A.L.F.R.E.D - Almighty Lightweight Fact Remote Exchange Daemon -============================================================== - -"alfred is a user space daemon to efficiently[tm] flood the network with -useless data - like vis, weather data, network notes, etc" - -- Marek Lindner, 2012 - -alfred is a user space daemon for distributing arbitrary local -information over the mesh/network in a decentralized fashion. This data -can be anything which appears to be useful - originally designed to -replace the batman-adv visualization (vis), you may distribute -hostnames, phone books, administration information, DNS information, the -local weather forecast ... - -Typically, alfred runs as unix daemon in the background of the system. A -user may insert information by using the alfred binary on the command -line, or use custom written programs to communicate with alfred directly -through unix sockets. Once the local data is received, the alfred daemon -takes care of distributing this information to other alfred servers on -other nodes somewhere in the network. As addressing scheme IPv6 -link-local multicast addresses are used which do not require any manual -configuration. A user can request data from alfred, and will receive the -information available from all alfred servers in the network. - -See the -`README https://git.open-mesh.org/alfred.git/blob_plain/refs/heads/master:/README`__ -for more information or the -`manpage https://downloads.open-mesh.org/batman/manpages/alfred.8.html`__ -for usage. - -Getting started ---------------- - -| * [[Building information]] - how to download and build alfred -| * [[batadv-vis]] - Tool to visualize batman-adv networks -| * [[alfred-gpsd]] - Share geolocation of mesh nodes - -Developer information ---------------------- - -* [[Alfred architecture]] - information about topologies, internal -architecture and packet format - -Further resources ------------------ - -| * alfred slave on android: https://github.com/basros/alfreda -| * Wireshark dissector for alfred: - https://github.com/basros/alfred-dissector diff --git a/alfred/index.rst b/alfred/index.rst index e1e3aea..3c5dedf 100644 --- a/alfred/index.rst +++ b/alfred/index.rst @@ -1,13 +1,16 @@ -alfred -====== +A.L.F.R.E.D - Almighty Lightweight Fact Remote Exchange Daemon +============================================================== + + "alfred is a user space daemon to efficiently[tm] flood the network with + useless data - like vis, weather data, network notes, etc" + + - Marek Lindner, 2012

Contents:

.. toctree:: :maxdepth: 2

- Wiki - Alfred gettingstarted developerinformation

@@ -17,3 +20,36 @@ Contents: =======

* :ref:`genindex` + +Introduction +------------ + +alfred is a user space daemon for distributing arbitrary local +information over the mesh/network in a decentralized fashion. This data +can be anything which appears to be useful - originally designed to +replace the batman-adv visualization (vis), you may distribute +hostnames, phone books, administration information, DNS information, the +local weather forecast ... + +Typically, alfred runs as unix daemon in the background of the system. A +user may insert information by using the alfred binary on the command +line, or use custom written programs to communicate with alfred directly +through unix sockets. Once the local data is received, the alfred daemon +takes care of distributing this information to other alfred servers on +other nodes somewhere in the network. As addressing scheme IPv6 +link-local multicast addresses are used which do not require any manual +configuration. A user can request data from alfred, and will receive the +information available from all alfred servers in the network. + +See the +`README https://git.open-mesh.org/alfred.git/blob_plain/refs/heads/master:/README`__ +for more information or the +`manpage https://downloads.open-mesh.org/batman/manpages/alfred.8.html`__ +for usage. + +Further resources +----------------- + +* alfred slave on android: https://github.com/basros/alfreda +* Wireshark dissector for alfred: + https://github.com/basros/alfred-dissector