Skip to main content
Version: BSP 6.x.y

Boot from a TFTP/NFS Server


A common configuration for rapid kernel/application development and debugging is to have the target machine connected to a development host (usually a PC) inside a network. The target retrieves the kernel (and device trees/device tree overlays) from a TFTP server running on the host and uses a root filesystem from an NFS server, also served by the host. This setup makes testing very convenient, as the developer can easily deploy new kernel builds and root filesystem contents in the respective local (host) server folders instead of having to transfer them to the target every single time (usually through a removable media such as an SD card or a USB stick). This article describes how to configure this setup.

Setup for a target and host with TFTP/NFS


In order to boot your module from a TFTP/NFS server you need:



We recommend using a second interface card on your development PC to build a dedicated network to your module. Alternatively, you can set a VLAN to isolate your target from the rest of the network.

The boot sequence for the described scenario follows the steps below:

  • U-Boot obtains the IP address and the name of the file containing the U-boot Distroboot script from the DHCP server running on the host.
  • U-Boot executes the script, obtaining linux kernel image, device tree/device tree overlays, auxiliary binaries (like M4 elf files or GPU firmware).
  • U-Boot sets the kernel's command line so that the kernel mounts the rootfs from an NFS server.
  • Linux uses DHCP again to get an IP address and retrieve the root-path arguments.
  • Linux tries to mount the root file system using the root-path.

First, you need to install and configure a DHCP, TFTP and NFS servers. Please consult your distribution's documentation on what server packages are needed and how they need to be configured. You might additionally need to allow these protocols to be passed through by your firewall rules.

The following sample configuration may (or may not) fit your distribution.


After configuration changes and when modifying the served NFS files, the servers need to be restarted: e.g. on Ubuntu: #service isc-dhcp-server restart; service tftpd-hpa restart; service nfs-kernel-server restart; on Fedora: # systemctl restart dhcpd.service; systemctl restart nfs-server.service

Sample DHCP Configuration

Some points to be taken into consideration:

  • The server IP (your computer) is the default serverip variable on U-boot. This way you don't need to configure the server IP if you are using default configurations.
  • The client IP (your module) is the default ipaddr variable on U-boot. This way you don't need to configure the client IP if you are using default configurations.
  • The interface property must be the name of the Interface where the module is connected via an Ethernet cable. On Ubuntu, you can get this information by using the command ip link of ifconfig.
  • The hardware ethernet property must be the MAC Address of your module. Please refer to the MAC Address article to find out some ways to get this information from your module.
# dhcpd.conf
option domain-name "";
option domain-name-servers;

default-lease-time 600;
max-lease-time 7200;

# Use this to enable / disable dynamic dns updates globally.
ddns-update-style none;

# Use this to send dhcp log messages to a different log file (you also
# have to hack syslog.conf to complete the redirection).
log-facility local7;

subnet netmask {
default-lease-time 86400;
max-lease-time 86400;
option broadcast-address;
option domain-name "";
option domain-name-servers;
option ip-forwarding off;
option routers;
option subnet-mask;
interface eth1;
#MAC address dependent IP assignment, used for the colibri target device
host eval {
filename "uImage";
hardware ethernet 00:14:2d:48:8a:58;
option host-name "colibri";
option root-path ",wsize=1024,rsize=1024,v3";

Sample root-path for NFSv4

        option root-path                "rootfs,v4,tcp,clientaddr=";

For NFSv4, rootfs, as given above, is relative to the root path which is where the exports file has the option "fsid=root" set (see below).


Take care to only answer DHCP requests originating from your development network card. You won't make friends by providing addresses to clients on your corporate network!

Then, start/restart the relevant services e.g. on Ubuntu:

mk@ubuntu: ~ $ sudo service isc-dhcp-server restart

Or on Fedora:

[root@vm_one ~]# systemctl restart dhcpd.service

Sample TFTP Configuration

Configure the server to serve /srv/tftp.
E.g. on a recent Ubuntu: /etc/default/tftpd-hpa
E.g. on a recent Fedora: /etc/xinitd.d/tftp

Copy the contents of you bootfs folder, which contains kernel, device tree and auxiliary binaries to the tftp directory:

sudo cp -Ppr /path to bootfs/* /srv/tftp/

For example, for Apalis iMX8X TFTP folder should contain this list of files (or similar):

:/srv/tftp/$ ls -lah
drwxr-xr-x 3 user user 4.0K Oct 28 18:39 .
drwxrwxr-x 10 user user 4.0K Aug 28 16:39 ..
-rw-r--r-- 1 user user 3.9K Oct 28 18:18 boot.scr
-rw-r--r-- 1 user user 101K Oct 27 22:48 dpfw.bin
-rw-r--r-- 1 user user 101K Oct 27 22:48 hdmitxfw.bin
-rw-r--r-- 1 user user 9.4M Oct 27 22:48 Image.gz
-rw-r--r-- 1 user user 159K Oct 27 22:48 imx8qm-apalis-eval.dtb
-rw-r--r-- 1 user user 160K Oct 27 22:48 imx8qm-apalis-ixora-v1.1.dtb
-rw-r--r-- 1 user user 159K Oct 27 22:48 imx8qm-apalis-v1.1-eval.dtb
-rw-r--r-- 1 user user 160K Oct 27 22:48 imx8qm-apalis-v1.1-ixora-v1.1.dtb
drwxr-xr-x 2 user user 4.0K Oct 27 22:48 overlays
-rw-r--r-- 1 user user 14 Oct 27 22:48 overlays.txt

Sample NFS Configuration

Copy the rootfs to /srv/nfs/rootfs (while preserving symlinks, timestamps..)

sudo cp -Ppr /path to image/rootfs/* /srv/nfs/rootfs
NFSv3 Configuration

Create an export configuration:

NFSv4 Configuration

Create an export configuration:


The path for NFSv4 (/srv/nfs) is indeed different from the path for NFSv3 (/srv/nfs/rootfs).

Apply Configuration

Start/restart the relevant daemons e.g. on Ubuntu:

mk@ubuntu: ~ $ sudo service nfs-kernel-server restart

Or on Fedora:

[root@vm_one ~]# systemctl restart nfs-server.service

Run TFTP/NFS Boot from U-Boot

Starting from BSP 5.1.0 U-Boot leverages Distroboot capabilities for network boot. This requires only one command to be run in U-Boot shell (even regardless the module you're using):

Apalis iMX8X # run bootcmd_dhcp

NFS and connman

In our images we use connman to manage network connections.

When using an NFS mounted rootfs connman is not started during boot. This is because connman takes an already configured NIC down before bringing it up again. In the case of a NFS boot this unmounts the rootfs and makes the boot fail.

Should you require connman when using NFS, e.g. to do tests with wireless connectivity, you could change the connman.service file. Make sure to change eth0 to the name of the used NIC on Apalis T30. This is likely enp7s0.

--- lib/systemd/system/connman.service~ 2014-05-02 17:01:49.000000000 +0200
+++ lib/systemd/system/connman.service 2014-06-16 09:48:08.454798634 +0200
@@ -3,14 +3,15 @@
# only if not NFS mount, connman will disconnect your rootfs otherwise!

-ExecStart=/usr/sbin/connmand -n
+#ExecStart=/usr/sbin/connmand -n
+ExecStart=/usr/sbin/connmand -n -I eth0


Send Feedback!