Mesh Node HOWTO

From Free Geek Seattle
Jump to: navigation, search

Following are instructions to set up a mesh-networking node in Debian. This guide assumes Debian Stable, jessie or later. If you are unsure of which release of Debian you are using, try the command lsb_release -a

This is a step-by-step guide, intended to help in understanding the process. If you want easy deployment, see, OpenWRT, or other projects that will be listed here.

The List[edit]

How it Works[edit]

This article is about adapting common, off-the-shelf devices into mesh-network nodes. Such devices include, but are not limited to, personal computers, home wifi routers, tiny computers (i.e. $FRUITPi) or any device which can run Debian and has one or more wifi interfaces.

Finished devices can be of several types:

Kinds of mesh nodes[edit]

sudomesh envisions two types of nodes: "home" nodes and "extender" nodes. Home nodes are "first class" nodes; they can operate independently of another device, while "extender" nodes are attached to a home node and extend its range.

An Outdoor node is one which can be left outside in a weather-proofed enclosure, perhaps with independent power generation and storage (like a small solar cell and battery).

A Grid node lives indoors and plugs into the wall. It may or may not have its own energy storage (Uninterruptible Power Supply).

Nodes transfer packets either within a given network (switching) or between two or more networks (routing).

A "switching" node does not necessarily need to run a routing protocol. An IPv6 switching node will need either a DHCP client or neighbor-discovery client, in order that it may configure itself for the network it will join.

A "routing" node will need to run a routing protocol daemon. In IPv6 this will usually be radvd (plus batmand for BATMAN networks.) cjdns is an all-inclusive network stack, so no routing nor switching software needs be added to it. Optionally it may connect to Internet service. The Internet-connected interface, if any, should be configured as a Tor relay node for one more of the networks. That is, all Internet access from the provided networks will be via Tor, and hosts on the provided networks will not be exposed to the Internet except via Tor (in order to prevent port scanning and other automated shenanigans, and to protect node owners who choose to share their Internet connections with their network from consequences incurred by the actions of other network users.

Set up hardware[edit]

First you will need to verify that your radio supports mesh mode or IBSS mode. These two modes are the new version of what used to be called "Repeater" and "Ad Hoc" modes. No mode called "Ad Hoc" exists any more in the
in Jessie still supports Ad-Hoc mode. uses the mesh / IBSS terminology, so this guide will standardize on that.

The difference between the two modes[edit]

From the
man page:

The mode can be Ad-Hoc (network composed of only one cell and without Access Point), Managed (node connects to a network composed of many Access Points, with roaming), Master (the node is the synchronisation master or acts as an Access Point), Repeater (the node forwards packets between other wireless nodes), Secondary (the node acts as a backup master/repeater), Monitor (the node is not associated with any cell and passively monitor all packets on the frequency) or Auto.


Once you have verified that your radio hardware supports the requisite mode, you must ensure that the correct firmware is installed to make it work properly. Some radios will still work with limited functionality without the correct firmware file installed, which can be confusing.

Kernel module / driver[edit] contains a list and feature matrix of available kernel modules.

Of course, your system should detect and use the correct kernel module on its own; use
to check once you have verified the correct chipset ID of the radio hardware using lspci / lsusb as appropriate.

Choosing and installing a mesh routing program[edit]


CJDNS is an all-in-one networking stack authored mostly (entirely?) by Caleb James Delisle (cjd, not to be confused with djb). It offers a host of excellent features such as end-to-end encryption, zeroconf, and other nice things. It has a strange build system (nodejs - based, but not one of the existing node libs for this purpose) and can be difficult in deployment. Joining a cjdns mesh requires interaction with a human being to acquire a key. To my knowledge cjdns is not packaged for any Linux distribution.


Optimized Link State Routing Daemon is packaged in Debian.


Babel is the routing protocol developed by HacDC's Byzantium project.


Better Approach to Mobile Ad-Hoc Networking is a project related in some way to FreiFunk.

BATMAN works only with ipv4 and has other limitations, which is why batman-adv exists.




From the BATMAN FAQ:

What is the batgat kernel module good for?

The batman daemon maintains a tunnel connection to every "batman internet client". Every packet that goes to the internet or comes back has to go through this tunnel. As it is a user space tunnel a lot of copying between user space and kernel land is necessary. Depending on the number of clients and the CPU power available this might be a bottleneck. The batgat kernel module tries to overcome this limitation. Once loaded the batman daemon will detect its presence automatically on startup. The daemon will activate the kernel module to let it handle the tunneling, hence avoiding the expensive copy operations. There is no difference between the daemon tunneling and the kernel tunneling other than that.


batctl is the command-line interface to batman-adv.


Most recent release as of this writing:

Setting up the device[edit]

The sample configuration[edit]

The first iteration of these instructions are written as I set up a group of radios to participate in a local mesh.

Each of the radios in this initial mesh will have identical configuration, as I intend to deploy them via Ansible or similar. The scripts will be available to download from this website or from a git repository with URI to be added here later.

  • OS: Debian stable (jessie)
  • Routing protocol: batman-adv with a publicly-routable ipv6 prefix which I have available.
  • Services: radvd, sshd, tor
  • Name service... tbd

Preparing the interface[edit]


Once batman-adv is up and running, a device called bat0 will be available in the output of `ip add show` or similar.

After you have verified that this is the case you can run `batctl` to configure the device, find a mesh to which to connect, and to effect the connection.

Adding the interface to the mesh[edit]

Setting up services[edit]

When you have verified that the