DebianOn is an effort to document how to install, configure and use Debian on some specific hardware. Therefore potential buyers would know if that hardware is supported and owners would know how get the best out of that hardware.
The purpose is not to duplicate the Debian Official Documentation, but to document how to install Debian on some specific hardware.
AKA How to run Debian on a router with an OpenWRT kernel
D-Link DIR-825, hardware revisions B1 and B2. Possibly also other routers which have a working OpenWRT kernel, enough memory and a USB port.
The DIR-825 is a wireless router with a 680 MHz MIPS core, 64 MiB RAM, 2 USB buses, 5 ethernet ports and 2 wireless interfaces. It has enough power to work as a small server in addition to routing network traffic. Potential applications are backup storage, network drives, USB printers, IRC screens, torrents etc.
The Debian MIPS port1 however does not have kernel support for this hardware, but fortunately OpenWRT2 does. This guide will show how to install a Debian root file system on a USB drive and how to boot into it using the OpenWRT version 12.xx (Attitude Adjustment) preinit system as a kind of bootloader.
The type of installation described here is likely to work with other OpenWRT supported routers, as long as they have enough memory and some way to access larger storage volumes (i.e. USB).
Boot Standard Kernel:
2 Ethernet interfaces (Atheros AG71xx):
USB drives ok
Ethernet switch (Realtek RTL8366S)
2 WLAN interfaces (Atheros AR9280 Rev:2)
= OK ; Unsupported(No Driver) ; = Error (Couldn't get it working); [?] Unknown, Not Test ; [-] Not-applicable
= Configuration Required; = Only works with a non-free driver and or firmware
This Debian installation is based on the OpenWRT kernel and preinit system. Install OpenWRT on your router and make sure it works before attempting to install Debian. A working and configured OpenWRT system on the internal flash also works as a backup. If the USB drive containing the rootfs breaks, you will lose your Debian server, but at least the network routing still works with OpenWRT. Remember backups.
There is a good chance that the Debian rootfs you are going to set up here does not work straight away (i.e. the network does not come up after first boot), in which case you have no access to the router (also known as bricking). It is recommended that you either solder a serial interface to your router to access the console or at least know how to access and use the OpenWRT failsafe mode BEFORE you start modifying your router firmware.
Build a custom OpenWRT image
The DIR-825 does not have a floating point unit (FPU) in its MIPS CPU. The binaries in the Debian MIPS port1 use FPU instructions, so the kernel needs to have an FPU emulator. OpenWRT on DIR-825 defaults to softfloat binaries, so its kernel does not contain the emulator by default. Therefore we need to compile a custom version of OpenWRT in order to use Debian binaries.
Installation and usage of the OpenWRT build system are described in OpenWRT wiki. After the SVN checkout and feed update, you need to configure the build to contain the necessary features.
Start menu based configuration in the build directory:
Set the following options
Target System -> Atheros AR7xxx/AR9xx
Target Profile -> D-Link DIR-825 rev. B1 (rev. B2 also works fine with this)
Base system -> busybox -> Archival Utilities -> ar (needed for unpacking .deb files)
If you want to use any OpenWRT packages above the bare minimum included in the default configuration (like LuCI, exotic kernel module packages, etc.), it is better to enable them in your custom build. Opkg packages from the official OpenWRT repositories can be installed, but in practice they can have subtle bugs due to the customization used here and small version mismatches.
Finish configuration and start kernel configuration:
Set the options
Enable FPU emulation
- If you want to enable other unusual kernel modules or options, do it now. Defaults usually work fine though.
Check the kernel configuration, the following options should be defined in build_dir/linux-ar71xx_generic/linux-3.3.8/.config
Compile OpenWRT (this takes a while):
New images will be in bin/ar71xx/. Packages suitable for installation with opkg are in bin/ar71xx/packages. If you can put this directory online via a webserver, you have an instant custom OpenWRT repository. Edit /etc/opkg.conf to use it.
Upgrade your router with new images.
Check that your new router firmware works and configure the router to handle your basic networking setup.
Get a USB (flash) drive and make a swap partition and an ext4 partition for Debian root FS on it (min. 1 GB for root, 256 MB for swap).
Configure OpenWRT for USB storage. Use the block-mount opkg package and its configuration file /etc/config/fstab. The required kernel module packages, like kmod-usb-storage and kmod-fs-ext4 should also be installed. You can use the kernel module packages from the official OpenWRT repos, but the installation with opkg needs to be --forced, since we are using a custom kernel with a mismatching version hash. The modules should work fine despite this, if you did not deviate too much from the default configuration.
You should now have a working configuration for mounting the USB partition (under /mnt for example) and having the swap turned on.
Install and run debootstrap. If your OpenWRT installation does not have ar you also need to install binutils:
opkg install debootstrap binutils
OpenWRT debootstrap is buggy, so you need to copy the file devices.tar.gz from another Debian system to the router:
scp /usr/share/debootstrap/devices.tar.gz root@my-router:/usr/share/debootstrap
debootstrap --arch=mips wheezy /mnt/ http://ftp.de.debian.org/debian
Initial Debian rootfs configuration
Check that the Debian rootfs works by chrooting into it and doing some basic configuration:
chroot /mnt /bin/bash
# install ssh etc.
apt-get install ssh wireless-tools vim tmux
# set up mount point for OpenWRT preinit root (IMPORTANT!)
# Put a hostname to /etc/hostname
echo my-router > /etc/hostname
# Setup basic networking on the ethernet switch interface eth0
cat <<EOF >> /etc/network/interfaces
> auto eth0
> iface eth0 inet static
> address 192.168.2.1
> netmask 255.255.255.0
Edit /etc/inittab and remove getty's on tty* devices (which do not exist on a headless router). If you have a serial console, enable it in inittab by adding this line
T0:23:respawn:/sbin/getty -L console 115200 vt100
Add the USB swap partition to /etc/fstab, otherwise you risk running out of memory during boot.
# <file system> <mount point> <type> <options> <dump> <pass>
/dev/sda2 none swap sw 0 0
OpenWRT extroot configuration
Set up the external root FS in OpenWRT. The configuration file /etc/config/fstab should have this kind of section:
option target '/'
option fstype 'ext4'
option options 'rw,sync'
option enabled '1'
option enabled_fsck '0'
option device '/dev/sda1'
The block-mount preinit scripts search for a file called /etc/extroot.md5sum in the external root file system and checks if it matches the file /overlay/.extroot.md5sum in the firmware flash. If it does not, the external rootfs will not be enabled, so you need to copy it to the Debian rootfs.
cp /overlay/.extroot.md5sum /mnt/etc/extroot.md5sum
The extroot scripts need to be modified slightly to allow Debian init to start without problems. Put this script to /lib/preinit/99_10_run_debian_init (so that it sorts second to last in the directory, before 99_10_run_init from block-mount).
[ -f /etc/debian_version ] || return 0
preinit_echo "- Debian init -"
kill $(pidof hotplug2)
if [ "$pi_init_suppress_stderr" = "y" ]; then
exec env - PATH=$pi_init_path $pi_init_env $pi_init_cmd 2>&0
exec env - PATH=$pi_init_path $pi_init_env $pi_init_cmd
boot_hook_add preinit_main run_debian_init
You are now ready to boot the router to Debian. Make sure you have a working serial console, or an ssh capable computer connected to one of the router switch ports and configured with an ip address in the correct subnet, 192.168.2.* if you used the network configuration above.
Internal flash partitions
The preinit system mounts the read-only squashfs part of the OpenWRT root file system under /rom. The modifiable part of the OpenWRT root fs (called overlay in OpenWRT) is a jffs2 file system in the fifth flash partition and can be accessed through the device /dev/mtdblock4.
In OpenWRT the root fs is created by combining /rom with the jffs2 overlay using overlayfs. In Debian the same can be achieved by creating the mount points /overlay and /openwrt-root and adding the following lines to /etc/fstab:
# <file system> <mount point> <type> <options> <dump> <pass>
/dev/mtdblock4 /overlay jffs2 ro 0 0
overlayfs /openwrt-root overlayfs lowerdir=/rom,upperdir=/overlay 0 0
Note that /overlay is mounted read-only (ro), which also makes the overlayfs mount read only.
The kernel modules are now available under the overlayfs partition in /openwrt-root/lib/modules.
Installing kernel modules with modprobe needs dependency information written to the module directory by depmod, so they need to be in a writable partition. You need to either mount /overlay and /openwrt-root read-write and link /lib/modules to /openwrt-root/lib/modules, or copy the modules to the Debian root file system. In any case,
needs to be run in order for modprobe to work.
If you want to install new kernel modules, you need to mount /openwrt-root read-write, chroot into it and install the necessary kmod-* packages with opkg.
The LEDs in DIR-825 can be controlled with sysfs, with the exception of the 4 ethernet switch indicator LEDs. The necessary drivers will be modprobed during boot, when these two module names are added to /etc/modules
The LED devices can now be controlled with files under /sys/devices/platform/leds-gpio/leds. If you install sysfsutils and add the following lines to /etc/sysfs.conf, the router looks a little less like a christmas tree than the default configuration.
class/leds/d-link:orange:power/trigger = none
class/leds/d-link:blue:planet/trigger = netdev
class/leds/d-link:blue:planet/device_name = eth1
class/leds/d-link:blue:planet/mode = link
class/leds/ath9k-phy0/trigger = netdev
class/leds/ath9k-phy0/device_name = wlan0
class/leds/ath9k-phy0/mode = link
class/leds/ath9k-phy1/trigger = phy1tpt
class/leds/d-link:blue:usb/trigger = usbdev
class/leds/d-link:blue:usb/device_name = 1-1
class/leds/d-link:blue:usb/activity_interval = 100
See the OpenWRT LED documentation for more details.
A normal home router provides a WLAN access point, bridges its LAN interfaces (eth0, wlanX) into a single network, serves DHCP to the local network and does Network Address Translation (NAT) when routing to the external network (WAN). The following will present a configuration which makes this happen with packages ifupdown, bridge-utils, dnsmasq and hostapd.
A basic /etc/hostapd/hostapd.conf
country_code=<your country code here>
ssid=<your access point name here>
wpa_passphrase=<your WPA2 passphrase here>
Here's a very bare bones, but working, configuration for DNSMasq, /etc/dnsmasq.conf.
The /etc/network/interfaces file of the ifupdown package controls the networking setup on a (non-gui) Debian system. The configuration below gets an IP address for the WAN interface (eth1) from DHCP, bridges the local network interfaces eth0 and wlan0, sets the local network address to 192.168.1.1, starts hostapd and enables NAT.
# interfaces(5) file used by ifup(8) and ifdown(8)
iface lo inet loopback
iface eth1 inet dhcp
iface eth0 inet manual
iface wlan0 inet manual
iface br0 inet static
bridge_ports eth0 wlan0
post-up /bin/echo 1 > /proc/sys/net/ipv4/ip_forward
post-up /sbin/iptables -t nat -A POSTROUTING -o eth1 -j MASQUERADE
# lspci -nn
00:11.0 Network controller : Atheros Communications Inc. AR922X Wireless Network Adapter [168c:0029] (rev 01)
00:12.0 Network controller : Atheros Communications Inc. AR922X Wireless Network Adapter [168c:0029] (rev 01)
# lsusb -v | grep -E '\<(Bus|iProduct|bDeviceClass|bDeviceProtocol)' 2>/dev/null
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
bDeviceClass 9 Hub
bDeviceProtocol 0 Full speed (or root) hub
iProduct 2 Generic Platform EHCI Controller
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
bDeviceClass 9 Hub
bDeviceProtocol 0 Full speed (or root) hub
iProduct 2 Generic Platform OHCI Controller