root/trunk/batctl/README @ 1466

Revision 1466, 13.9 kB (checked in by simon, 9 months ago)

update the batctl README

Line 
1##############################################################################
2# batctl - B.A.T.M.A.N. advanced control and management tool                 #
3##############################################################################
4
5
6
7Introduction
8============
9
10Why do I need batctl ? B.A.T.M.A.N. advanced operates on layer 2 and thus all
11hosts participating in the virtual switch are completely transparent for all
12protocols above layer 2. Therefore the common diagnosis tools do not work as
13expected. To overcome these problems batctl was created. At the moment batctl
14contains ping, traceroute, tcpdump and interfaces to the kernel module
15settings.
16
17
18How does it work ?
19==================
20
21batctl uses the /dev/batman-adv device provided by the B.A.T.M.A.N. advanced
22kernel module to inject custom icmp packets into the data flow. That's why
23ping and traceroute work almost like their IP based counterparts. Tcpdump was
24designed because B.A.T.M.A.N. advanced encapsulates all traffic within batman
25packets, so that the normal tcpdump would not recognize the packets.
26
27
28The bat-hosts file
29==================
30
31This file is simliar to the /etc/hosts file. You can write one MAC address and
32one host name per line. batctl will analyze the file to find the matching MAC
33address to your provided host name. Host names are much easier to remember
34than MAC addresses.  ;)
35
36
37batctl ping
38============
39
40Sends a Layer 2 batman-adv ping to check round trip time and connectivity
41
42Usage: batctl ping [options] mac|bat-host
43options:
44         -c ping packet count
45         -h print this help
46         -i interval in seconds
47         -t timeout in seconds
48
49Example:
50
51$ batctl ping fe:fe:00:00:09:01
52PING fe:fe:00:00:09:01 (fe:fe:00:00:09:01) 19(47) bytes of data
5319 bytes from fe:fe:00:00:09:01 icmp_seq=1 ttl=43 time=8.74 ms
5419 bytes from fe:fe:00:00:09:01 icmp_seq=2 ttl=43 time=7.48 ms
5519 bytes from fe:fe:00:00:09:01 icmp_seq=3 ttl=43 time=8.23 ms
56^C--- fe:fe:00:00:09:01 ping statistics ---
573 packets transmitted, 3 received, 0% packet loss
58rtt min/avg/max/mdev = 7.476/8.151/8.743/1.267 ms
59
60batctl traceroute
61==================
62
63Traceroute sends 3 packets to each hop, awaits the answers and prints out the
64response times.
65
66Usage: batctl traceroute [options] mac|bat-host
67
68Example:
69
70$ batctl traceroute fe:fe:00:00:09:01
71traceroute to fe:fe:00:00:09:01 (fe:fe:00:00:09:01), 50 hops max, 19 byte packets
72 1: fe:fe:00:00:02:01 4.932 ms  2.338 ms  1.333 ms
73 2: fe:fe:00:00:03:01 6.860 ms  1.579 ms  1.260 ms
74 3: fe:fe:00:00:04:01 2.342 ms  1.547 ms  1.655 ms
75 4: fe:fe:00:00:05:01 2.906 ms  2.211 ms  2.253 ms
76 5: fe:fe:00:00:06:01 3.577 ms  2.687 ms  3.088 ms
77 6: fe:fe:00:00:07:01 4.217 ms  5.741 ms  3.551 ms
78 7: fe:fe:00:00:08:01 5.017 ms  5.547 ms  4.294 ms
79 8: fe:fe:00:00:09:01 5.730 ms  4.970 ms  6.437 ms
80
81
82
83batctl tcpdump
84===============
85
86tcpdump layer 2 traffic on the given interface
87
88Usage: batctl tcpdump [options] interface [interface]
89options:
90         -h print this help
91         -n don't convert addresses to bat-host names
92         -p dump specific packet type
93                1 - batman ogm packets
94                2 - batman icmp packets
95                4 - batman unicast packets
96                8 - batman broadcast packets
97                16 - batman vis packets
98                32 - non batman packets
99                33 - batman ogm & non batman packets
100
101Example output for tcpdump:
102
103$ batctl tcpdump mesh0
10401:51:42.401188 BAT kansas: OGM via neigh kansas, seqno 6718, tq 255, ttl 50, v 9, flags [..I], length 28
10501:51:42.489735 BAT kansas: OGM via neigh wyoming, seqno 6718, tq 245, ttl 49, v 9, flags [.D.], length 28
10601:51:42.510330 BAT wyoming: OGM via neigh wyoming, seqno 6721, tq 255, ttl 50, v 9, flags [..I], length 28
10701:51:42.601092 BAT wyoming: OGM via neigh kansas, seqno 6721, tq 245, ttl 49, v 9, flags [.D.], length 28
10801:51:43.361076 BAT kansas > wyoming: ICMP echo request, id 0, seq 1, ttl 1, v 9, length 19
10901:51:43.365347 BAT wyoming > kansas: ICMP echo reply, id 0, seq 1, ttl 50, v 9, length 19
11001:51:43.372224 BAT kansas > wyoming: ICMP echo request, id 0, seq 2, ttl 1, v 9, length 19
11101:51:43.376506 BAT wyoming > kansas: ICMP echo reply, id 0, seq 2, ttl 50, v 9, length 19
11201:51:43.381250 BAT kansas: OGM via neigh kansas, seqno 6719, tq 255, ttl 50, v 9, flags [..I], length 28
11301:51:43.386281 BAT kansas > wyoming: ICMP echo request, id 0, seq 3, ttl 1, v 9, length 19
11401:51:43.387910 BAT wyoming > kansas: ICMP echo reply, id 0, seq 3, ttl 50, v 9, length 19
11501:51:43.479503 BAT kansas: OGM via neigh wyoming, seqno 6719, tq 245, ttl 49, v 9, flags [.D.], length 28
11601:51:43.509899 BAT wyoming: OGM via neigh wyoming, seqno 6722, tq 255, ttl 50, v 9, flags [..I], length 28
11701:51:43.600999 BAT wyoming: OGM via neigh kansas, seqno 6722, tq 245, ttl 49, v 9, flags [.D.], length 28
11801:51:44.381064 BAT kansas: OGM via neigh kansas, seqno 6720, tq 255, ttl 50, v 9, flags [..I], length 28
119
120batctl bisect
121=============
122
123Analyzes  the logfiles to build a small internal database of all sent sequence
124numbers and routing table changes. This database can be used to search for
125routing loops (default action), to trace OGMs of  a  host  (use  "-t"  to
126specify  the  mac address or bat-host name) throughout the network or to
127display routing tables of the nodes (use "-r" to specify the mac address or
128bat-host name). You can name a specific sequence number or a range  using the
129"-s"  option  to limit the output's range. Furthermore you can filter the
130output by specifying an originator (use "-o" to specify the mac address or
131bat-host name) to only see data connected to  this  originator.  If  "-n"  was
132given batctl will not replace the mac addresses with bat-host names in the
133output.
134
135Usage: batctl bisect [options] <file1> <file2> .. <fileN>
136options:
137         -h print this help
138         -l run a loop detection of given mac address or bat-host (default)
139         -n don't convert addresses to bat-host names
140         -r print routing tables of given mac address or bat-host
141         -s seqno range to limit the output
142         -t trace seqnos of given mac address or bat-host
143
144Examples:
145
146$ batctl bisect log/* -l uml3
147Analyzing routing tables of originator: uml3 [all sequence numbers]
148
149Checking host: uml3
150Path towards uml7 (seqno 9 via neigh uml5): -> uml5 -> uml6
151Path towards uml7 (seqno 10 via neigh uml4): -> uml4 -> uml5 -> uml6
152Path towards uml6 (seqno 4 via neigh uml4): -> uml4
153Path towards uml8 (seqno 12 via neigh uml4): -> uml4 -> uml5 -> uml6 -> uml7
154Path towards uml8 (seqno 203 via neigh uml4): -> uml4 -> uml6 -> uml7
155Path towards uml8 (seqno 391 via neigh uml2): -> uml2 -> uml3 -> uml2 aborted due to loop!
156Path towards uml8 (seqno 396 via neigh uml4): -> uml4 -> uml6 -> uml7
157Path towards uml9 (seqno 10 via neigh uml5): -> uml5 -> uml6 -> uml7 -> uml9.
158Path towards uml9 (seqno 10 via neigh uml4): -> uml4 -> uml5 -> uml6 -> uml7 -> uml9.
159Path towards uml9 (seqno 11 via neigh uml4): -> uml4 -> uml6 -> uml7 -> uml8 -> uml9.
160Path towards uml9 (seqno 12 via neigh uml4): -> uml4 -> uml5 -> uml6 -> uml7 -> uml8 -> uml9.
161Path towards uml9 (seqno 21 via neigh uml5): -> uml5 -> uml6 -> uml7 -> uml8 -> uml9.
162Path towards uml9 (seqno 22 via neigh uml4): -> uml4 -> uml5 -> uml6 -> uml7 -> uml8 -> uml9.
163
164$ ./batctl bisect -t uml3 log/*
165Sequence number flow of originator: uml3 [all sequence numbers]
166[...]
167+=> uml3 (seqno 19)
168|- uml2 [tq: 255, ttl: 50, neigh: uml3, prev_sender: uml3]
169|   |- uml3 [tq: 154, ttl: 49, neigh: uml2, prev_sender: uml3]
170|   \- uml1 [tq: 154, ttl: 49, neigh: uml2, prev_sender: uml3]
171|       |- uml3 [tq: 51, ttl: 48, neigh: uml1, prev_sender: uml2]
172|       \- uml2 [tq: 51, ttl: 48, neigh: uml1, prev_sender: uml2]
173|- uml5 [tq: 255, ttl: 50, neigh: uml3, prev_sender: uml3]
174|   |- uml6 [tq: 33, ttl: 48, neigh: uml5, prev_sender: uml3]
175|   |   |- uml5 [tq: 11, ttl: 47, neigh: uml6, prev_sender: uml5]
176|   |   |- uml7 [tq: 11, ttl: 47, neigh: uml6, prev_sender: uml5]
177|   |   |   |- uml8 [tq: 3, ttl: 46, neigh: uml7, prev_sender: uml6]
178|   |   |   |   |- uml6 [tq: 0, ttl: 45, neigh: uml8, prev_sender: uml7]
179|   |   |   |   |- uml9 [tq: 0, ttl: 45, neigh: uml8, prev_sender: uml7]
180|   |   |   |   \- uml7 [tq: 0, ttl: 45, neigh: uml8, prev_sender: uml7]
181|   |   |   |- uml6 [tq: 3, ttl: 46, neigh: uml7, prev_sender: uml6]
182|   |   |   |- uml9 [tq: 3, ttl: 46, neigh: uml7, prev_sender: uml6]
183|   |   |   \- uml5 [tq: 3, ttl: 46, neigh: uml7, prev_sender: uml6]
184|   |   \- uml4 [tq: 11, ttl: 47, neigh: uml6, prev_sender: uml5]
185|   |- uml7 [tq: 33, ttl: 48, neigh: uml5, prev_sender: uml3]
186|   \- uml4 [tq: 33, ttl: 48, neigh: uml5, prev_sender: uml3]
187\- uml4 [tq: 255, ttl: 50, neigh: uml3, prev_sender: uml3]
188    |- uml3 [tq: 106, ttl: 49, neigh: uml4, prev_sender: uml3]
189    |- uml6 [tq: 106, ttl: 49, neigh: uml4, prev_sender: uml3]
190    |- uml2 [tq: 106, ttl: 49, neigh: uml4, prev_sender: uml3]
191    \- uml5 [tq: 106, ttl: 49, neigh: uml4, prev_sender: uml3]
192+=> uml3 (seqno 20)
193|- uml2 [tq: 255, ttl: 50, neigh: uml3, prev_sender: uml3]
194|   |- uml3 [tq: 160, ttl: 49, neigh: uml2, prev_sender: uml3]
195|   |- uml1 [tq: 160, ttl: 49, neigh: uml2, prev_sender: uml3]
196|   \- uml4 [tq: 160, ttl: 49, neigh: uml2, prev_sender: uml3]
197|- uml5 [tq: 255, ttl: 50, neigh: uml3, prev_sender: uml3]
198|   |- uml3 [tq: 43, ttl: 48, neigh: uml5, prev_sender: uml3]
199|   |- uml6 [tq: 43, ttl: 48, neigh: uml5, prev_sender: uml3]
200|   |   |- uml8 [tq: 16, ttl: 47, neigh: uml6, prev_sender: uml5]
201|   |   |- uml5 [tq: 16, ttl: 47, neigh: uml6, prev_sender: uml5]
202|   |   |- uml7 [tq: 16, ttl: 47, neigh: uml6, prev_sender: uml5]
203|   |   |   |- uml8 [tq: 5, ttl: 46, neigh: uml7, prev_sender: uml6]
204|   |   |   |   |- uml6 [tq: 0, ttl: 45, neigh: uml8, prev_sender: uml7]
205|   |   |   |   |- uml9 [tq: 0, ttl: 45, neigh: uml8, prev_sender: uml7]
206|   |   |   |   \- uml7 [tq: 0, ttl: 45, neigh: uml8, prev_sender: uml7]
207|   |   |   \- uml6 [tq: 5, ttl: 46, neigh: uml7, prev_sender: uml6]
208|   |   \- uml4 [tq: 16, ttl: 47, neigh: uml6, prev_sender: uml5]
209|   \- uml4 [tq: 43, ttl: 48, neigh: uml5, prev_sender: uml3]
210|- uml1 [tq: 255, ttl: 50, neigh: uml3, prev_sender: uml3]
211|   \- uml2 [tq: 49, ttl: 48, neigh: uml1, prev_sender: uml3]
212\- uml4 [tq: 255, ttl: 50, neigh: uml3, prev_sender: uml3]
213    |- uml3 [tq: 114, ttl: 49, neigh: uml4, prev_sender: uml3]
214    |- uml6 [tq: 114, ttl: 49, neigh: uml4, prev_sender: uml3]
215    |- uml2 [tq: 114, ttl: 49, neigh: uml4, prev_sender: uml3]
216    \- uml5 [tq: 114, ttl: 49, neigh: uml4, prev_sender: uml3]
217[...]
218
219batctl originators
220==================
221
222Check the Originators table
223
224Usage: batctl originators|o
225
226Example:
227
228$ batctl originators
229  Originator     (#/255)           Nexthop [outgoingIF]:   Potential nexthops ... [B.A.T.M.A.N. adv 0.2-beta r1457, MainIF/MAC: eth0/fe:fe:00:00:01:01]
230fe:fe:00:00:05:01  (223) fe:fe:00:00:02:01 [      eth0]: fe:fe:00:00:03:01 ( 96) fe:fe:00:00:02:01 (223)
231fe:fe:00:00:04:01  (233) fe:fe:00:00:02:01 [      eth0]: fe:fe:00:00:03:01 (100) fe:fe:00:00:02:01 (233)
232fe:fe:00:00:02:01  (254) fe:fe:00:00:02:01 [      eth0]: fe:fe:00:00:02:01 (254) fe:fe:00:00:03:01 (100)
233fe:fe:00:00:07:01  (203) fe:fe:00:00:02:01 [      eth0]: fe:fe:00:00:02:01 (203) fe:fe:00:00:03:01 ( 88)
234fe:fe:00:00:08:01  (196) fe:fe:00:00:02:01 [      eth0]: fe:fe:00:00:03:01 (  0) fe:fe:00:00:02:01 (196)
235fe:fe:00:00:03:01  (244) fe:fe:00:00:02:01 [      eth0]: fe:fe:00:00:03:01 (104) fe:fe:00:00:02:01 (244)
236fe:fe:00:00:09:01  (184) fe:fe:00:00:02:01 [      eth0]: fe:fe:00:00:02:01 (184) fe:fe:00:00:03:01 ( 72)
237fe:fe:00:00:06:01  (214) fe:fe:00:00:02:01 [      eth0]: fe:fe:00:00:03:01 ( 76) fe:fe:00:00:02:01 (214)
238
239batctl interface
240================
241
242display or modify the interface settings
243
244Usage: batctl interface|if  [none|interface]         
245
246Example:
247
248$  batctl interface
249[  active] eth0 fe:fe:00:00:01:01
250
251batctl interval
252===============
253
254display or modify the originator interval in ms
255
256Usage: batctl interval|it   [orig_interval]
257
258Example:
259
260$ batctl interval
2611000
262
263batctl log
264==========
265
266read the log produced by the kernel module
267
268Usage: batctl log|l
269
270Example:
271
272$ batctl log
273r)
274[       400] Received BATMAN packet via NB: fe:fe:00:00:02:01 IF: eth0 [fe:fe:00:00:01:01] (from OG: fe:fe:00:00:01:01 via prev OG: fe:fe:00:00:01:01 seqno 670, tq 245, TTL 49, V 8, IDF 1)
275[       400] Drop packet: originator packet from myself (via neighbour)
276[       400] Received BATMAN packet via NB: fe:fe:00:00:02:01 IF: eth0 [fe:fe:00:00:01:01] (from OG: fe:fe:00:00:02:01 via prev OG: fe:fe:00:00:02:01 seqno 545, tq 255, TTL 50, V 8, IDF 0)
277[       400] updating last_seqno: old 544, new 545
278[       400] bidirectional: orig = fe:fe:00:00:02:01 neigh = fe:fe:00:00:02:01 => own_bcast = 64, real recv = 64, local tq: 255, asym_penalty: 255, total tq: 255
279[       400] update_originator(): Searching and updating originator entry of received packet
280[       400] Updating existing last-hop neighbour of originator
281[...]
282
283batctl loglevel
284===============
285
286display or modify the log level
287
288Usage: batctl |ll   [level]
289
290Example:
291$  batctl loglevel
292[x] critical (0)
293[x] warnings (1)
294[x] notices (2)
295[x] batman (4)
296[x] routes (8)
297
298batctl aggregation
299==================
300
301display or modify the packet aggregation setting
302
303Usage: batctl aggregation|ag [0|1]
304
305batctl translocal
306=================
307
308display the local translation table
309
310Usage: batctl translocal|tl
311
312Example:
313
314$ batctl translocal
315Locally retrieved addresses (from bat0) announced via HNA:
316 * d6:e0:fd:d9:00:00
317
318batctl transglobal
319==================
320
321display the global translation table
322
323Usage: batctl transglobal|tg
324
325Example:
326
327Globally announced HNAs received via the mesh (translation table):
328 * 16:aa:c4:a2:00:00 via fe:fe:00:00:09:01
329 * 5a:32:f9:df:00:00 via fe:fe:00:00:03:01
330 * 32:ae:5a:00:00:00 via fe:fe:00:00:04:01
331 * 86:88:80:29:00:00 via fe:fe:00:00:08:01
332 * 9e:d8:72:f2:00:00 via fe:fe:00:00:02:01
333 * 76:84:68:49:00:00 via fe:fe:00:00:05:01
334 * 86:4b:b2:d2:00:00 via fe:fe:00:00:07:01
335 * ca:a1:5b:e5:00:00 via fe:fe:00:00:06:01
336
337batctl visformat
338================
339
340display or modify the vis output format
341
342Usage: batctl visformat|vf  [format]
343
344Example:
345
346$ batctl visformat
347[x] dot_draw
348[ ] json
349
350
Note: See TracBrowser for help on using the browser.