About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / batman-adv.txt


Based on kernel version 4.13.3. Page generated on 2017-09-23 13:55 EST.

1	BATMAN-ADV
2	----------
3	
4	Batman  advanced  is  a new approach to wireless networking which
5	does no longer operate on the IP basis. Unlike the batman daemon,
6	which  exchanges  information  using UDP packets and sets routing
7	tables, batman-advanced operates on ISO/OSI Layer 2 only and uses
8	and  routes  (or  better: bridges) Ethernet Frames. It emulates a
9	virtual network switch of all nodes participating.  Therefore all
10	nodes  appear  to be link local, thus all higher operating proto-
11	cols won't be affected by any changes within the network. You can
12	run almost any protocol above batman advanced, prominent examples
13	are: IPv4, IPv6, DHCP, IPX.
14	
15	Batman advanced was implemented as a Linux kernel driver  to  re-
16	duce the overhead to a minimum. It does not depend on any (other)
17	network driver, and can be used on wifi as well as ethernet  lan,
18	vpn,  etc ... (anything with ethernet-style layer 2).
19	
20	
21	CONFIGURATION
22	-------------
23	
24	Load the batman-adv module into your kernel:
25	
26	# insmod batman-adv.ko
27	
28	The  module  is now waiting for activation. You must add some in-
29	terfaces on which batman can operate. After  loading  the  module
30	batman  advanced  will scan your systems interfaces to search for
31	compatible interfaces. Once found, it will create  subfolders  in
32	the /sys directories of each supported interface, e.g.
33	
34	# ls /sys/class/net/eth0/batman_adv/
35	# elp_interval  iface_status  mesh_iface  throughput_override
36	
37	If an interface does not have the "batman_adv" subfolder it prob-
38	ably is not supported. Not supported  interfaces  are:  loopback,
39	non-ethernet and batman's own interfaces.
40	
41	Note:  After the module was loaded it will continuously watch for
42	new interfaces to verify the compatibility. There is no  need  to
43	reload the module if you plug your USB wifi adapter into your ma-
44	chine after batman advanced was initially loaded.
45	
46	The batman-adv soft-interface can be created using  the  iproute2
47	tool "ip"
48	
49	# ip link add name bat0 type batadv
50	
51	To  activate a  given  interface  simply  attach it to the "bat0"
52	interface
53	
54	# ip link set dev eth0 master bat0
55	
56	Repeat  this step for all interfaces you wish to add.  Now batman
57	starts using/broadcasting on this/these interface(s).
58	
59	By reading the "iface_status" file you can check its status:
60	
61	# cat /sys/class/net/eth0/batman_adv/iface_status
62	# active
63	
64	To  deactivate  an  interface  you  have   to  detach it from the
65	"bat0" interface:
66	
67	# ip link set dev eth0 nomaster
68	
69	
70	All  mesh  wide  settings  can be found in batman's own interface
71	folder:
72	
73	# ls /sys/class/net/bat0/mesh/
74	# aggregated_ogms        fragmentation  isolation_mark  routing_algo
75	# ap_isolation           gw_bandwidth   log_level       vlan0
76	# bonding                gw_mode        multicast_mode
77	# bridge_loop_avoidance  gw_sel_class   network_coding
78	# distributed_arp_table  hop_penalty    orig_interval
79	
80	There is a special folder for debugging information:
81	
82	# ls /sys/kernel/debug/batman_adv/bat0/
83	# bla_backbone_table  log          neighbors          transtable_local
84	# bla_claim_table     mcast_flags  originators
85	# dat_cache           nc           socket
86	# gateways            nc_nodes     transtable_global
87	
88	Some of the files contain all sort of status information  regard-
89	ing  the  mesh  network.  For  example, you can view the table of
90	originators (mesh participants) with:
91	
92	# cat /sys/kernel/debug/batman_adv/bat0/originators
93	
94	Other files allow to change batman's behaviour to better fit your
95	requirements.  For instance, you can check the current originator
96	interval (value in milliseconds which determines how often batman
97	sends its broadcast packets):
98	
99	# cat /sys/class/net/bat0/mesh/orig_interval
100	# 1000
101	
102	and also change its value:
103	
104	# echo 3000 > /sys/class/net/bat0/mesh/orig_interval
105	
106	In very mobile scenarios, you might want to adjust the originator
107	interval to a lower value. This will make the mesh  more  respon-
108	sive to topology changes, but will also increase the overhead.
109	
110	
111	USAGE
112	-----
113	
114	To  make use of your newly created mesh, batman advanced provides
115	a new interface "bat0" which you should use from this  point  on.
116	All  interfaces  added  to  batman  advanced are not relevant any
117	longer because batman handles them for you. Basically, one "hands
118	over" the data by using the batman interface and batman will make
119	sure it reaches its destination.
120	
121	The "bat0" interface can be used like any  other  regular  inter-
122	face.  It needs an IP address which can be either statically con-
123	figured or dynamically (by using DHCP or similar services):
124	
125	# NodeA: ip link set up dev bat0
126	# NodeA: ip addr add 192.168.0.1/24 dev bat0
127	
128	# NodeB: ip link set up dev bat0
129	# NodeB: ip addr add 192.168.0.2/24 dev bat0
130	# NodeB: ping 192.168.0.1
131	
132	Note:  In  order to avoid problems remove all IP addresses previ-
133	ously assigned to interfaces now used by batman advanced, e.g.
134	
135	# ip addr flush dev eth0
136	
137	
138	LOGGING/DEBUGGING
139	-----------------
140	
141	All error messages, warnings and information messages are sent to
142	the kernel log. Depending on your operating  system  distribution
143	this  can  be read in one of a number of ways. Try using the com-
144	mands: dmesg, logread, or looking in the files  /var/log/kern.log
145	or  /var/log/syslog.  All  batman-adv  messages are prefixed with
146	"batman-adv:" So to see just these messages try
147	
148	# dmesg | grep batman-adv
149	
150	When investigating problems with your mesh network  it  is  some-
151	times  necessary  to see more detail debug messages. This must be
152	enabled when compiling the batman-adv module. When building  bat-
153	man-adv  as  part of kernel, use "make menuconfig" and enable the
154	option "B.A.T.M.A.N. debugging".
155	
156	Those additional  debug messages can be accessed  using a special
157	file in debugfs
158	
159	# cat /sys/kernel/debug/batman_adv/bat0/log
160	
161	The additional debug output is by default disabled. It can be en-
162	abled  during run time. Following log_levels are defined:
163	
164	  0 - All  debug  output  disabled
165	  1 - Enable messages related to routing / flooding / broadcasting
166	  2 - Enable messages related to route added / changed / deleted
167	  4 - Enable messages related to translation table operations
168	  8 - Enable messages related to bridge loop avoidance
169	 16 - Enable messages related to DAT, ARP snooping and parsing
170	 32 - Enable messages related to network coding
171	 64 - Enable messages related to multicast
172	128 - Enable messages related to throughput meter
173	255 - Enable all messages
174	
175	The debug output can be changed at runtime  using  the  file
176	/sys/class/net/bat0/mesh/log_level. e.g.
177	
178	# echo 6 > /sys/class/net/bat0/mesh/log_level
179	
180	will enable debug messages for when routes change.
181	
182	Counters for different types of packets entering and leaving the
183	batman-adv module are available through ethtool:
184	
185	# ethtool --statistics bat0
186	
187	
188	BATCTL
189	------
190	
191	As batman advanced operates on layer 2 all hosts participating in
192	the  virtual switch are completely transparent for all  protocols
193	above layer 2. Therefore the common diagnosis tools do  not  work
194	as  expected.  To  overcome these problems batctl was created. At
195	the  moment the  batctl contains ping,  traceroute,  tcpdump  and
196	interfaces to the kernel module settings.
197	
198	For more information, please see the manpage (man batctl).
199	
200	batctl is available on https://www.open-mesh.org/
201	
202	
203	CONTACT
204	-------
205	
206	Please send us comments, experiences, questions, anything :)
207	
208	IRC:            #batman   on   irc.freenode.org
209	Mailing-list:   b.a.t.m.a.n@open-mesh.org (optional  subscription
210	          at https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n)
211	
212	You can also contact the Authors:
213	
214	Marek  Lindner  <mareklindner@neomailbox.ch>
215	Simon  Wunderlich  <sw@simonwunderlich.de>
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog