Network boot with Debian

These are my notes on setting up diskless booting of a Via EDEN computer from an Ubuntu server. This should also work on a Debian server. The machines of relevance to this article are:

  • DHCP Server ( an existing server running an old copy of RedHat which is currently providing DHCP services to the existing local network
  • Boot Server ( A new machine running Kubuntu 5.10 “Hoary Hedgehog” which will contain the boot image and files
  • Client – The Via EDEN box which has no hard disk

Setting up the EDEN box to network boot

You’ll need to go into the BIOS settings by pressing the DEL key when you see the Via splash screen.

1. Go into Advanced BIOS Features and change the First boot device setting to LAN.

2. Go into the Integrated Peripherals section and enable the Onboard Lan Boot ROM.

3. Save your changes and reboot. It won’t work yet because we haven’t set up the server but you should see it try and fail to network boot.

Setting up DHCP for network booting

Since there is already a DHCP system installed here, I need to work with that since I do not think it would be a good idea to have two DHCP servers on the same network. So we will begin by adding the following lines to /etc/dhcpd.conf – don’t forget to change the IP and MAC numbers to ones appropriate for your own network:

allow booting;
allow bootp;

   filename "pxelinux.0";

   host stb00001;
      hardware Ethernet 00:40:63:E1:F9:76;

After modifying the file, restart the daemon. That should be all the changes I need to do on the RedHat box and I have not messed up normal DHCP operation for the other network users.

# service dhcpd restart

Setting up the boot environment

The Via box uses a network boot standard known as PXE. Debian has some packages to get a PXE boot going. Install the following packages:

# apt-get install syslinux tftpd-hpa nfs-user-server

Choose no when it asks if you want to launch tftpd from inetd.

Next set up the file /etc/default/tftpd-hpa to look like this:

#Defaults for tftpd-hpa
OPTIONS="-l -s /tftpboot"

Then set up a boot directory:

# mkdir /tftpboot

# chmod 755 /tftpboot

# cd /tftpboot

# cp /usr/lib/syslinux/pxelinux.0 ./

# mkdir pxelinux.cfg

Next set up the PXE configuration file. The configuration file name must be the IP of the client in HEX. The hex letters must be in uppercase too!

So for our test box at, the file would be /tftpboot/pxelinux.cfg/CB2341E8. Apparently you can also call this file /tftpboot/pxelinux.cfg/default but I haven’t tried that. Here are the contents of the file:

# PXE Configuration file for the DVC set top box.
# by Adam Pierce
# Command Systems Pty. Ltd. Australia

default dvc

label dvc
kernel dvc-kernel
append ip=dhcp root=/dev/nfs rw nfsroot=

At this point, you should be able to reboot the Via box and it should connect to the server and obtain its network settings. It should get as far as loading the OS and then fail with “Could not find kernel image”.

Set up the root file system

The operating system for the client will be stored in a directory on the server. Let’s create that directory now.

# mkdir /export

# mkdir /export/dvc

# mkdir /export/dvc/stbroot

# mkdir /export/dvc/stb00001

Fill this new directory with your root file system. In my case, I intend to run multiple clients at some point in the future so I have created two subdirectories called stbroot and stb00001. These will be mounted read-only and read-write respectively. The stb00001 directory will contain folders such as /tmp and /home which the client will need to write to and I can have a separate directory for each client on the network.

The root file system for the client can now be placed in stbroot:

# cd /export/dvc/stbroot

# tar zxvf MyRootFSWhichIPreparedEarlier.tar.gz

Set up the kernel

The client will need to load the kernel before it can mount the shared directories so the kernel will need to go in the tftpboot area. Just copy the kernel from your root file system (this is easy if you are using GRUB):

# cp /export/dvc/stbroot/boot/<name of kernel> /tftpboot/dvc-kernel

At this point, the client will be able to boot and load the kernel. You should see screenfuls of kernel messages and then it will say “Kernel panic: unable to mount root fs”.

Configure NFS

This is the final step before the client can be booted. The client will mount it’s drives over the network using NFS. Set this up in the /etc/exports file. It should look like this:

# /etc/exports: the access control list for filesystems which may be exported
#                 to NFS clients. See exports(5).

Then finally you can restart the NFS daemon and you should be good to go.

# /etc/init.d/nfs-user-server restart

Note that I have not discussed how to set up the root file system for the client. That can be a topic for another day.

18 thoughts on “Network boot with Debian

  1. Hi Adam,

    Great article, but I’m kind of stuck without knowing how to prepare the root filesystem I want to use. Can you point me in the right direction? I want to PXE boot some Via boxes with PVR-150s, running Debian 4.0 and VLC. Thanks.


  2. The easiest way is to get an old hard disk, put it into your Via box and install Linux onto it. The contents of the hard disk are now your root file system.

    Pull the hard drive out of your Via box and put it in your PC. Copy the data to the stbroot directory.

    You’ll also need to edit /etc/fstab to mount root via NFS.

    I have successfully done it this way.

    Alternatively, there is a Debian package called fai-client ( ) which supposedly automates the installation of diskless clients but I haven’t tried it.

  3. Great, thanks!

    In my case, the device has a CF to IDE adapter and I have a working version of exactly what I want to replicate, running off the CF card, I just want to remove the CF card and network boot the boxes.

    So essentially copy the contents of “/” to my tftpboot/stbroot, as is. No changes at all? :) Cool.

    Now what if I want to have 35 of these little beasts? I’m guessing some config files need to be truly localized and some network mounted?


  4. Thinking about this further, if I had a bunch of localized config information, I should be able to create /stbroot/IPOfMachine/localfiles on the NFS server and just mount each one of those unique directories based on the IP the box gets (which I’ll hard code in the DHCP conf). That should work, right?


  5. Yes, that should work just fine.

    There are also more complicated ways of doing it.

    I once had to set up a whole bunch of diskless clients and didn’t want to fill up the server’s disk with a dozen copies of the OS so I separated the files into stuff that could be shared (/bin, /boot, /usr and so on) and stuff which needed to be specific to each box (/etc, /var etc.) and wrote a complicated script to mount them based on the box’s address.

  6. Well I’m kind of stuck. I have the kernel loading but it fails on the NFS mount.

    You mentioned I had to edit my /etc/fstab file to tell it to nfs mount the root parition. Which /etc/fstab do I edit, the one in the /export directory?

    Right now it says “Cannot open root device “nfs” or unknown-block(0,255)” and then panics.

    Through experimentation I discovered this is the /dev/nfs line in the pxelinux.cfg directory config for the machine (ie making it /dev/jeff alters that error).

    It almost appears as if the kernel doesn’t have a valid IP so it can’t NFS mount the directory (which appears to be properly exported on my NFS host). Anyway I can confirm if the kernel has an IP that would allow it to talk? It isn’t responding to pings at the assigned boot address.


  7. I think I’ve got to go back and make sure my IP support, NFSRoot support and NIC driver are in my kernel… you may want to mention that. :)


  8. Yes, good point. I was using a Via EDEN motherboard. The NIC driver for that is built in to the standard Debian kernel. NFSRoot is also enabled by default in Debian so it Just Worked for me.

    But if you have different hardware, then yes you might need to build a new kernel.

    The fstab you should change is the one in /export. Here’s mine:

    none /proc proc defaults 1 0
    /dev/ram0 /tmp ext2 defaults 0 2 / nfs ro 0 1

  9. I was using a stock Debian 4.0 kernel (2.6.18). It didn’t appear to have NFSRoot support when I went in to rebuild the kernel. I had to enable that, the IP stuff, and in my case, it turns out I’ve got a Via Esther 1GHz processor which uses Via Rhine II NIC, so I added that in as well.

    I’m just about to try the rebuilt kernel now…


  10. I’ve got it all up and running.

    I suggest anyone interested in this check out for some handy utilities to copy root file systems and create symlinks to ram copies of files to allow errorless NFSRoot booting.


    PS – More to come when I clean up my notes.

  11. I tried this too… but i got a problem… after loading the pxelinux.cfg it says: “boot failed: press a key to retry or wait for reboot”

    Anyone has a solution?

  12. Check that your tftp service is working properly. You can test it by loading up a tftp client and trying to download the kernel with it.

  13. The problem was the kernel, it couldn’t find it… in the “/tftpboot/pxelinux.cfg/default” file I changed the kernel into the full kernel path and now it work fine…

    But now i got the following error:
    ‘VFS: Cannot open root device “export/dvc/stbroot”
    Please append a correct “root=” boot option
    Kernel panic – not syncing: VFS: Unable to mount root fs on …’

    Anyone help?

    Greetz Tim

  14. nealy working but i get this error any ideas?
    device=eth0, addr=, mask=, gw=,
    host=, domain=, nis-domain=(none),
    bootserver=, rootserver=, rootpath=
    Looking up port of RPC 100003/2 on
    Looking up port of RPC 100005/1 on
    VFS: Mounted root (nfs filesystem).
    Freeing unused kernel memory: 252k freed
    Warning: unable to open an initial console.
    Kernel panic – not syncing: No init found. Try passing init= option to kernel.

  15. I think the key is “No init found”. Check that your path to the root file system is correct and that the root file system contains the file /sbin/init

  16. Thankyou for this great howto. Debian wiki is fairly complete but missing some details in configuring PXE kernel boot params. Here I’ve found what I was looking for. Thankyou again.


Comments are closed.