
############################################################
# batctl - B.A.T.M.A.N. advanced control and managing tool #
############################################################



Introduction
============

Why do I need batctl ? B.A.T.M.A.N. advanced operates on layer 2 and thus all hosts participating in the virtual switch are completely transparent for all protocols above layer 2. Therefore the common diagnosis tools do not work as expected. To overcome these problems batctl was created. At the moment batctl contains ping, traceroute, tcpdump and interfaces to the kernel module settings.


How does it work ?
==================

batctl uses the /dev/batman-adv device provided by the B.A.T.M.A.N. advanced kernel module to inject custom icmp packets into the data flow. That's why ping and traceroute work almost like their IP based counterparts. Tcpdump was designed because B.A.T.M.A.N. advanced encapsulates all traffic within batman packets, so that the normal tcpdump would not recognize the packets.


 The bat-hosts file
==================

This file is simliar to the /etc/hosts file. You can write one MAC address and one host name per line. batctl will analyze the file to find the matching MAC address to your provided host name. Host names are much easier to remember than MAC addresses.  ;)


batctl ping
============

batctl ping [options] [mac address|host name]

The following options are supported:

- c (count) - stop after n pings (default is infinite)

- i (interval) - interval to wait between 2 pings (default is 1 second)

- t (timeout interval) - timeout interval in seconds (default is 1 second)


batctl traceroute
==================

batctl traceroute [mac address|host name]

Traceroute sends 3 packets to each hop, awaits the answers and prints out the response times.


batctl tcpdump
===============

batctl tcpdump [options] [interface]

The following options are supported:

-a (all packets) - switch tcpdump behaviour to work as the "normal" tcpdump and filter for non-batman advanced packets

-d (dump packets) - print packet data in hex

-p (packet type) - specify to filter for certain batman packets (1 = batman packets, 2 = icmp packets, 3 = unicast packets, 4 = broadcast packets)

-v (verbose) - prints more information about each packet


B.A.T.M.A.N. advanced encapsulates all traffic within batman packets. In total it uses 4 different packet types:

batman packets - these transport the B.A.T.M.A.N. originator messages to build the mesh network

batman icmp packets - lightweight implementation of the ICMP protocol (needed for ping and traceroute)

batman unicast packets - unicast data is bound as payload in these packets

batman broadcast packets - broadcast data is bound as payload in these packets


The tcpdump output looks like:

34 05:47:22 6e:2b:79:45:c8:1a -> ff:ff:ff:ff:ff:ff BAT 6e:2b:79:45:c8:1a 6e:2b:79:45:c8:1a (seqno 401, tq 255, TTL 50, V 1, UD 0, DL 0)

60                -> packet size in bytes
17:56:57          -> time when this packet was seen
6e:2b:79:45:c8:1a -> sender mac address
ff:ff:ff:ff:ff:ff -> recipient mac address
BAT               -> packet type (batman packet)
6e:2b:79:45:c8:1a -> batman packet originator
6e:2b:79:45:c8:1a -> batman old originator
seqno 401
tq 255
ttl 50
V 1               -> batman version
UD 0              -> [1|0] unidirectional
DL 0              -> [1|0] directlink

