Building a BeagleBone router

A few months ago we decided to set up our own network in our coworking space, since we had no chance to apply any configurations to the official WiFi. Luckily I still had an old hub we could use, but we also needed a bridge from our network to the public WiFi. Until now we’ve used an old barebone for that, but I always thought that this solution was a bit oversized.

That was probably the reason why I came up with the idea to use a BeagleBone as a router when it crossed my way during some hardware testing we did for a new project. The BeagleBone seemed like a perfect fit: It is small but powerful and has all connectors we need (if we use an USB WiFi dongle). Unfortunately the way to a perfect router was not as straight as I thought in the first place, but in the end everything worked out.

1. Overview

First of all I want to give you a general overview over the initial hardware setup:

  • Computer with Debian Linux
    • WiFi: Internet
    • Ethernet: local network
  • BeagleBone Black Rev. C
    • WiFi USB dongle
    • Ethernet: local network
  • Required during installation:
    • 2GB MicroSD card

Since my computer is connected to the internet and to the local network, I can share the internet connection of my computer with the Beagle Bone until it’s able to connect to the internet by itself via WiFi.

2. Prepare the image

We need the latest Debian image on the fixed storage (eMMC) of the BegleBone in order to get the router working properly. The reason for this is the fact that the HDMI Cape of the BeagleBone interferes with compact WiFi dongles. Therefore the HDMI cape has to be disabled and according to my research the only way to do this is to use Linux 3.8.x and a system that resides directly on the eMMC.

The eLinux Debian images for the BeagleBoard should fit our requirements. However, the default image only works if loaded directly from the microSD card, so we have to use one of the eMMC Flashers images. I’ve used the BBB-eMMC-flasher-debian-7.8-console-armhf-2015-03-01-2gb image in this tutorial.

Run the following commands to download and extract the flasher image and write it on the microSD card:

apt-get install wget xz
xz -dv BBB-eMMC-flasher-debian-7.8-console-armhf-2015-03-01-2gb.img.xz
dd if=BBB-eMMC-flasher-debian-7.8-console-armhf-2015-03-01-2gb.img of=/dev/sdX

In the last line /dev/sdX should point to your SD card device (/dev/sdc in my case). Copying the image data to the SD card might take a while, but you can press CTRL+T to see the progress.

3. Configure the image

I assume that your local network has no DHCP server yet, therefore some extra configuration is required before we’re ready to copy everything on the BeagleBone. To get the configuration right we also need some additional information:

  • The IP address of the BeagleBone in the local network (e.g.
  • The IP address of your computer in the local network (e.g.
  • The subnet mask of the local network (e.g.
  • The broadcast address of the local network (e.g.

The IP address of the BeagleBone can be chosen freely (within the limits of your local network). All other information you should get from a simple ipconfig call or from the network preferences dialog of your OS.

Now it’s time to mount the SD card and edit the config files!

mkdir -p /mnt/bonesd && mount /dev/sdX /mnt/bonesd

First we replace the default eth0 DHCP configuration with a static IP version in /mnt/bonesd/etc/network/interfaces:

auto eth0
iface eth0 inet static

Second we add Google’s public DNS server to /mnt/bonesd/etc/resolv.conf:


Now we’re almost ready. The last edit disables the HDMI cape to prevent unstable WiFi connections. Add the followng line to /mnt/bonesd/boot/uEnv.txt


That’s it for now. If you’re unsure how to edit the file you could take a look at this GIST, which contains the full versions of all modified config files.

The final step is to unmount the SD card and put its content on the BeagleBone:

umount /mnt/bonesd && rm -r /mnt/bonesd

You can now put the SD card into the BeagleBone and switch it on to copy the Debian system from the card to the eMMC. The LEDs will flash to show that the copy process is running. When everything is done the BeagleBone will be shut down automatically. You can now remove the SD card and switch it on again.

4. First steps on the BeagleBone

You should now be able to log into the BeagleBone via SSH:

ssh root@

After that you should see a prompt like root@beaglebone:~#. If the login fails you most probably made a mistake in your network configuration and you should start over with step 2.

If everything went well, you should route all network traffic that reaches your computer via Ethernet to the WiFi connection. This way your computer acts as an internet router for the BeagleBone. Just run the following commands on your computer as root and the routing should work:

sed -i 's/#\(net.ipv4.ip_forward=1\)/\1/' /etc/sysctl.conf
sysctl -p
iptables -t nat -A POSTROUTING -o wlan0 -j MASQUERADE
iptables -A FORWARD -i wlan0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A FORWARD -i eth0 -o wlan0 -j ACCEPT

Keep in mind that these commands are for Debian based systems and that the names of the network interfaces (eth0, wlan0) might be different on your computer.

You can now test the internet connection by switching back to the BeagleBone prompt and typing:


If both pings were successful you can go on with the next step. If the first ping fails the whole routing process is still not working (or Google is down ^^). If the second ping fails only the DNS configuration is broken. Either case this more detailed routing guide might be of some help.

5. Securing the BeagleBone

You should now have a BeagleBone with SSH access and a connection to the internet. Use SSH to log in as root on the BeagleBone make sure that all software packets are on the latest version:

apt-get update
apt-get upgrade

Apart from updating the software packages you should also install a NTP service to ensure that the system clock has the correct time:

apt-get install ntp

Afterwards you should generate fresh SSH keys for your BeagleBone since keeping the ones shipped with the image would be a massive security hole:

rm /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server

Protecting root and the debian account with new passwords is also a good idea:

passwd root
passwd debian

When evertyhing is done you should close the the SSH session and re-login again:

# back on your computer
sed -i~ '\||d' ~/.ssh/known_hosts
ssh root@

Deleting the BeagleBone entry from your known SSH hosts (line 3) is necessary since you’ve generated new SSH keys. If the host would still be known SSH would fail due to unexpectedly changed keys.

6. WiFi dongle

When you’re back at the BeagleBone prompt you can plug in your WiFi dongle and check if it’s recognized by the system:

apt-get install wireless-tools wpasupplicant

If the iwconfig output shows an interface named wlan0 you’re lucky: The system has already the required drivers and you can continue with step 7. If you only see no wireless extensions you have to compile the driver module by yourself.

The latter was the case for my TP-Link dongle. I will show the steps required to get it working here as an example. Specific steps might be different for your hardware, but the general procedure should be similar.

Compile the RTL8188EU driver

First of all you have to install the tools required to compile your own kernel module:

apt-get install build-essential linux-headers-3.8.13-bone70 git

You can then download and compile the module sources:

git clone git://
cd rtl8188eu

Now the module is ready to be installed and loaded into the kernel:

make install
modprobe 8188eu

Test if your WiFi dongle is now recognized by the system:


You should now see the network interface wlan0.

7. Configure the WiFi network

Now it is time to actually connect your BeagleBone to the internet. Therefore you have to create a wpa-supplicant configuration file for your network at first:

wpa_passphrase SSID PASSWORD > /etc/wpa_supplicant/wlan0.conf

The fields SSID and PASSWORD have to be replaced with the correct values for your WiFi network of course.

Then you can add the WiFi interface to /mnt/bonesd/etc/network/interfaces:

allow-hotplug wlan0
iface wlan0 inet dhcp
    wpa-conf /etc/wpa_supplicant/wlan0.conf

You should also remove the gateway of the Ethernet interface in the same file:

sed -i 's/\(gateway\)/#\1/' /etc/network/interfaces

Afterwards you can restart the eth0 interface and the activate the WiFi connection:

ifdown eth0 && ifup eth0
ifup wlan0

Test if the WiFi network is working:


You should see the wlan0 interface with an IP address (inet addr).

8. Configure IP forwarding

If you’ve made it until here, you’re almost done. The last thing you have to do is to set up the actual routing. The iptables configuration is the same like in step 4:

sed -i 's/#\(net.ipv4.ip_forward=1\)/\1/' /etc/sysctl.conf
sysctl -p
iptables -t nat -A POSTROUTING -o wlan0 -j MASQUERADE
iptables -A FORWARD -i wlan0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A FORWARD -i eth0 -o wlan0 -j ACCEPT

Unlike on your computer the iptable rules on the BeagleBone should be permanent. Therefore the iptables-persistent service has to be installed:

apt-get install iptables-persistent

Just say “yes” when you’re asked if you want to store the current IP4 and IP6 rules.

9. Setup the DHCP service

A full-featured router should also act as a DHCP and DNS server for the local network. Lucily the dnsmasq packages provides both services at once:

apt-get install dbus dnsmasq

After the installation dnsmasq can be configured and restarted:

sed -i 's/^#interface=$/interface=eth0/' /etc/dnsmasq.conf
sed -i 's/^#dhcp-range=,,12h$/dhcp-range=,,12h/' /etc/dnsmasq.conf
service dnsmasq restart

The first line tells dnsmasq to listen only on the Ethernet to prevent the local DNS or DHCP from disturbing the DNS or DHCP of the WiFi. The second line activates the DHCP service. The IP addresses between and will be assigned to clients, which connect to the network. Remember to change these IP addresses, if you’re using another configuration for your local network (line 2).

10. Congratulations

Yay – you’ve made it! Your BeagleBone router should be set up and ready to work. To test it you can active DHCP for your local network on your computer and deactivate the WiFi network. After a few seconds your computer should get an IP address from the BeagleBone. To test the internet connection just type:


The first hop should be the IP address of your BeagleBone; the second the address of the WiFi router. After a few hops more the IP address of should be reached.

6 thoughts on “Building a BeagleBone router”

  1. Can I use it also to connect a usb hdd/ssd to the beagle bone and set it up to run a plex server?

Leave a Reply

Your email address will not be published. Required fields are marked *