DebianWRT - Debian Wiki (2023)

The goal of the DebianWRT project is to support running Debian on access points, such as those supported by the OpenWRT project. See the OpenWRT hardware table for a list.

These access points are an attractive target for Debian because they are increasingly powerful machines sold extremely cheaply as commodity hardware. Everyone needs an access point, so why not run Debian on it and add mipsel to your collection of architectures? OpenWRT is a fine replacement firmware for these devices, but it's not Debian, and for some of us that's reason enough to put Debian on these machines.

Currently the most common methods used to run Debian on these systems is to install OpenWRT or a similar firmware, add disk space either by USB storage or NFS, create a debian chroot by either running cdebootstrap from inside OpenWRT or debootstrap --foreign on a PC, and running Debian from this chroot. For example, instructions for the WLHDD.

A working Debian chroot can also be used as a root file system in OpenWRT, as explained in InstallingDebianOn/D-Link/DIR-825. In this approach the OpenWRT preinit mounts the chroot, calls pivot_root and runs Debian init. The resulting system is pure Debian, except for the OpenWRT kernel.

Yet another approach to explain how to use Debian on hardware supported by OpenWRT is explained here. It provides a mipsel kernel image and a base filesystem, so even a non-advanced user can easily use it. More advanced users will find how to create a kernel and a base filesystem on their own.

We'd like to be able to just boot up the DebianInstaller and install Debian more or less as normal, with some additional step to cram the Debian system down to a usable system that can run from flash with the disk disconnected, perhaps based on a technology like flashybrid or the adsrootbuilder. In this best of all worlds scenario, you have a full Debian system when you want it, and an embedded access point when you need it, and upgrading/maintaining the access point is not a separate process from upgrading the Debian system

The first tricky part is that for nearly all the access points in the TableOfHardware, the wireless driver is a binary kernel module, which needs a 2.4 kernel. OpenWRT's kernel includes a shim module to allow this binary module, built for an old 2.4.2x kernel, to run with 2.4.31. Plus lots of other patches.

Getting this kernel into Debian would be a lot of work and pretty hard. At least for the first pass, using the OpenWRT kernel seems like the easiest approach.

Various approaches could be used to install Debian using the DebianInstaller. Of course we don't really have to use d-i to install to these machines, it would only be convenient and nice for consistency if we can.

takeover

Similar to debtakeover, replace the running OpenWRT or other firmware with the files we need to boot Debian from disk. Preserve the kernel and kernel modules and use those in the installed Debian system.

It might work like this: Install OpenWRT, then add an ipkg source on a Debian mirror and, "ipkg install debian-installer", which depends on all available kernel module packages for OpenWRT and installs a DebianInstaller chroot, which is then chrooted into and the Debian installation proceeds as usual. At the end the OpenWRT system is modified to boot the installed Debian system.

Advantages of this method:

• The access point keeps on functioning as an access point throughout the whole installation process! You can keep surfing the net while your AP installs Debian.
• You can drive the installer from the very beginning as you're already logged into OpenWRT.

• Debian would only need to distribute the debian-installer ipkg, which would contain only free software and could be provided as just another DebianInstaller image.

• In the very short term, I can develop an installer for my AP without depriving the whole ?OldenBurg conference of it too... -- JoeyHess

Disadvanatages:

• Changes to OpenWRT can break the installer.
• Really needs a firmware that uses jffs2 or another fully writiable root filesystem. Systems using RO filesystems or symlinks, etc can't be completly wiped.
• You have to flash OpenWRT or another firmware first, so there's a two step installation process with a new system (OpenWRT) to learn in the middle.
• OpenWRT running means more memory used by its programs. Unless they're killed. It's doubtful d-i can run on some of the lower end models anyway, so that can be a problem.
• If OpenWRT is in flash then d-i cannot (partially?) run itself from flash, (unless it blows OpenWRT away at the beginning of the install), which means that much less ram is available for the installer.

This method will work for install on 32 mb machines, but squeezing it onto 16 mb machines would be very tough.

clean install

Put together the OpenWRT kernel and modules and tiny little system (possibly based on DebianInstaller) and create a firmware image which does nothing except go out and find the media containing the real installer, and run the installer from USB or NFS. Then the installer, still blind, has to bring up networking and ssh, and a dhcp server.

Then you connect to the access point and use network-console to complete the installation. At the end an initrd type image is generated and written to flash to boot Debian.

Advantages:

• Quite a lot cleaner. If in the future the kernel issues get sorted out it could be a quite normal Debian target.
• No dependencies on OpenWRT besides needing their kernel for now.

Disadvantages:

• Quite different from rest of d-i.
• Relatively difficult to get a working firmware image, and this dificulty will need to be repeated for each new access point model.
• Have to support users flashing the firmware too, which is pretty tricky.
• The firmware image would contain non-free and/or non-Debian kernel stuff and so could not be part of Debian.

• DebianInstaller has to run blind until network-console comes up, which has plenty of potential for failed installs.

second-stage bootloader

Write a little bootloader that can be flashed in and that just accesses a USB storage device and boots linux from it. Solves all size issues, generally a very nice approach, but does require some rather low-level mips hacking.

chrooted system

Create an alternative Debian root in external drive and keep OpenWRT running in internal drive.

Install regular OpenWRT on internal flash (kernel + root image). Create a debian instalation in USB drive via debootstrap, create init scripts in OpenWRT to mount the USB drive, create the chroot (and mount /proc, /dev etc. inside chroot) and execute init scripts of chrooted system (an special runlevel for example).

• Optional: mount internal flash inside chroot to access to OpenWRT files from Debian.
• Optional: keep OpenWRT services on alternative ports (for example dropbear ssh access to OpenWRT on port 23 and OpenSSH access to Debian on port 22).
• Optional: shutdowns from Debian require a method to trigger a clean shutdown from OpenWRT (for example a daemon on OpenWRT that receives a signal from Debian and launch shutdown on OpenWRT)

Advantages:

• The access point keeps on functioning as an access point throughout the whole installation process! You can keep surfing the net while your AP installs Debian.
• Keep OpenWRT functionally, better for maintenance/failover if USB crashes or instalation is not completed.
• Use of specific drivers/modules/daemons/configurations from OpenWRT while keeping all Debian posibilities.

Disadvantages:

• You have to flash OpenWRT first, so there's a two step installation process with a new system (OpenWRT) to learn in the middle.
• The instalation of Debian chroot is a manual process (no debian installer) and there is no standard scripts to switch to chroot.
• OpenWRT running means more memory used by its programs.

Note: this installation has been done with success in a Linksys WRT160NL.