Mainline Debian HowTo

Jump to navigation Jump to search

This page describes bootstrapping Debian jessie with it's default (mainline) linux kernel (3.16) to create a SD-card with a clean (official) install. Based on the instructions on the official debian wiki

To summarize the process: Most work is the normal debian bootstrapping procedure. To make the SD-card bootable, we use a precompiled version of U-Boot provided by the Debian installer team. Tested on Cubieboard 1 and Cubietruck, should work on other boards, too.


  • The kernel comes without display drivers, so you won't get any display-output with this guide! Use UART or ssh to login.
  • The current Debian jessie kernels (3.16.7-ckt11-1 at the time of writing) do not support NAND yet, so only SATA and MMC/SD-card storage is supported.
  • We will use a recent version of U-Boot and device tree. The Allwinner-specific script.bin isn't needed anymore.

Using a ready-made installation SD card image instead of bootstrapping

If you are being lazy, then it is possible to download a bootable SD card image for A10/A10s/A20 based devices with the debian installer and write it to an SD card:

  xzcat 20141215-sunxi-bootsetup-prototype-v6.img.xz > ${card}

Then boot from this SD card and use a menu based installer, which is accessible on the UART serial console. Ignore warnings about the missing kernel modules. When asked about partitioning the SD card, any choice should be fine. But erasing the existing partition is probably the most clean and preferable solution (the installer itself is running from RAM and does not depend on any data from the SD card during the installation). At the end of the process, you should get a clean (official) installation of Debian, installed from the network. The mainline non-modified release of U-Boot v2015.01 is used as a bootloader.

Every part of this SD card image can be reconstructed from sources. The instructions are available at

And the 'official' debian installer initrd file is taken right from the debian website. This bootable SD card image just provides a bit more convenient deployment method instead of the TFTP or USB stick tricks from the wiki page. Refreshing the initrd file to a more up to date build is possible in the following way:

   gzip -d initrd.gz
   lzma initrd
   mkimage -A arm -O linux -T ramdisk -C lzma -a 0x43300000 -n "Debian Installer" -d initrd.lzma initrd-debian-netboot.lzma.uboot

And then replace the 'initrd-debian-netboot.lzma.uboot' file on the SD card with the newly generated one.

Supported devices: Cubieboard, Cubieboard2, Cubietruck, A10-OLinuXino-LIME, Mele A2000 and many others (which are yet to be tested).

Getting a cross toolchain

Refer to Toolchain. This is not needed if you do not intent to build U-Boot by yourself.

Creating a bootable SD Card with U-Boot

There are two options: Build U-Boot yourself or use the images provided by the Debian installer team.

Building U-Boot yourself

Mainline U-Boot works fine:

 git clone -b v2015.01
 cd u-boot
 make Cubietruck_config
 make -j$(nproc) CROSS_COMPILE=arm-linux-gnueabihf-

(Also refer to U-Boot#Compile U-Boot)

Downloading precompiled U-Boot images

Download the U-Boot image u-boot-sunxi-with-spl.bin.gz for your hardware from, i.e. for Cubieboard 1


or for Cubietruck


then unzip:

 gunzip u-boot-sunxi-with-spl.bin.gz

Setting up the SD-card

${card} is the SD device (ie /dev/sdc). ${partition} is the partition number (ie. 1). Exclamation.png Warning: This will delete the content.

 dd if=/dev/zero of=${card} bs=1M count=1
 dd if=u-boot-sunxi-with-spl.bin of=${card} bs=1024 seek=8

Create partition(s). ie one big partition beginning with sector 2048, type 83 (Linux)

 fdisk ${card}
 mkfs.ext4 ${card}${partition}
 mount ${card}${partition} /mnt

This will first clean the card (at least the first 1M), install the U-Boot bootloader you compiled/downloaded in the step before, and then you can create -for example- one partition, format it, and mount it to /mnt/ for use in the next steps.

(Also refer to Bootable_SD_card)

Bootstrapping Debian

This will bootstrap Debian stable (aka Jessie)

 qemu-debootstrap --verbose --include=${kernel},locales,flash-kernel,sunxi-tools,firmware-linux,debconf --arch=armhf --components main,contrib,non-free jessie /mnt

with ${kernel} being either linux-image-armmp for Cubieboard 1 or linux-image-armmp-lpae for Cubietruck. For Cubieboard 2, linux-image-armmp-lpae should be the correct kernel. You need to have the packages qemu-user-static and debootstrap installed.

If in doubt, have a look at the Debian wiki or the official documentation.

Configuring the system


We are going to use flash-kernel to generate the boot.src. Tell it which hardware we're aiming for. (Devices listed in: /usr/share/flash-kernel/db/all.db)

 mkdir /mnt/etc/flash-kernel/
 echo "Cubietech Cubietruck" >> /mnt/etc/flash-kernel/machine

or for Cubieboard 1 use

 echo "Cubietech Cubieboard" >> /mnt/etc/flash-kernel/machine

Kernel arguments:

echo 'LINUX_KERNEL_CMDLINE="console=ttyS0,115200 disp.screen0_output_mode=EDID:1280x1024p60 root=/dev/mmcblk0p1 rootwait panic=10 ${extra}"' >> /mnt/etc/default/flash-kernel

Kernel modules

Write extra modules that should be loaded at boot time to /mnt/etc/modules.

 echo "rtc_sunxi" >> /mnt/etc/initramfs-tools/modules

This module does not exist for the linux-image-armmp kernels, so it is not available for Cubieboard 1.

Base configuration files

 echo "/dev/mmcblk0p1  /           ext4    relatime,errors=remount-ro        0       1" > /mnt/etc/fstab
 echo "HOSTNAME" > /mnt/etc/hostname

Add your hostname to the and ::1 lines in /mnt/etc/hosts, e.g.

 nano /mnt/etc/hosts

Hint: Please consider using your favorite debian-mirror instead of

cat <<EOF > /mnt/etc/apt/sources.list

deb jessie main non-free contrib
deb-src jessie main non-free contrib

deb jessie/updates main contrib non-free
deb-src jessie/updates main contrib non-free

# jessie-updates, previously known as 'volatile'
deb jessie-updates main contrib non-free
deb-src jessie-updates main contrib non-free
cat <<EOF > /mnt/etc/network/interfaces
# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

# The loopback network interface
auto lo
iface lo inet loopback

# The primary network interface
allow-hotplug eth0
iface eth0 inet dhcp

Prepare Login

Remember: We won't have any display output, so we can eiter: spawn a login on the serial console:

 echo "T0:23:respawn:/sbin/getty -L ttyS0 115200 vt100" >> /mnt/etc/inittab

and/or use ssh. Since debian disabled root password-login in jessie, re-enable it:

 sed -i "s/^PermitRootLogin without-password/PermitRootLogin yes/" /mnt/etc/ssh/sshd_config

or copy your key:

 umask 077; mkdir /mnt/root/.ssh/ cat ~/.ssh/ >> /mnt/root/.ssh/authorized_keys

chroot and setup

Now chroot in to the new system and set everything up.

 mount -t proc chproc /mnt/proc
 mount chsys /mnt/sys -t sysfs
 mount -t devtmpfs chdev /mnt/dev || mount --bind /dev /mnt/dev
 mount -t devpts chpts /mnt/dev/pts
 echo -e '#!/bin/sh\nexit 101' > /mnt/usr/sbin/policy-rc.d
 chmod 755 /mnt/usr/sbin/policy-rc.d
 DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true LC_ALL=C LANGUAGE=C LANG=C chroot /mnt dpkg --configure -a

The next steps are executed inside the chroot:

   dpkg-reconfigure locales
   dpkg-reconfigure tzdata

Optional: Install U-Boot (U-Boot from debian is not used, but it does no harm and i'll include it for future reference)

   apt-get install u-boot u-boot-tools

Or, if you want simple frame-buffer support (on some cards) go with kernel >3.19. For this, you need to add experimental sources for apt:

   apt-get -t experimental install linux-image-3.19.0-trunk-armmp-lpae u-boot u-boot-tools

Install non-free firmware and add one currently missing file to the wifi-firmware (not for Cubieboard 1):

   apt-get install firmware-brcm80211
   wget -O /lib/firmware/brcm/brcmfmac43362-sdio.txt

Install a few other things:

   apt-get install console-setup keyboard-configuration openssh-server ntp

At this point, debian should have generated a kernel image /boot/vmlinuz-??? and an initrd /boot/initrd.img-??? for you. Generate the /boot/boot.scr, set a password and after a little cleanup you're set:

   passwd root


 rm /mnt/usr/sbin/policy-rc.d
 rm /mnt/usr/bin/qemu-arm-static
 umount /mnt/dev/pts && umount /mnt/dev && umount /mnt/sys && umount /mnt/proc && umount /mnt


Now you should be able to boot your brand new debian installation. Hopefully it'll boot, pull up networking and you're able to login via ssh.

Manual boot (serial console)

If it doesn't boot, you'll want an 3,3V USB UART module to debug. U-Boot seems to be powerful and gives helpful error messages. If it says something like 'CRC error' 'loading default environment', that's okay, we want default. (Side note: use the filesize variable or give the size in hexadecimal)

 setenv bootargs console=ttyS0,115200n8 disp.screen0_output_mode=EDID:1280x1024p60 root=/dev/mmcblk0p1 rootwait panic=10 ${extra}
 ext4load mmc 0:1 0x47000000 boot/dtb-3.16.0-4-armmp-lpae
 ext4load mmc 0:1 0x46000000 boot/vmlinuz-3.16.0-4-armmp-lpae
 ext4load mmc 0:1 0x48000000 boot/initrd.img-3.16.0-4-armmp-lpae
 bootz 0x46000000 0x48000000:${filesize} 0x47000000


Newer debian uses systemd by default. Beside activing ttyS0 there using

systemctl enable [email protected]

make sure your kernel has


Also note that semantic of 'halt' is not yet reestablished. Use 'poweroff' instead, meanwhile.


As of now it is possible to run Debian with a recent mainline kernel and only few changes to the system. We can throw away some of the crude, device-specific things like the modifications to the kernel, 'script.bin'... U-Boot is on the right track and Debian-installer will be usable on various sunxi-based systems, once a recent kernel arrives in the installer builds.

What's left to be done is:

  • Optimizing the system
  • Getting some/any graphics support

See also

External Links