CallingTheBatmanFreeNetworksOnFreeBSD [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Calling the BATMAN: Free networks on FreeBSD ======

  * Student: [[/AymericWibo|AymericWibo]] (obiwac@freebsd.org)
  * Mentor:  [[/MahdiMokhtari|MahdiMokhtari]] (mmokhi@)

===== Project description =====

[[https://www.open-mesh.org/projects/open-mesh/wiki/BATMANConcept|BATMAN]] (Better Approach to Mobile Ad-hoc Networking), as developed and used by the [[https://freifunk.net/|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 [[https://www.kernel.org/doc/html/v4.19/networking/batman-adv.html|batman-adv]] kernel module on Linux, which has been ported to %%FreeBSD%% through the batman_adv(4) kernel module.

===== Demo =====

https://youtu.be/RgilHD84hl4

===== 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|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 [[https://github.com/obiwac/freebsd-gsoc/pull/1/commits/a06c5b5befe37df259d5e5e4af77723dd5815089|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 [[https://www.freebsd.org/status/report-2022-10-2022-12/netlink/|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