-
Notifications
You must be signed in to change notification settings - Fork 2
/
README
321 lines (251 loc) · 12.5 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
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 ...
alfred runs as daemon in the background of the system. A user may insert
information by using the alfred binary on the command line, or use special
programs to communicate with alfred (done via unix sockets). alfred then takes
care of distributing the local information to other alfred servers on other
nodes. This is done via IPv6 link-local multicast, and does not require any
configuration. A user can request data from alfred, and will receive the
information available from all alfred servers in the network.
Compilation
-----------
alfred depends on:
* librt (usually part of libc)
* IPv6 support in the kernel/host system
and optionally:
* libgps - if you want to distribute GPS information
* libcap - if you want extra security by dropping unneeded privileges
To compile alfred, simply type:
$ make
This will compile alfred, batadv-vis & alfred-gpsd. To install, use
$ make install
(with the right privileges).
If you don't want to compile batadv-vis, add the directive CONFIG_ALFRED_VIS=n:
$ make CONFIG_ALFRED_VIS=n
$ make CONFIG_ALFRED_VIS=n install
If you don't want to compile alfred-gpsd, add the directive
CONFIG_ALFRED_GPSD=n:
$ make CONFIG_ALFRED_GPSD=n
$ make CONFIG_ALFRED_GPSD=n install
If don't want to compile with libcap to drop privileges, use:
$ make CONFIG_ALFRED_CAPABILITIES=n
$ make CONFIG_ALFRED_CAPABILITIES=n install
Usage
-----
First, alfred must run as daemon (server) in background to be used. This can
either be done by some init-scripts from your distribution (if you have
received alfred as a package with your distribution). Please see their
documentation how to configure alfred in this case. In any event, you can
still run alfred from the command line. The relevant options are (for a full
list of options, run alfred -h):
-i, --interface specify the interface to listen on
-b specify the batman-adv interface configured on
the system (default: bat0). use 'none' to disable
the batman-adv based best server selection
-m, --master start up the daemon in master mode, which
accepts data from slaves and syncs it with
other masters
The -b option is optional, and only needed if you run alfred on a batman-adv
interface not called bat0, or if you don't use batman-adv at all
(use '-b none'). In this case, alfred will still work but will not be able to
find the best next master server based on metrics.
alfred servers may either run as master or slave in the network. Masters will
announce their status via broadcast, so that slaves can find them. Slaves will
then send their data to their nearest master (based on TQ). Masters will
exchange their data (which they have received from slaves or got on their own)
with other masters. By using masters and slaves, overhead can be reduced while
still keeping redundancy (by having multiple masters). Obviously, at least one
master must be present in the network to let any data exchange happen. Also
having all nodes in master mode is possible (for maximum decentrality and
overhead).
To put it together, let us start alfred in master mode on our bridge br0
(assuming that this bridge includes the batman interface bat0):
$ alfred -i br0 -m
Now that the server is running, let us input some data. This can be done by
using the alfred binary in client mode from the command line:
$ cat /etc/hostname | alfred -s 64
This will set the hostname as data for datatype 64. Note that 0 - 63 are
reserved (please send us an e-mail if you want to register a datatype), and can
not be used on the commandline. We skipped the version parameter allowing you
to assign a version to your data which can be filtered by other alfred users.
Skipping the parameter entirely has the same effect as setting the parameter
to 0 ('-V 0').
After the hostname has been set on a few alfred hosts, the can be retrieved again:
$ alfred -r 64
{ "fe:f1:00:00:01:01", "OpenWRT-node-1\x0a" },
{ "fe:f1:00:00:02:01", "OpenWRT-node-2\x0a" },
{ "fe:f1:00:00:03:01", "OpenWRT-node-3\x0a" },
Note that the information must be periodically written again to alfred, otherwise
it will timeout and alfred will forget about it (after 10 minutes).
One final remark on terminology: If we talk about "servers" and "clients" in
alfred, we mean the local processes on one machine which talk to each other via
unix sockets (client connects and talks to servers). On the other hand, "slaves"
and "masters" are the roles alfred can take over in the network between different
machines (slaves send information to masters).
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.
batadv-vis, similar to to alfred, combines server (daemon) and client
functionality in the 'batadv-vis' binary. The batadv-vis server must be started
to let batadv-vis work:
$ batadv-vis -i bat0 -s
This server will read the neighbor and client information from batman-adv every
10 seconds and set it in alfred via unix socket. Obviously, the alfred server
must run too to get this information set.
To get a graphviz-compatible vis output, simply type:
$ batadv-vis
digraph {
subgraph "cluster_fe:f0:00:00:04:01" {
"fe:f0:00:00:04:01"
}
"fe:f0:00:00:04:01" -> "fe:f0:00:00:05:01" [label="1.000"]
"fe:f0:00:00:04:01" -> "fe:f0:00:00:03:01" [label="1.004"]
"fe:f0:00:00:04:01" -> "00:00:43:05:00:04" [label="TT"]
"fe:f0:00:00:04:01" -> "fe:f1:00:00:04:01" [label="TT"]
subgraph "cluster_fe:f0:00:00:02:01" {
"fe:f0:00:00:02:01"
}
"fe:f0:00:00:02:01" -> "fe:f0:00:00:03:01" [label="1.000"]
"fe:f0:00:00:02:01" -> "fe:f0:00:00:01:01" [label="1.008"]
"fe:f0:00:00:02:01" -> "fe:f0:00:00:08:01" [label="1.000"]
"fe:f0:00:00:02:01" -> "fe:f1:00:00:02:01" [label="TT"]
"fe:f0:00:00:02:01" -> "00:00:43:05:00:02" [label="TT"]
subgraph "cluster_fe:f0:00:00:08:01" {
"fe:f0:00:00:08:01"
}
[...]
}
For a json line formatted output, use:
$ batadv-vis -f json
{ "primary" : "fe:f0:00:00:04:01" }
{ "router" : "fe:f0:00:00:04:01", "neighbor" : "fe:f0:00:00:05:01", "label" : "1.000" }
{ "router" : "fe:f0:00:00:04:01", "neighbor" : "fe:f0:00:00:03:01", "label" : "1.008" }
{ "router" : "fe:f0:00:00:04:01", "gateway" : "00:00:43:05:00:04", "label" : "TT" }
{ "router" : "fe:f0:00:00:04:01", "gateway" : "fe:f1:00:00:04:01", "label" : "TT" }
{ "primary" : "fe:f0:00:00:02:01" }
{ "router" : "fe:f0:00:00:02:01", "neighbor" : "fe:f0:00:00:03:01", "label" : "1.000" }
{ "router" : "fe:f0:00:00:02:01", "neighbor" : "fe:f0:00:00:01:01", "label" : "1.016" }
{ "router" : "fe:f0:00:00:02:01", "neighbor" : "fe:f0:00:00:08:01", "label" : "1.000" }
{ "router" : "fe:f0:00:00:02:01", "gateway" : "fe:f1:00:00:02:01", "label" : "TT" }
{ "router" : "fe:f0:00:00:02:01", "gateway" : "00:00:43:05:00:02", "label" : "TT" }
{ "primary" : "fe:f0:00:00:08:01" }
[...]
and for output where the complete document is json, use:
$ batadv-vis -f jsondoc
{
"source_version" : "2013.3.0-14-gcd34783",
"algorithm" : 4,
"vis" : [
{ "primary" : "fe:f0:00:00:04:01",
"neighbors" : [
{ "router" : "fe:f0:00:00:04:01",
"neighbor" : "fe:f0:00:00:05:01",
"metric" : "1.000" },
{ "router" : "fe:f0:00:00:04:01",
"neighbor" : "fe:f0:00:00:03:01",
"metric" : "1.008" }
],
"clients" : [
"00:00:43:05:00:04",
"fe:f1:00:00:04:01"
]
},
{ "primary" : "fe:f0:00:00:02:01",
"neighbors" : [
{ "router" : "fe:f0:00:00:02:01",
"neighbor" : "fe:f0:00:00:03:01",
"metric" : "1.000" },
{ "router" : "fe:f0:00:00:02:01",
"neighbor" : "fe:f0:00:00:01:01",
"metric" : "1.016" },
{ "router" : "fe:f0:00:00:02:01",
"neighbor" : "fe:f0:00:00:08:01",
"metric" : "1.000" }
],
"clients" : [
"fe:f1:00:00:02:01",
"00:00:43:05:00:02"
]
},
{ "primary" : "fe:f0:00:00:08:01",
[...]
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.
Alfred-gpsd, similar to to alfred, combines server (daemon) and client
functionality in the 'alfred-gpsd' binary. The alfred-gpsd server must
be started to distribute location information. When retrieving
location information from gpsd, it should be started with:
$ alfred-gpsd -s
For a static location, use:
$ alfred-gpsd -s -l 48.858222,2.2945,358
This server will set the location in alfred via unix
socket. Obviously, the alfred server must run too to get this
information set. When using gpsd, it updates alfred every 2
seconds. With a static location, the update it made every 5 minutes.
To get JSON formatted output, use:
$ alfred-gpsd
[
{ "source" : "f6:00:48:13:d3:1e", "tpv" : {"class":"TPV","tag":"RMC","device":"/dev/ttyACM0","mode":3,"time":"2013-10-01T10:43:20.000Z","ept":0.005,"lat":52.575485000,"lon":-1.339716667,"alt":122.500,"epx":10.199,"epy":15.720,"epv":31.050,"track":0.0000,"speed":0.010,"climb":0.000,"eps":31.44} },
{ "source" : "8e:4c:77:b3:65:b4", "tpv" : {"class":"TPV","device":"command line","time":"2013-10-01T10:43:05.129Z","lat":48.858222,"lon":2.2945,"alt":358.000000,"mode":3} }
]
See gpsd_json(5) for documentation of the tpv object.
Running alfred as non-root user
-------------------------------
Alfred currently requires special capabilities and access rights to work
correctly. The user root is normally the only user having these
capabilities/rights on a standard Linux system.
Operations requiring special capabilities:
* bind to device
* creating the unix socket
* accessing the debugfs filesystem
The first operation can still be executed when the admin grants the special
capability CAP_NET_RAW to anyone executing the alfred binary. The unix socket
can also be moved using the parameter '-u' to a different directory which can
be accessed by the user.
$ sudo setcap cap_net_raw+ep alfred
$ ./alfred -u alfred.sock -i eth0
The user running alfred must still be in a group which is allowed to access
/sys/kernel/debugfs to correctly choose best neighbors for communication.
It is possible (but not recommended) to disable the neighbor
selection/prioritization using the parameter '-b none'.
License
-------
alfred, batadv-vis and alfred-gpsd are licensed under the terms of version 2
of the GNU General Public License (GPL). Please see the LICENSE file.
The file "packet.h" is an exception and not licensed with the GPL. Instead,
it is licensed using ISC license (see the head of this file). This allows
programs to include this header file (e.g. for communicating with alfred via
unix sockets) without enforcing the restrions of the GPL license on this third
party program.
Contact
-------
As alfred was developed to help on batman-adv, we share communication channels.
Please send us comments, experiences, questions, anything :)
IRC: #batman on irc.freenode.org
Mailing-list: [email protected] (optional subscription
at https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n)
If you have test reports/patches/ideas, please read the wiki for further instruction
on how to contribute:
https://www.open-mesh.org/projects/open-mesh/wiki/Contribute
You can also contact the Authors:
Simon Wunderlich <[email protected]>
Sven Eckelmann <[email protected]>