About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / batman-adv.rst




Custom Search

Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.