Calling the BATMAN: Free networks on FreeBSD
Student: AymericWibo (obiwac@freebsd.org)
Mentor: MahdiMokhtari (mmokhi@)
Project description
BATMAN (Better Approach to Mobile Ad-hoc Networking), as developed and used by the Freifunk project, is a routing protocol for (primarily wireless) multi-hop ad-hoc networks. Freifunk is a German initiative to build an open Wi-Fi network at city-scale, based on the principles of net-neutrality. BATMAN's motive is to be a completely decentralized protocol; no one node in the network knows or has to care about the topology of the whole network.
Support for this protocol is provided by the batman-adv kernel module on Linux, which has been ported to FreeBSD through the batman_adv(4) kernel module.
Demo
What works
- Loading batman_adv(4).
- Creating BATMAN mesh interfaces with ifconfig(8), and choosing the routing algorithm.
Setting the "master" of an interface (with IFLA_MASTER) to add it to the mesh interface.
- Sending/receiving packets between Ethernet nodes on the mesh.
All this also works and was tested a Linux environment with iproute2.
What is there still to do
Port batctl (and by extension libnl).
- Get Wi-Fi interfaces to work as slaves to BATMAN interfaces, not just Ethernet.
- Support BATMAN extensions (DAT, BLA, and multicast optimizations don't seem that difficult, I haven't looked much into NC but it seems harder).
- Allow users to modify mesh attributes through ifconfig(8).
I plan to continue working on this after the final evaluation 
What I've done
This is explained in more detail in the deliverables section.
Brought the Linux source for batman-adv into the FreeBSD tree.
Got it all compiling/working by adding missing functionality necessary to the functioning of BATMAN to LinuxKPI (notably backing struct net_device by struct ifnet and mbuf <=> sk_buff conversion).
Created batadv cloner for creating BATMAN soft interfaces.
- Added support for setting the master interface of an interface (used for giving slave "hard" interfaces to the BATMAN "soft" interface).
- Added support to ifconfig(8) for setting master interfaces and also creating BATMAN soft interfaces with the specified routing algo.
- Added manual page for batman_adv(4) and updated ifconfig(8), rtnetlink(4), and ifnet(9) manpages.
The Code
GitHub: https://github.com/obiwac/freebsd-gsoc/pull/1.
This is the diff w.r.t. FreeBSD with the batman-adv sources already pulled into the tree. The diff with just the batman-adv sources are here: https://github.com/obiwac/freebsd-gsoc/pull/3
The last GSoC-related commit was a06c5b5befe37df259d5e5e4af77723dd5815089 ("netlink: Only compile LinuxKPI-related code when COMPAT_LINUXKPI is set"),
Approach to solving the problem and deliverables
This project consisted of the following parts:
Getting the kernel module working (milestone 1)
The first step was getting batman-adv kernel module for Linux compiling & working on FreeBSD. This included a bunch of additions to the LinuxKPI and the relatively new Netlink API in FreeBSD.
BATMAN support for userland libraries/utilities (milestone 2)
Support for creating and managing BATMAN networks was added to ifconfig(8). Setting attributes other than the routing algorithm is currently not supported due to limited support for Netlink Generic.
batctl (milestone 3)
This ended up being a little more complicated than expected 
batctl uses libnl on Linux, whereas FreeBSD has snl(3) for user programs. I'd like to port libnl to FreeBSD, backed by snl(3), such that future Linux programs which rely on Netlink may easily be ported.
Documentation (milestone 4)
The ifconfig(8), rtnetlink(4), and ifnet(9) manpages have been updated. There's also a batman_adv(4) manpage which describes the batman_adv kernel module at a high level, and shows a basic example of usage.
Useful links
Link to GSoC program page: https://summerofcode.withgoogle.com/programs/2023/projects/9YX3dONN
Linux kernel documentation of batman-adv: https://www.kernel.org/doc/html/latest/networking/batman-adv.html
Overview of batman-adv: https://www.open-mesh.org/projects/batman-adv/wiki/Understand-your-batman-adv-network