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 | |
52735a6f SE |
30 | batman-adv can operate. The batman-adv soft-interface can be created using the |
31 | iproute2 tool ``ip``:: | |
e45eba24 SE |
32 | |
33 | $ ip link add name bat0 type batadv | |
34 | ||
35 | To activate a given interface simply attach it to the ``bat0`` interface:: | |
36 | ||
37 | $ ip link set dev eth0 master bat0 | |
38 | ||
52735a6f | 39 | Repeat this step for all interfaces you wish to add. Now batman-adv starts |
e45eba24 SE |
40 | using/broadcasting on this/these interface(s). |
41 | ||
e45eba24 SE |
42 | To deactivate an interface you have to detach it from the "bat0" interface:: |
43 | ||
44 | $ ip link set dev eth0 nomaster | |
45 | ||
52735a6f SE |
46 | The same can also be done using the batctl interface subcommand:: |
47 | ||
48 | batctl -m bat0 interface create | |
49 | batctl -m bat0 interface add -M eth0 | |
50 | ||
51 | To detach eth0 and destroy bat0:: | |
e45eba24 | 52 | |
52735a6f SE |
53 | batctl -m bat0 interface del -M eth0 |
54 | batctl -m bat0 interface destroy | |
e45eba24 | 55 | |
52735a6f SE |
56 | There are additional settings for each batadv mesh interface, vlan and hardif |
57 | which can be modified using batctl. Detailed information about this can be found | |
58 | in its manual. | |
e45eba24 | 59 | |
52735a6f SE |
60 | For instance, you can check the current originator interval (value |
61 | in milliseconds which determines how often batman-adv sends its broadcast | |
62 | packets):: | |
e45eba24 | 63 | |
52735a6f | 64 | $ batctl -M bat0 orig_interval |
e45eba24 SE |
65 | 1000 |
66 | ||
67 | and also change its value:: | |
68 | ||
52735a6f | 69 | $ batctl -M bat0 orig_interval 3000 |
e45eba24 SE |
70 | |
71 | In very mobile scenarios, you might want to adjust the originator interval to a | |
72 | lower value. This will make the mesh more responsive to topology changes, but | |
73 | will also increase the overhead. | |
74 | ||
4c35e15a SE |
75 | Information about the current state can be accessed via the batadv generic |
76 | netlink family. batctl provides human readable version via its debug tables | |
77 | subcommands. | |
78 | ||
e45eba24 SE |
79 | |
80 | Usage | |
81 | ===== | |
82 | ||
83 | To make use of your newly created mesh, batman advanced provides a new | |
84 | interface "bat0" which you should use from this point on. All interfaces added | |
85 | to batman advanced are not relevant any longer because batman handles them for | |
86 | you. Basically, one "hands over" the data by using the batman interface and | |
87 | batman will make sure it reaches its destination. | |
88 | ||
89 | The "bat0" interface can be used like any other regular interface. It needs an | |
90 | IP address which can be either statically configured or dynamically (by using | |
91 | DHCP or similar services):: | |
92 | ||
93 | NodeA: ip link set up dev bat0 | |
94 | NodeA: ip addr add 192.168.0.1/24 dev bat0 | |
95 | ||
96 | NodeB: ip link set up dev bat0 | |
97 | NodeB: ip addr add 192.168.0.2/24 dev bat0 | |
98 | NodeB: ping 192.168.0.1 | |
99 | ||
100 | Note: In order to avoid problems remove all IP addresses previously assigned to | |
101 | interfaces now used by batman advanced, e.g.:: | |
102 | ||
103 | $ ip addr flush dev eth0 | |
104 | ||
105 | ||
106 | Logging/Debugging | |
107 | ================= | |
108 | ||
109 | All error messages, warnings and information messages are sent to the kernel | |
110 | log. Depending on your operating system distribution this can be read in one of | |
111 | a number of ways. Try using the commands: ``dmesg``, ``logread``, or looking in | |
112 | the files ``/var/log/kern.log`` or ``/var/log/syslog``. All batman-adv messages | |
113 | are prefixed with "batman-adv:" So to see just these messages try:: | |
114 | ||
115 | $ dmesg | grep batman-adv | |
116 | ||
117 | When investigating problems with your mesh network, it is sometimes necessary to | |
118 | see more detail debug messages. This must be enabled when compiling the | |
119 | batman-adv module. When building batman-adv as part of kernel, use "make | |
120 | menuconfig" and enable the option ``B.A.T.M.A.N. debugging`` | |
121 | (``CONFIG_BATMAN_ADV_DEBUG=y``). | |
122 | ||
4c35e15a | 123 | Those additional debug messages can be accessed using the perf infrastructure:: |
e45eba24 | 124 | |
4c35e15a | 125 | $ trace-cmd stream -e batadv:batadv_dbg |
e45eba24 SE |
126 | |
127 | The additional debug output is by default disabled. It can be enabled during | |
52735a6f SE |
128 | run time:: |
129 | ||
130 | $ batctl -m bat0 loglevel routes tt | |
131 | ||
132 | will enable debug messages for when routes and translation table entries change. | |
e45eba24 SE |
133 | |
134 | Counters for different types of packets entering and leaving the batman-adv | |
135 | module are available through ethtool:: | |
136 | ||
137 | $ ethtool --statistics bat0 | |
138 | ||
139 | ||
140 | batctl | |
141 | ====== | |
142 | ||
143 | As batman advanced operates on layer 2, all hosts participating in the virtual | |
144 | switch are completely transparent for all protocols above layer 2. Therefore | |
145 | the common diagnosis tools do not work as expected. To overcome these problems, | |
146 | batctl was created. At the moment the batctl contains ping, traceroute, tcpdump | |
147 | and interfaces to the kernel module settings. | |
148 | ||
149 | For more information, please see the manpage (``man batctl``). | |
150 | ||
151 | batctl is available on https://www.open-mesh.org/ | |
152 | ||
153 | ||
154 | Contact | |
155 | ======= | |
156 | ||
157 | Please send us comments, experiences, questions, anything :) | |
158 | ||
159 | IRC: | |
160 | #batman on irc.freenode.org | |
161 | Mailing-list: | |
162 | b.a.t.m.a.n@open-mesh.org (optional subscription at | |
4dd5066a | 163 | https://lists.open-mesh.org/mailman3/postorius/lists/b.a.t.m.a.n.lists.open-mesh.org/) |
e45eba24 SE |
164 | |
165 | You can also contact the Authors: | |
166 | ||
167 | * Marek Lindner <mareklindner@neomailbox.ch> | |
168 | * Simon Wunderlich <sw@simonwunderlich.de> |