Commit | Line | Data |
---|---|---|
d06dfbc6 SE |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
e45eba24 SE |
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> |