c28c0b6b14
Add missing sysfs attributes in the proper section of the README Signed-off-by: Antonio Quartulli <antonio@meshcoding.com> Signed-off-by: Marek Lindner <mareklindner@neomailbox.ch>
203 lines
7.0 KiB
Plaintext
203 lines
7.0 KiB
Plaintext
BATMAN-ADV
|
|
----------
|
|
|
|
Batman advanced is a new approach to wireless networking which
|
|
does no longer operate on the IP basis. Unlike the batman daemon,
|
|
which exchanges information using UDP packets and sets routing
|
|
tables, batman-advanced operates on ISO/OSI Layer 2 only and uses
|
|
and routes (or better: bridges) Ethernet Frames. It emulates a
|
|
virtual network switch of all nodes participating. Therefore all
|
|
nodes appear to be link local, thus all higher operating proto-
|
|
cols won't be affected by any changes within the network. You can
|
|
run almost any protocol above batman advanced, prominent examples
|
|
are: IPv4, IPv6, DHCP, IPX.
|
|
|
|
Batman advanced was implemented as a Linux kernel driver to re-
|
|
duce the overhead to a minimum. It does not depend on any (other)
|
|
network driver, and can be used on wifi as well as ethernet lan,
|
|
vpn, etc ... (anything with ethernet-style layer 2).
|
|
|
|
|
|
CONFIGURATION
|
|
-------------
|
|
|
|
Load the batman-adv module into your kernel:
|
|
|
|
# insmod batman-adv.ko
|
|
|
|
The module is now waiting for activation. You must add some in-
|
|
terfaces on which batman can operate. After loading the module
|
|
batman advanced will scan your systems interfaces to search for
|
|
compatible interfaces. Once found, it will create subfolders in
|
|
the /sys directories of each supported interface, e.g.
|
|
|
|
# ls /sys/class/net/eth0/batman_adv/
|
|
# iface_status mesh_iface
|
|
|
|
If an interface does not have the "batman_adv" subfolder it prob-
|
|
ably is not supported. Not supported interfaces are: loopback,
|
|
non-ethernet and batman's own interfaces.
|
|
|
|
Note: After the module was loaded it will continuously watch for
|
|
new interfaces to verify the compatibility. There is no need to
|
|
reload the module if you plug your USB wifi adapter into your ma-
|
|
chine after batman advanced was initially loaded.
|
|
|
|
To activate a given interface simply write "bat0" into its
|
|
"mesh_iface" file inside the batman_adv subfolder:
|
|
|
|
# echo bat0 > /sys/class/net/eth0/batman_adv/mesh_iface
|
|
|
|
Repeat this step for all interfaces you wish to add. Now batman
|
|
starts using/broadcasting on this/these interface(s).
|
|
|
|
By reading the "iface_status" file you can check its status:
|
|
|
|
# cat /sys/class/net/eth0/batman_adv/iface_status
|
|
# active
|
|
|
|
To deactivate an interface you have to write "none" into its
|
|
"mesh_iface" file:
|
|
|
|
# echo none > /sys/class/net/eth0/batman_adv/mesh_iface
|
|
|
|
|
|
All mesh wide settings can be found in batman's own interface
|
|
folder:
|
|
|
|
# ls /sys/class/net/bat0/mesh/
|
|
#aggregated_ogms distributed_arp_table gw_sel_class orig_interval
|
|
#ap_isolation fragmentation hop_penalty routing_algo
|
|
#bonding gw_bandwidth isolation_mark vlan0
|
|
#bridge_loop_avoidance gw_mode log_level
|
|
|
|
There is a special folder for debugging information:
|
|
|
|
# ls /sys/kernel/debug/batman_adv/bat0/
|
|
# bla_backbone_table log transtable_global
|
|
# bla_claim_table originators transtable_local
|
|
# gateways socket
|
|
|
|
Some of the files contain all sort of status information regard-
|
|
ing the mesh network. For example, you can view the table of
|
|
originators (mesh participants) with:
|
|
|
|
# cat /sys/kernel/debug/batman_adv/bat0/originators
|
|
|
|
Other files allow to change batman's behaviour to better fit your
|
|
requirements. For instance, you can check the current originator
|
|
interval (value in milliseconds which determines how often batman
|
|
sends its broadcast packets):
|
|
|
|
# cat /sys/class/net/bat0/mesh/orig_interval
|
|
# 1000
|
|
|
|
and also change its value:
|
|
|
|
# echo 3000 > /sys/class/net/bat0/mesh/orig_interval
|
|
|
|
In very mobile scenarios, you might want to adjust the originator
|
|
interval to a lower value. This will make the mesh more respon-
|
|
sive to topology changes, but will also increase the overhead.
|
|
|
|
|
|
USAGE
|
|
-----
|
|
|
|
To make use of your newly created mesh, batman advanced provides
|
|
a new interface "bat0" which you should use from this point on.
|
|
All interfaces added to batman advanced are not relevant any
|
|
longer because batman handles them for you. Basically, one "hands
|
|
over" the data by using the batman interface and batman will make
|
|
sure it reaches its destination.
|
|
|
|
The "bat0" interface can be used like any other regular inter-
|
|
face. It needs an IP address which can be either statically con-
|
|
figured or dynamically (by using DHCP or similar services):
|
|
|
|
# NodeA: ifconfig bat0 192.168.0.1
|
|
# NodeB: ifconfig bat0 192.168.0.2
|
|
# NodeB: ping 192.168.0.1
|
|
|
|
Note: In order to avoid problems remove all IP addresses previ-
|
|
ously assigned to interfaces now used by batman advanced, e.g.
|
|
|
|
# ifconfig eth0 0.0.0.0
|
|
|
|
|
|
LOGGING/DEBUGGING
|
|
-----------------
|
|
|
|
All error messages, warnings and information messages are sent to
|
|
the kernel log. Depending on your operating system distribution
|
|
this can be read in one of a number of ways. Try using the com-
|
|
mands: dmesg, logread, or looking in the files /var/log/kern.log
|
|
or /var/log/syslog. All batman-adv messages are prefixed with
|
|
"batman-adv:" So to see just these messages try
|
|
|
|
# dmesg | grep batman-adv
|
|
|
|
When investigating problems with your mesh network it is some-
|
|
times necessary to see more detail debug messages. This must be
|
|
enabled when compiling the batman-adv module. When building bat-
|
|
man-adv as part of kernel, use "make menuconfig" and enable the
|
|
option "B.A.T.M.A.N. debugging".
|
|
|
|
Those additional debug messages can be accessed using a special
|
|
file in debugfs
|
|
|
|
# cat /sys/kernel/debug/batman_adv/bat0/log
|
|
|
|
The additional debug output is by default disabled. It can be en-
|
|
abled during run time. Following log_levels are defined:
|
|
|
|
0 - All debug output disabled
|
|
1 - Enable messages related to routing / flooding / broadcasting
|
|
2 - Enable messages related to route added / changed / deleted
|
|
4 - Enable messages related to translation table operations
|
|
8 - Enable messages related to bridge loop avoidance
|
|
16 - Enable messaged related to DAT, ARP snooping and parsing
|
|
31 - Enable all messages
|
|
|
|
The debug output can be changed at runtime using the file
|
|
/sys/class/net/bat0/mesh/log_level. e.g.
|
|
|
|
# echo 6 > /sys/class/net/bat0/mesh/log_level
|
|
|
|
will enable debug messages for when routes change.
|
|
|
|
Counters for different types of packets entering and leaving the
|
|
batman-adv module are available through ethtool:
|
|
|
|
# ethtool --statistics bat0
|
|
|
|
|
|
BATCTL
|
|
------
|
|
|
|
As batman advanced operates on layer 2 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 the batctl contains ping, traceroute, tcpdump and
|
|
interfaces to the kernel module settings.
|
|
|
|
For more information, please see the manpage (man batctl).
|
|
|
|
batctl is available on http://www.open-mesh.org/
|
|
|
|
|
|
CONTACT
|
|
-------
|
|
|
|
Please send us comments, experiences, questions, anything :)
|
|
|
|
IRC: #batman on irc.freenode.org
|
|
Mailing-list: b.a.t.m.a.n@open-mesh.org (optional subscription
|
|
at https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n)
|
|
|
|
You can also contact the Authors:
|
|
|
|
Marek Lindner <mareklindner@neomailbox.ch>
|
|
Simon Wunderlich <sw@simonwunderlich.de>
|