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 switch 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 wget https://rcn-ee.com/rootfs/bb.org/release/2015-03-01/console/BBB-eMMC-flasher-debian-7.8-console-armhf-2015-03-01-2gb.img.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. 192.168.222.2)
- The IP address of your computer in the local network (e.g. 192.168.222.100)
- The subnet mask of the local network (e.g. 255.255.255.0)
- The broadcast address of the local network (e.g. 192.168.222.0)
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 address 192.168.222.2 netmask 255.255.255.0 network 192.168.222.0 gateway 192.168.222.100
Second we add Google’s public DNS server to /mnt/bonesd/etc/resolv.conf
:
nameserver 8.8.8.8
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
cape_disable=capemgr.disable_partno=BB-BONELT-HDMI,BB-BONELT-HDMIN
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@192.168.222.2
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:
ping 95.168.222.108 ping google.com
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:
exit # back on your computer sed -i~ '\|192.168.222.2|d' ~/.ssh/known_hosts ssh root@192.168.222.2
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 iwconfig
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://github.com/lwfinger/rtl8188eu cd rtl8188eu make
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:
iwconfig
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 192.168.222.100\)/#\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:
ifconfig
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=192.168.0.50,192.168.0.150,12h$/dhcp-range=192.168.222.50,192.168.222.150,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 192.168.222.50 and 192.168.222.150 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:
traceroute google.com
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 google.com should be reached.