Booting Grml over the network with PXE

Most computers today have the capability to boot over the network. This network boot capability is often named PXE (Preboot eXecution Environment). This can be very handy to boot into Grml without burning CDs, writing USB sticks, etc.

Booting Grml without grml-terminalserver

If you do not have a PXE environment available yet the easiest way to get started with Grml PXE boot is by booting one Grml system from USB/CD/DVD and just invoke 'grml-terminalserver' there. This easy-to-use tool will guide you through the configuration to set up all the services required to get network boot up and running without caring about the details. But if you already have PXE infrastructure available or want to set it up on your own Grml provides so called netboot packages to easily provide Grml inside your PXE infrastructure.


  • Unix/Linux server as boot server (Windows works too, but the instrcutions here are for Linux). The computer needs these services installed and configured:
    • DHCP server - provides your computer the IP address and boot information when booting from network
    • TFTP server - allows your computer to obtain the low-level boot files
    • NFS server - give access to the Grml files over the network
  • grml.iso image of the Grml version you want to use.
  • grml_netboot_package that matches your Grml version. This contains the low-level boot files and must be the same version as the Grml you use.

Quick setup guide

Necessary steps to integrate Grml in a running network boot setup:

  • copy vmlinuz and the initrd.img from your netboot package to your tftpboot directory (eg. /srv/tftp/ on Debian)
  • make grml iso content available in your nfs directory (eg. mount -o loop grml.iso /live/image, or just copy to the filesystem (mount -o loop grml.iso /mnt/iso && rsync -a /mnt/iso/ /live/image/).
  • export the /live/image (readonly is ok)
  • Add the following lines to your default pxelinux config (adjust the IP and replace “live-media-path=/live/grml64-full” according to the Grml flavour, so use “live-media-path=/live/grml32-full” if you're running grml32-full instead of grml64-full for example!):
LABEL grml
KERNEL vmlinuz
APPEND root=/dev/nfs rw nfsroot= live-media-path=/live/grml64-full/ boot=live lang=us nomce
    apm=power-off noprompt noeject initrd=initrd.img vga=791
  • You must give an IP address to the nfsroot option
  • If you encounter “Kernel panic - not syncing: VFS Unable to mount root fs on unknown-block(0,255)” it may be caused by a linebreak in the APPEND section. Make sure all the boot parameters after APPEND are in one long line without linebreaks.
  • If you use any nondefault path where your grml-iso content is on your filesystem, do not forget to update your nfsroot accordingly. You must export the directory with the GRML-iso contents directly, you can not export a higher level directory and point to it using live-media-path.
mount -o loop grml.iso /mnt/foo => nfsroot=<IP>:/mnt/foo
  • If your NFS Server only speaks NFSv2, you will need another bootoption for grml >= 1.1:
  • That's it!

If you don't have a network boot setup

Necessary steps to integrate Grml if you don't have a running network boot setup:

  • Install a dhcp server, an NFS Server and a TFTP Server, if not already done. A very basic setup for the dhcp server will do, see man dhcpd.conf.
  • cp -r everything from the tftpboot directory in the netboot package to your tftpboot directory (eg. /var/lib/tftpboot or /tftpboot on debian, this may depend on the tftp server you installed. I used atftpd which is the server grml-terminalserver uses).
  • make grml iso content available via nfs. eg. mount -o loop grml.iso /live/image, or just cp, then
    exportfs :/live/image

    edit /etc/exports to make the export permanent.

  • Edit the file pxelinux.cfg/default in the tftpboot directory. Change the nfsroot= entrys to match your ip and path.
  • Add the following entrys to the configuration file of your dhcp server:
         next-server xx.xx.xx.xx; 
         filename "pxelinux.0";

    Where xx.xx.xx.xx is the ip adress of your server. Restart the dhcpd server. Some tftp setups may require an absolute path for filename, but normaly the path is relative to your tftpboot directory.

  • That's it!

Grml netboot packages

For current releases

The netboot package contains a complete tftpboot directory:

  • tftpboot/vmlinuz - The grml linux kernel image
  • tftpboot/initrd.img - Netboot ready initrd
  • tftpboot/pxelinux.cfg/default - Default configfile for pxelinux
  • tftpboot/pxelinux.0 - Pxelinux binary

Hardware issues

  • NIC sends the tftp requests to the IP of the dhcp-server regardlessly of what he told him. This is a known bug in certain PXE implementations. 3Com hardware seems to suffer from this repeatedly.
  • acer Aspire One 110 (Realtek Ethernet Card) is not able to boot via network: I think it is a missing module for the network card.

Software issues

  • NFS root can not be mounted and busybox nfsmount gives something like “NFS over TCP not available from” ⇒ try bootoption “nfsopts=-oudp” (thx fEnIo from #grml for report&fix)
  • when two nics are installed and pxe-boot is started from the second one (eth1) then grml will fail to boot because it tries to get a ip-address via eth0 (instead of eth1). This can be changed via the grml ethdevice=… option (see cheatcodes)
terminalserver.txt · Last modified: 2016/01/10 21:27 by mika
Recent changes RSS feed Creative Commons License Valid XHTML 1.0 Valid CSS Grml homepage Driven by DokuWiki