Staging: batman-adv: updating README
Signed-off-by: Marek Lindner <lindner_marek@yahoo.de> Signed-off-by: Andrew Lunn <andrew@lunn.ch> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
This commit is contained in:
parent
6d45d8df24
commit
2d06efdb48
|
@ -1,122 +1,190 @@
|
||||||
[state: 22-03-2010]
|
[state: 03-05-2010]
|
||||||
|
|
||||||
BATMAN-ADV
|
BATMAN-ADV
|
||||||
----------
|
----------
|
||||||
|
|
||||||
Batman-advanced is a new approach to wireless networking which does no longer
|
Batman advanced is a new approach to wireless networking which
|
||||||
operate on the IP basis. Unlike B.A.T.M.A.N, which exchanges information
|
does no longer operate on the IP basis. Unlike the batman daemon,
|
||||||
using UDP packets and sets routing tables, batman-advanced operates on ISO/OSI
|
which exchanges information using UDP packets and sets routing
|
||||||
Layer 2 only and uses and routes (or better: bridges) Ethernet Frames. It
|
tables, batman-advanced operates on ISO/OSI Layer 2 only and uses
|
||||||
emulates a virtual network switch of all nodes participating. Therefore all
|
and routes (or better: bridges) Ethernet Frames. It emulates a
|
||||||
nodes appear to be link local, thus all higher operating protocols won't be
|
virtual network switch of all nodes participating. Therefore all
|
||||||
affected by any changes within the network. You can run almost any protocol
|
nodes appear to be link local, thus all higher operating proto-
|
||||||
above B.A.T.M.A.N. Advanced, prominent examples are: IPv4, IPv6, DHCP, IPX.
|
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.
|
||||||
|
|
||||||
This is batman-advanced implemented as Linux kernel driver. It does not depend
|
Batman advanced was implemented as a Linux kernel driver to re-
|
||||||
on any network (other) driver, and can be used on wifi as well as ethernet,
|
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).
|
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/
|
||||||
|
# aggregate_ogm originators transtable_global vis_mode
|
||||||
|
# orig_interval transtable_local vis_data
|
||||||
|
|
||||||
|
|
||||||
|
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/class/net/bat0/mesh/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
|
||||||
|
# status: 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
|
USAGE
|
||||||
-----
|
-----
|
||||||
|
|
||||||
insmod the batman-adv.ko in your kernel:
|
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.
|
||||||
|
|
||||||
# insmod batman-adv.ko
|
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):
|
||||||
|
|
||||||
the module is now waiting for activation. You must add some interfaces
|
# NodeA: ifconfig bat0 192.168.0.1
|
||||||
on which batman can operate. Each interface must be added separately:
|
# NodeB: ifconfig bat0 192.168.0.2
|
||||||
|
# NodeB: ping 192.168.0.1
|
||||||
|
|
||||||
# echo wlan0 > /proc/net/batman-adv/interfaces
|
Note: In order to avoid problems remove all IP addresses previ-
|
||||||
|
ously assigned to interfaces now used by batman advanced, e.g.
|
||||||
|
|
||||||
( # echo wlan1 > /proc/net/batman-adv/interfaces )
|
# ifconfig eth0 0.0.0.0
|
||||||
( # echo eth0 > /proc/net/batman-adv/interfaces )
|
|
||||||
( ... )
|
|
||||||
|
|
||||||
Now batman starts broadcasting on this interface.
|
|
||||||
You can now view the table of originators (mesh participants) with:
|
|
||||||
|
|
||||||
# cat /proc/net/batman-adv/originators
|
VISUALIZATION
|
||||||
|
-------------
|
||||||
|
|
||||||
The module will create a new interface "bat0", which can be used as a
|
If you want topology visualization, at least one mesh node must
|
||||||
regular interface:
|
be configured as VIS-server:
|
||||||
|
|
||||||
# ifconfig bat0 inet 192.168.0.1 up
|
# echo "server" > /sys/class/net/bat0/mesh/vis_mode
|
||||||
# ping 192.168.0.2
|
|
||||||
...
|
|
||||||
|
|
||||||
---
|
Each node is either configured as "server" or as "client" (de-
|
||||||
If you want topology visualization, your meshnode must be configured
|
fault: "client"). Clients send their topology data to the server
|
||||||
as VIS-server:
|
next to them, and server synchronize with other servers. If there
|
||||||
|
is no server configured (default) within the mesh, no topology
|
||||||
|
information will be transmitted. With these "synchronizing
|
||||||
|
servers", there can be 1 or more vis servers sharing the same (or
|
||||||
|
at least very similar) data.
|
||||||
|
|
||||||
# echo "server" > /proc/net/batman-adv/vis_server
|
When configured as server, you can get a topology snapshot of
|
||||||
|
your mesh:
|
||||||
|
|
||||||
Each node is either configured as "server" or as "client" (default:
|
# cat /sys/class/net/bat0/mesh/vis_data
|
||||||
"client"). Clients send their topology data to the server next to them,
|
|
||||||
and server synchronize with other servers. If there is no server
|
|
||||||
configured (default) within the mesh, no topology information will be
|
|
||||||
transmitted. With these "synchronizing servers", there can be 1 or
|
|
||||||
more vis servers sharing the same (or at least very similar) data.
|
|
||||||
|
|
||||||
When configured as server, you can get a topology snapshot of your mesh:
|
This raw output is intended to be easily parsable and convertable
|
||||||
|
with other tools. Have a look at the batctl README if you want a
|
||||||
|
vis output in dot or json format for instance and how those out-
|
||||||
|
puts could then be visualised in an image.
|
||||||
|
|
||||||
# cat /proc/net/batman-adv/vis_data
|
The raw format consists of comma separated values per entry where
|
||||||
|
each entry is giving information about a certain source inter-
|
||||||
This raw output is intended to be easily parsable and convertable with
|
face. Each entry can/has to have the following values:
|
||||||
other tools. Have a look at the batctl README if you want a vis output
|
-> "mac" - mac address of an originator's source interface
|
||||||
in dot or json format for instance and how those outputs could then be
|
|
||||||
visualised in an image.
|
|
||||||
|
|
||||||
The raw format consists of comma seperated values per entry where each
|
|
||||||
entry is giving information about a certain source interface. Each entry
|
|
||||||
can/has to have the following values:
|
|
||||||
-> "mac" -> mac address of an originator's source interface
|
|
||||||
(each line begins with it)
|
(each line begins with it)
|
||||||
-> "TQ mac value" -> src mac's link quality towards mac address of a neighbor
|
-> "TQ mac value" - src mac's link quality towards mac address
|
||||||
originator's interface which is being used for routing
|
of a neighbor originator's interface which
|
||||||
-> "HNA mac" -> HNA announced by source mac
|
is being used for routing
|
||||||
-> "PRIMARY" -> this is a primary interface
|
-> "HNA mac" - HNA announced by source mac
|
||||||
-> "SEC mac" -> secondary mac address of source (requires preceeding
|
-> "PRIMARY" - this is a primary interface
|
||||||
-> PRIMARY)
|
-> "SEC mac" - secondary mac address of source
|
||||||
|
(requires preceding PRIMARY)
|
||||||
|
|
||||||
The TQ value has a range from 4 to 255 with 255 being the best.
|
The TQ value has a range from 4 to 255 with 255 being the best.
|
||||||
The HNA entries are showing which hosts are connected to the mesh via bat0
|
The HNA entries are showing which hosts are connected to the mesh
|
||||||
or being bridged into the mesh network.
|
via bat0 or being bridged into the mesh network. The PRIMARY/SEC
|
||||||
The PRIMARY/SEC values are only applied on primary interfaces
|
values are only applied on primary interfaces
|
||||||
|
|
||||||
---
|
|
||||||
In very mobile scenarios, you might want to adjust the originator
|
|
||||||
interval to a lower value. This will make the mesh more responsive to
|
|
||||||
topology changes, but will also increase the overhead. Please make sure
|
|
||||||
that all nodes in your mesh use the same interval. The default value
|
|
||||||
is 1000 ms (1 second).
|
|
||||||
|
|
||||||
# echo 1000 > /proc/net/batman-adv/orig_interval
|
|
||||||
|
|
||||||
To deactivate batman, do:
|
|
||||||
|
|
||||||
# echo "" > /proc/net/batman-adv/interfaces
|
|
||||||
|
|
||||||
LOGGING/DEBUGGING
|
LOGGING/DEBUGGING
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
All error messages, warnings and information messages are sent to the
|
All error messages, warnings and information messages are sent to
|
||||||
kernel log. Depending on your operating system distribution this can be
|
the kernel log. Depending on your operating system distribution
|
||||||
read in one of a number of ways. Try using the commands: dmesg,
|
this can be read in one of a number of ways. Try using the com-
|
||||||
logread, or looking in the files /var/log/kern.log or
|
mands: dmesg, logread, or looking in the files /var/log/kern.log
|
||||||
/var/log/syslog. All batman-adv messages are prefixed with
|
or /var/log/syslog. All batman-adv messages are prefixed with
|
||||||
"batman-adv:" So to see just these messages try
|
"batman-adv:" So to see just these messages try
|
||||||
|
|
||||||
dmesg | grep batman-adv
|
# dmesg | grep batman-adv
|
||||||
|
|
||||||
When investigating problems with your mesh network it is sometimes
|
When investigating problems with your mesh network it is some-
|
||||||
necessary to see more detail debug messages. This must be enabled when
|
times necessary to see more detail debug messages. This must be
|
||||||
compiling the batman-adv module. Use "make menuconfig" and enable the
|
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".
|
option "B.A.T.M.A.N. debugging".
|
||||||
|
|
||||||
The additional debug output is by default disabled. It can be enabled
|
The additional debug output is by default disabled. It can be en-
|
||||||
either at kernel module load time or during run time. To enable debug
|
abled either at kernel modules load time or during run time. To
|
||||||
output at module load time, add the module parameter debug=<value>.
|
enable debug output at module load time, add the module parameter
|
||||||
<value> can take one of four values.
|
debug=<value>. <value> can take one of four values.
|
||||||
|
|
||||||
0 - All debug output disabled
|
0 - All debug output disabled
|
||||||
1 - Enable messages related to routing / flooding / broadcasting
|
1 - Enable messages related to routing / flooding / broadcasting
|
||||||
|
@ -125,34 +193,36 @@ output at module load time, add the module parameter debug=<value>.
|
||||||
|
|
||||||
e.g.
|
e.g.
|
||||||
|
|
||||||
modprobe batman-adv debug=2
|
# modprobe batman-adv debug=2
|
||||||
|
|
||||||
will load the module and enable debug messages for when routes or HNAs
|
will load the module and enable debug messages for when routes or
|
||||||
change.
|
HNAs change.
|
||||||
|
|
||||||
The debug output can also be changed at runtime using the file
|
The debug output can also be changed at runtime using the file
|
||||||
/sys/module/batman-adv/parameters/debug. e.g.
|
/sys/module/batman-adv/parameters/debug. e.g.
|
||||||
|
|
||||||
echo 2 > /sys/module/batman-adv/parameters/debug
|
# echo 2 > /sys/module/batman-adv/parameters/debug
|
||||||
|
|
||||||
enables debug messages for when routes or HNAs
|
enables debug messages for when routes or HNAs
|
||||||
|
|
||||||
The debug output is sent to the kernel logs. So try dmesg, logread etc
|
The debug output is sent to the kernel logs. So try dmesg, lo-
|
||||||
to see the debug messages.
|
gread, etc to see the debug messages.
|
||||||
|
|
||||||
|
|
||||||
BATCTL
|
BATCTL
|
||||||
------
|
------
|
||||||
|
|
||||||
B.A.T.M.A.N. advanced operates on layer 2 and thus all hosts
|
As batman advanced operates on layer 2 all hosts participating in
|
||||||
participating in the virtual switch are completely transparent for all
|
the virtual switch are completely transparent for all protocols
|
||||||
protocols above layer 2. Therefore the common diagnosis tools do not
|
above layer 2. Therefore the common diagnosis tools do not work
|
||||||
work as expected. To overcome these problems batctl was created. At
|
as expected. To overcome these problems batctl was created. At
|
||||||
the moment the batctl contains ping, traceroute, tcpdump and
|
the moment the batctl contains ping, traceroute, tcpdump and
|
||||||
interfaces to the kernel module settings.
|
interfaces to the kernel module settings.
|
||||||
|
|
||||||
For more information, please see the manpage (man batctl).
|
For more information, please see the manpage (man batctl).
|
||||||
|
|
||||||
batctl is available on http://www.open-mesh.net/
|
batctl is available on http://www.open-mesh.org/
|
||||||
|
|
||||||
|
|
||||||
CONTACT
|
CONTACT
|
||||||
-------
|
-------
|
||||||
|
@ -160,10 +230,11 @@ CONTACT
|
||||||
Please send us comments, experiences, questions, anything :)
|
Please send us comments, experiences, questions, anything :)
|
||||||
|
|
||||||
IRC: #batman on irc.freenode.org
|
IRC: #batman on irc.freenode.org
|
||||||
Mailing-list: b.a.t.m.a.n@open-mesh.net
|
Mailing-list: b.a.t.m.a.n@open-mesh.net (optional subscription
|
||||||
(subscription at https://list.open-mesh.net/mm/listinfo/b.a.t.m.a.n )
|
at https://lists.open-mesh.org/mm/listinfo/b.a.t.m.a.n)
|
||||||
|
|
||||||
You can also contact the Authors:
|
You can also contact the Authors:
|
||||||
|
|
||||||
Marek Lindner <lindner_marek@yahoo.de>
|
Marek Lindner <lindner_marek@yahoo.de>
|
||||||
Simon Wunderlich <siwu@hrz.tu-chemnitz.de>
|
Simon Wunderlich <siwu@hrz.tu-chemnitz.de>
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue