From Soekris Info Wiki

Revision as of 04:09, 19 January 2016 by Firas (Talk | contribs)
Jump to: navigation, search

This page assumes that you are familiar with operating a Soekris box, and describes the steps needed to install Debian 8 (codenamed "Jessie") on it. More precisely, it was how I installed it on my net4801. It can also be used, with some modifications, to install other versions of Debian or Debian derivatives (however be careful that Ubuntu requires a PAE-enabled processor starting with version 12.04).

There are two main methods to install Debian (and its derivatives) on systems which are unable to use traditional bootable installation media. The first, and most commonly used among Soekris users, is to boot from the network using PXE. The second is similar to how some other distributions such as Gentoo are installed: the base system is first loaded on the target installation media by connecting it to a pre-existing system (in Debian, this is done with the debootstrap tool), and the media is then transferred to the target system. The first solution may be simpler for beginners since the installer program is the same as that found on the traditional installation media, but on the other hand it requires an external PXE server for booting.

Here, I will only cover the first solution for now, but I may add the second one later (I do not currently have a CompactFlash reader to connect the target CF to another system).


Booting and installing by PXE

To boot and install an OS on your Soekris box by PXE, you will need an additional machine on your network to serve as a PXE server. A fast Internet connection is also desirable since everything will be downloaded from the Internet. Although many other pages on this Wiki describe how to setup a PXE booting server, I will still do it here for the sake of completeness (and to offer my personal perspective). Because the PXE server will also act as a DHCP server, it is best to temporarily disable all other DHCP servers on your network (in particular, the one on your Internet gateway if there is one).

Setting up the PXE server

I use Ubuntu 14.04 as my PXE server. Also, to minimise disruption, I like to use a VirtualBox virtual machine (available below as an OVA file) as PXE server: with the network interface of the virtual machine configured in "bridged" mode, it will behave as if it were another physical machine on the network. Since the server will act as the DHCP server on the network, its network interface must be configured with a static IP address, with an entry in /etc/network/interfaces similar to the following:

auto eth0
iface eth0 inet static

Install the packages isc-dhcp-server (which may be called dhcp3-server on older systems), tftpd-hpa, and openbsd-inetd. We will first configure the DHCP server; open /etc/dhcp/dhcpd.conf in a text editor. First, specify the DNS-related information which the server will send to the clients by editing those two lines (which are lines 16-17 on my machine):

option domain-name "";
option domain-name-servers,;

The domain name is generally not necessary, so you can comment this line out, and the name server line is self-explanatory. For me, it becomes:

#option domain-name "";
option domain-name-servers;

We can then use this template (lines 38-41) for the rest of the configuration:

#subnet netmask {
#  range;
#  option routers,;

For me, it looks like this:

subnet netmask {
  option routers;
  filename "pxelinux.0";

Again, all the options are self-explanatory: subnet and netmask specify the network we are operating on, range specifies the range of IP addresses which the DHCP server will assign to the clients, and routers is the address of the gateway. Finally, filename specifies the name of the PXE image for booting, more details about this later. Save the file and restart the DHCP server with

$ sudo service isc-dhcp-server restart

You can check that the DHCP server is running with

$ service isc-dhcp-server status

(if it is not running, it is probably due to a mistake in your dhcpd.conf or network configuration, for example if the server's IP address is not in the network specified in dhcpd.conf).

We will now configure the TFTP server. First look in /etc/default/tftpd-hpa to obtain the TFTP root directory (for me it is /var/lib/tftpboot). Then add the following line in /etc/inetd.conf:

tftp    dgram   udp    wait    root    /usr/sbin/in.tftpd /usr/sbin/in.tftpd -s /var/lib/tftpboot

(replace /var/lib/tftpboot with your TFTP root directory if it is different), and restart inetd with

$ sudo service restart openbsd-inetd

Finally, we will extract the installation files to the TFTP root directory. Those files are located in the netboot.tar.gz archive which can be found on the Debian FTP mirrors. For an i386 install of Debian Jessie, the file you want is

but you can replace jessie with, e.g., testing or sid to obtain the corresponding archive. Extract it to the TFTP root folder with

$ cd /var/lib/tftpboot/
$ wget -O-|sudo tar xz

We need to do some additional configuration for the boot process to operate on the serial line. First, add those two lines to pxelinux.cfg/default:

SERIAL 0 19200 0

(of course, replace 19200 with the speed of your serial line if it is different; 19200 is the default for Soekris boxes). Finally, in debian-installer/i386/boot-screens/txt.cfg edit the append line from this

append vga=788 initrd=debian-installer/i386/initrd.gz --- quiet

to this:

append initrd=debian-installer/i386/initrd.gz console=ttyS0,19200 --- quiet

(you may also remove quiet for a more verbose boot). We are now ready to boot and install. The boot process is well-documented on this Wiki (basically, press Ctrl+P to enter comBIOS, and type boot f0 at the prompt), and the installer is the same as with traditional installation media and is also well-documented (for example on the official Debian installation manual).

Pre-made virtual machine

For those interested, I have compiled a virtual machine file of my PXE server as configured above in OVA format, to use in VirtualBox (and possibly other virtualisation products). The file is here (compressed with lrzip, 467MB, the SHA-256 checksum of the decompressed OVA file is 9eb35c0ec9e22153f085269e5b0f3cfdcf9306a40f41a6bef6f7ec94cac35510).

The login name and password are both pxeboot (use sudo to get root), and SSH is listening. To change the keyboard layout (English is the default), run

$ sudo dpkg-reconfigure keyboard-configuration

Note also that in order to keep the file small, system updates have not been installed, and so it is recommended to install them before using the machine.

After the installation

The system, including GRUB, has automatically been configured to operate over the serial line, but for some reason the kernel is not run with the correct console parameter, so the boot messages are not visible. To fix this, edit the line GRUB_CMDLINE_LINUX in the GRUB configuration file /etc/default/grub from this:


to this:


After editing the file, run update-grub to apply the changes.

Installing with debootstrap


Personal tools