terminalserver

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.

grml-terminalserver introduction

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.

The rest of this guide details how to, essentially, do the equivalent of what grml-terminalserver does, but manually, on an existing server.

It also has tricks not featured in grml-terminalserver.

Requirements

• Unix/Linux server as boot server (Windows may work too, but the instructions 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 or HTTP 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). Note that those files can also be taken from inside the ISO.

• 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):

  exportfs :/live/image
  

  edit /etc/exports to make the export permanent.

• 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 initrd=initrd.img live-media-path=/live/grml64-full/ root=/dev/nfs rw nfsroot=192.168.0.1:/live/image boot=live

  You must give the NFS server IP address to the nfsroot option, of course.

• If you encounter "Kernel panic - not syncing: VFS Unable to mount root fs on unknown-block(0,255)" it may be caused by a line break in the APPEND section. Make sure all the boot parameters after APPEND are in one long line without line breaks.

• If you use any non-default 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 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=:/mnt/foo

• If your NFS Server only speaks NFSv2, you will need another bootoption for grml >= 1.1:

  nfsopts=v2

• That's it!

Basic network boot setup

The above assumes you already have a DHCP server with PXE configured.

If you don't, also do those steps to setup a boot server:

• Install a DHCP server and a TFTP Server, if not already done. A very basic setup for the DHCP server will do, see man dhcpd.conf.

• copy everything from the tftpboot directory in the netboot package to your tftpboot directory (eg. /var/lib/tftpboot or /srv/tftpboot on Debian, this may depend on the TFTP server you installed. I used atftpd which is the server grml-terminalserver uses).

• 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.

At this point, booting a machine on that network segment should boot into the PXE menu.

If you don't want to run NFS

If you don't want to setup NFS, you can still boot GRML over the network.

You still need to setup a server with DHCP, TFP, HTTP and PXE, where you can at least get a shell in a PXE boot loader (e.g. iPXE) and deliver files over HTTP.

For this, follow the above Basic network boot setup. If you already have a PXE server and know what you're doing, you can skip that step, but you will need to deploy the vmlinuz and initrd files to the TFTP server root. Those can be copied from the ISO.

From here on we assume you have a PXE server setup that can boot a linux kernel. Then:

• install a web server. Apache, Nginx, Caddy, python -m http.server 80, any will do. from here on we assume files are served from /var/www/html

• extract the .squashfs file from the .ISO (which can then be deleted), for example:

  mount grml-full-2025.08-amd64.iso /mnt -o loop
  mkdir -p /var/www/html/grml/live
  cp /mnt/live/grml-full-amd64.squashfs /var/www/html/grml/live
  umount /mnt
  rm grml-full-2025.08-amd64.iso
  

  You can also bind-mount the ISO directly:

  mount grml-full-2025.08-amd64.iso /var/www/html/grml -o loop
  

  You do not gain much space by doing it the first way: most of the ISO space is taken up by the squashfs, of course

  Note that the path to the squashfs will vary according to the flavor (full, small) and architecture (e.g. amd64), and this pattern might change in future GRML releases.

• Add the following lines to your default pxelinux config (adjust the IP and replace fetch= according to the Grml flavour):

  label grml-http
  menu DEFAULT
  menu label grml-full-amd64 ^Standard (2025.08, amd64, HTTP boot)
  kernel vmlinuz
  append initrd=initrd.img boot=live fetch=http://192.168.0.1/grml/live/grml64-full/grml64-full.squashfs
  

Note: the above is based on this article from 2008 and IRC discussions from September 2025.

Grml netboot packages

The netboot package contains a complete tftpboot directory. It is available from https://download.grml.org/ .

• 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 192.168.0.1" => 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)