blob: 88d4afbdef98a913b539e3973a804220f491635c [file] [log] [blame]
Antonio Quartulli2dafb492011-05-05 08:42:45 +02001[state: 17-04-2011]
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +00002
3BATMAN-ADV
4----------
5
6Batman advanced is a new approach to wireless networking which
7does no longer operate on the IP basis. Unlike the batman daemon,
8which exchanges information using UDP packets and sets routing
9tables, batman-advanced operates on ISO/OSI Layer 2 only and uses
10and routes (or better: bridges) Ethernet Frames. It emulates a
11virtual network switch of all nodes participating. Therefore all
12nodes appear to be link local, thus all higher operating proto-
13cols won't be affected by any changes within the network. You can
14run almost any protocol above batman advanced, prominent examples
15are: IPv4, IPv6, DHCP, IPX.
16
17Batman advanced was implemented as a Linux kernel driver to re-
18duce the overhead to a minimum. It does not depend on any (other)
19network driver, and can be used on wifi as well as ethernet lan,
20vpn, etc ... (anything with ethernet-style layer 2).
21
Antonio Quartulli2dafb492011-05-05 08:42:45 +020022
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +000023CONFIGURATION
24-------------
25
26Load the batman-adv module into your kernel:
27
28# insmod batman-adv.ko
29
30The module is now waiting for activation. You must add some in-
31terfaces on which batman can operate. After loading the module
32batman advanced will scan your systems interfaces to search for
33compatible interfaces. Once found, it will create subfolders in
34the /sys directories of each supported interface, e.g.
35
36# ls /sys/class/net/eth0/batman_adv/
37# iface_status mesh_iface
38
39If an interface does not have the "batman_adv" subfolder it prob-
40ably is not supported. Not supported interfaces are: loopback,
41non-ethernet and batman's own interfaces.
42
43Note: After the module was loaded it will continuously watch for
44new interfaces to verify the compatibility. There is no need to
45reload the module if you plug your USB wifi adapter into your ma-
46chine after batman advanced was initially loaded.
47
48To activate a given interface simply write "bat0" into its
49"mesh_iface" file inside the batman_adv subfolder:
50
51# echo bat0 > /sys/class/net/eth0/batman_adv/mesh_iface
52
53Repeat this step for all interfaces you wish to add. Now batman
54starts using/broadcasting on this/these interface(s).
55
56By reading the "iface_status" file you can check its status:
57
58# cat /sys/class/net/eth0/batman_adv/iface_status
59# active
60
61To deactivate an interface you have to write "none" into its
62"mesh_iface" file:
63
64# echo none > /sys/class/net/eth0/batman_adv/mesh_iface
65
66
67All mesh wide settings can be found in batman's own interface
68folder:
69
70# ls /sys/class/net/bat0/mesh/
Sven Eckelmann091b9482011-01-27 10:56:56 +010071# aggregated_ogms gw_bandwidth hop_penalty
72# bonding gw_mode orig_interval
73# fragmentation gw_sel_class vis_mode
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +000074
75
Sylvestre Ledruf65e51d2011-04-04 15:04:46 -070076There is a special folder for debugging information:
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +000077
78# ls /sys/kernel/debug/batman_adv/bat0/
Sven Eckelmann091b9482011-01-27 10:56:56 +010079# gateways socket transtable_global vis_data
80# originators softif_neigh transtable_local
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +000081
82
83Some of the files contain all sort of status information regard-
84ing the mesh network. For example, you can view the table of
85originators (mesh participants) with:
86
87# cat /sys/kernel/debug/batman_adv/bat0/originators
88
89Other files allow to change batman's behaviour to better fit your
90requirements. For instance, you can check the current originator
91interval (value in milliseconds which determines how often batman
92sends its broadcast packets):
93
94# cat /sys/class/net/bat0/mesh/orig_interval
95# 1000
96
97and also change its value:
98
99# echo 3000 > /sys/class/net/bat0/mesh/orig_interval
100
101In very mobile scenarios, you might want to adjust the originator
102interval to a lower value. This will make the mesh more respon-
103sive to topology changes, but will also increase the overhead.
104
105
106USAGE
107-----
108
109To make use of your newly created mesh, batman advanced provides
110a new interface "bat0" which you should use from this point on.
111All interfaces added to batman advanced are not relevant any
112longer because batman handles them for you. Basically, one "hands
113over" the data by using the batman interface and batman will make
114sure it reaches its destination.
115
116The "bat0" interface can be used like any other regular inter-
117face. It needs an IP address which can be either statically con-
118figured or dynamically (by using DHCP or similar services):
119
120# NodeA: ifconfig bat0 192.168.0.1
121# NodeB: ifconfig bat0 192.168.0.2
122# NodeB: ping 192.168.0.1
123
124Note: In order to avoid problems remove all IP addresses previ-
125ously assigned to interfaces now used by batman advanced, e.g.
126
127# ifconfig eth0 0.0.0.0
128
129
130VISUALIZATION
131-------------
132
133If you want topology visualization, at least one mesh node must
134be configured as VIS-server:
135
136# echo "server" > /sys/class/net/bat0/mesh/vis_mode
137
138Each node is either configured as "server" or as "client" (de-
139fault: "client"). Clients send their topology data to the server
140next to them, and server synchronize with other servers. If there
141is no server configured (default) within the mesh, no topology
142information will be transmitted. With these "synchronizing
143servers", there can be 1 or more vis servers sharing the same (or
144at least very similar) data.
145
146When configured as server, you can get a topology snapshot of
147your mesh:
148
149# cat /sys/kernel/debug/batman_adv/bat0/vis_data
150
151This raw output is intended to be easily parsable and convertable
152with other tools. Have a look at the batctl README if you want a
153vis output in dot or json format for instance and how those out-
154puts could then be visualised in an image.
155
156The raw format consists of comma separated values per entry where
157each entry is giving information about a certain source inter-
158face. Each entry can/has to have the following values:
159-> "mac" - mac address of an originator's source interface
160 (each line begins with it)
161-> "TQ mac value" - src mac's link quality towards mac address
162 of a neighbor originator's interface which
163 is being used for routing
Antonio Quartulli2dafb492011-05-05 08:42:45 +0200164-> "TT mac" - TT announced by source mac
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +0000165-> "PRIMARY" - this is a primary interface
166-> "SEC mac" - secondary mac address of source
167 (requires preceding PRIMARY)
168
169The TQ value has a range from 4 to 255 with 255 being the best.
Antonio Quartulli2dafb492011-05-05 08:42:45 +0200170The TT entries are showing which hosts are connected to the mesh
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +0000171via bat0 or being bridged into the mesh network. The PRIMARY/SEC
172values are only applied on primary interfaces
173
174
175LOGGING/DEBUGGING
176-----------------
177
178All error messages, warnings and information messages are sent to
179the kernel log. Depending on your operating system distribution
180this can be read in one of a number of ways. Try using the com-
181mands: dmesg, logread, or looking in the files /var/log/kern.log
182or /var/log/syslog. All batman-adv messages are prefixed with
183"batman-adv:" So to see just these messages try
184
185# dmesg | grep batman-adv
186
187When investigating problems with your mesh network it is some-
188times necessary to see more detail debug messages. This must be
189enabled when compiling the batman-adv module. When building bat-
190man-adv as part of kernel, use "make menuconfig" and enable the
191option "B.A.T.M.A.N. debugging".
192
193Those additional debug messages can be accessed using a special
194file in debugfs
195
196# cat /sys/kernel/debug/batman_adv/bat0/log
197
198The additional debug output is by default disabled. It can be en-
199abled during run time. Following log_levels are defined:
200
2010 - All debug output disabled
2021 - Enable messages related to routing / flooding / broadcasting
Antonio Quartulli2dafb492011-05-05 08:42:45 +02002032 - Enable route or tt entry added / changed / deleted
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +00002043 - Enable all messages
205
206The debug output can be changed at runtime using the file
207/sys/class/net/bat0/mesh/log_level. e.g.
208
209# echo 2 > /sys/class/net/bat0/mesh/log_level
210
Antonio Quartulli2dafb492011-05-05 08:42:45 +0200211will enable debug messages for when routes or TTs change.
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +0000212
213
214BATCTL
215------
216
217As batman advanced operates on layer 2 all hosts participating in
218the virtual switch are completely transparent for all protocols
219above layer 2. Therefore the common diagnosis tools do not work
220as expected. To overcome these problems batctl was created. At
221the moment the batctl contains ping, traceroute, tcpdump and
222interfaces to the kernel module settings.
223
224For more information, please see the manpage (man batctl).
225
226batctl is available on http://www.open-mesh.org/
227
228
229CONTACT
230-------
231
232Please send us comments, experiences, questions, anything :)
233
234IRC: #batman on irc.freenode.org
Sven Eckelmann091b9482011-01-27 10:56:56 +0100235Mailing-list: b.a.t.m.a.n@open-mesh.org (optional subscription
236 at https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n)
Sven Eckelmannc6c8fea2010-12-13 11:19:28 +0000237
238You can also contact the Authors:
239
240Marek Lindner <lindner_marek@yahoo.de>
241Simon Wunderlich <siwu@hrz.tu-chemnitz.de>