Babel

Homenet tutorial

This document describes how to set up a Homenet network. It has two independent parts:

Setting up a Homenet router using OpenWRT/LEDE and hnetd

Setting up a Homenet router using OpenWRT/LEDE is easy — most of the hassle is in installing the OS. You don't need IPv6, a NATed IPv4 address is good enough for hnetd.

LEDE is a promising recent fork of OpenWRT. At the time of writing, the two systems are equivalent for most purposes.

Rich Brown has written a more friendly tutorial partly based on this one. Please consider following this friendly Homenet on LEDE tutorial.

Install OpenWRT or LEDE

Get yourself an OpenWRT-capable router with at least 16MB of flash and 32MB of RAM. I am very happy with the WNDR3700v2 (careful about the exact version!) and the WNDR3800 which should be easy to find second-hand. If you find an old Asus WL-500GP, that should be fine too, although it doesn't do IEEE 802.11n. Both models have a tftp client built into the bootloader, which makes them easy to reset if something fails. Before you go shopping, please check the OpenWRT table of hardware. Don't overdo it — most cheap models are just fine if they have enough flash and RAM.

Install the latest OpenWRT snapshot or LEDE snapshot; check the generic instructions and the instructions for your exact model in the OpenWRT table of hardware. Reboot your router, cross fingers, and perform the first login (set up a root password). Logout and log back in, this time using ssh. Perform basic config, notably wireless setup.

At this point, you should have a basic IPv4 NAT box and IPv6 router working. Reboot and test your installation.

Install some random utilities

The default OpenWRT installation is somewhat minimalistic. If you have enough flash, you will want to install some useful utilities:

opkg update
opkg install tcpdump strace diffutils

or even

opkg update
opkg install tcpdump strace diffutils less vim

You can check the list of available packages by doing opkg list.

Recommended: unbridge your router

By default, OpenWRT bridges all of the non-WAN interfaces in software (LAN and wireless). This is not optimal for Homenet, since it causes multicast spam and prevents Babel from making smart routing decisions. You will therefore want to set up your router so that the box performs routing, not switching, between the interfaces. This step is optional, but recommended.

Unbridging is described in Routed AP. That page assumes that you have just one wireless interface; if you're using a two-radio router, you will need to perform the procedure for each radio. Contrary to what this page says, you don't need to set up a new firewall zone for each interface — just add the new interfaces to the "lan" firewall zone.

(It is also possible set up each of the "LAN" plugs on your router to behave as a separate interface. Since this requires low-level tweaks to the embedded switch, I don't recommend it for a first installation. If you're ambitious, check out the OpenWRT switch documentation.)

Reboot and test your installation. You should have Internet access (at least IPv4) from each interface. Make a backup of the /etc/config directory for future reference.

Reconfigure your router to run Homenet

Install the hnet-full metapackage:

opkg update
opkg install hnet-full

Now edit the /etc/config/network file:

vi /etc/config/network

and, for each interface that you want to participate in Homenet, change “proto dhcp” or “proto static” to “proto hnet”.

(For the full experience, it is recommended to rename the interfaces to something like hnet0 and hnet1, since the default wan and lan have the side effect of disabling edge discovery. For a first install, however, this is not necessary.)

Reboot. Restart DHCP and SLAAC on your client — you should get a Homenet IPv4 address now (in the 10/8 prefix). If you lock yourself out, you can probably log in using a link-local IPv6 address in order to fix things:

ping6 -Ieth0 ff02::1
ssh root@fe80::what:ever%eth0

Optional: add a tunnel

If you don't have native IPv6, or if you wish to experiment with multiple IPv6 providers, you will want to setup a tunnel. Set up a tunnel as described in the OpenWRT network documentation, then tell OpenWRT to let hnetd manage it:

config interface whatever
    ...
    option proto 6in4
    ...
    option delegate 0

and finally tell babeld to announce it on the network: add the following to /etc/babeld.conf:

redistribute ip ::/0 le 0 src-ge 48 allow

(That's /etc/babeld.conf, babeld's native configuration file, not /etc/config/babeld, which is the OpenWRT-specific file. This could be done in either, but I prefer babeld's native syntax.)

Setting up a Homenet router using shncpd

Unlike hnetd, which has a number of dependencies, shncpd only depends on babeld, libbsd and the ip command-line utility. This makes it easy to install on any Linux box.

Shncpd is early experimental software, and some things may break. You get to keep both pieces.

In this section, I assume a laptop running Debian with interfaces eth0 and wlan0. Any Linux box should do, though, Fedora, Alpine, Ubuntu, whatever. (Please contact me if you wish to help with porting to BSD Unix.)

Install babeld and shncpd

sudo apt-get install build-essential libbsd-dev
git clone https://github.com/jech/babeld
(cd babeld && make && sudo make install)
git clone https://github.com/jech/shncpd
(cd shncpd && make && sudo make install)

Alternatively, you may install babeld from your distribution's package repository. If you do, please check that the version is recent enough (babeld-1.6.1 and later should be fine).

Kill Network Manager

Kill Network Manager, and anything else that can interfere with the networking setup. (If you don't, things may appear to work at first, but Network Manager will take revenge later.)

Set up the link layer

Pull an Ethernet cable between your laptop and one of the LAN ports of your OpenWRT router, or between your laptop and another Linux machine, and say:

sudo ip link set dev eth0 up

You should see a link-local IPv6 address appear; if you don't, check the status of the Ethernet carrier:

ethtool eth0 | grep Link

Setting up the wireless interface to act as a proper access point is not supported by most laptop hardware, the simplest workaround is to set it up in IBSS mode:

ip link set dev wlan0 down
iwconfig wlan0 mode ad-hoc
iwconfig wlan0 essid "homenet42"
ip link set dev wlan0 up

Again, you should see a link-local IPv6 address appear on the interface.

Run babeld and shncpd

Run babeld, telling it to redistrbute the routes installed by shncpd and nothing else:

sudo babeld -c /dev/null -C 'redistribute local deny' -C 'redistribute proto 43 allow' eth0 wlan0 &

Now run shncpd. If you've got an OpenWRT router somewhere in the network, no further configuration is needed:

sudo shncpd eth0 wlan0 &

If, on the other hand, your whole network runs shncpd, you need to choose one of your routers to act as an "edge router", and tell it to delegate some prefixes to the network:

sudo shncpd eth0 wlan0 -E 10.0.0.0/24 -E 2001:db8:1234:/48 -N 2001:db8:42::53

Shncpd uses the official IANA assignments for HNCP. In order to interoperate with older versions of hnetd, you must specify the port number and multicast group with -p 8808 -m ff02::8808

You can dump either deamon's status by sending it a SIGUSR1 signal:

sudo killall -USR1 babeld
sudo killall -USR1 shncpd

Both deamons have manual pages — if everything else fails, read the documentation.

Known limitations of shncpd

Please see the shncpd page for a list of limitations of shncpd. We're working on it, but don't hold your breath.