8. Network Boot¶

The Jaguar boot process involves three major steps. Each step loads the next one.

Table 8.1 Network boot steps¶
Step	Can be loaded from network?
U-Boot bootloader	No, must always be loaded from eMMC or SD Card
Linux kernel	Yes (TFTP via U-Boot `tftp` command, or PXE via U-Boot `pxe` command)
Root filesystem	Yes (NFS via Linux `nfsroot` argument)

A Linux server that provides NFS and TFTP servers is required. This chapter assumes Debian Bookworm. Additionally, it is assumed that there is a DHCP server on the network.

8.1. NFS+TFTP Server Setup¶

A Debian Linux server is used for NFS and TFTP.

8.1.1. Install NFS and TFTP packages¶

Note

All commands in this section must be run as the root user.

tftpd-hpa is only required if you load the Linux kernel from the network (Section 8.2.1 Variant 1: Linux and Rootfs from Network)

Run:

apt-get install nfs-kernel-server tftpd-hpa

Add the following line to /etc/exports:

/srv/nfsroot *(rw,async,no_subtree_check,no_root_squash)

Edit the file /etc/default/tftpd-hpa and adjust TFTP_DIRECTORY so it reads:

TFTP_DIRECTORY="/srv/nfsroot"

To apply the configuration changes, run:

systemctl restart nfs-kernel-server
systemctl restart tftpd-hpa

8.1.2. Extract the root filesystem¶

As part of (Section 5 Debian image guide), the file sdcard-jaguar-debos-trixie.tar.gz should have been generated.

This file needs to be extracted to /srv/nfsroot on the NFS+TFP server (adjust the path /tmp/sdcard-jaguar-debos-trixie.tar.gz to the actual location):

mkdir /srv/nfsroot &&
tar --extract --directory /srv/nfsroot --file /tmp/sdcard-jaguar-debos-trixie.tar.gz

If you want to load the Linux kernel from the network (Section 8.2.1 Variant 1: Linux and Rootfs from Network), a pxelinux configuration file must be created:

mkdir /srv/nfsroot/pxelinux.cfg &&
cat <<EOF > /srv/nfsroot/pxelinux.cfg/default-arm-rk3588-jaguar_rk3588
LABEL rk3588-jaguar-nfsroot
LINUX /boot/Image
FDT /boot/rk3588-jaguar.dtb
APPEND root=/dev/nfs rw ip=dhcp nfsroot=\${serverip}:/srv/nfsroot,v4,tcp,soft
EOF

8.2. Jaguar Setup¶

Deploy a disk image to SD card or eMMC as described in Section 7 Deploy a disk image.

Power up the board and wait for this line one the serial console:

Hit any key to stop autoboot

Hit any key to get to the U-Boot prompt.

8.2.1. Variant 1: Linux and Rootfs from Network¶

In this variant, the Linux kernel is loaded from the network via TFTP and the root file system is loaded from the network via NFS.

Only network interfaces that are supported by both U-Boot and Linux can be used. The on-board Ethernet interface works, of course. USB-Ethernet dongles may, for example.

The kernel command line is controlled through the file /srv/nfsroot/pxelinux.cfg/default-arm-rk3588-jaguar_rk3588 on the NFS+TFTP server. This makes it easy to adjust as necessary.

Run the commands below on the U-Boot prompt.

Note

Replace the IP address 192.168.123.123 with the actual IP address of your NFS+TFTP server.

env set autoload no
env set bootcmd 'dhcp && env set serverip 192.168.123.123 && pxe get && pxe boot'
env save
reset

8.2.2. Variant 2: Only Rootfs from Network¶

In this variant, the Linux kernel is loaded from eMMC and the root file system is loaded from the network via NFS.

In this variant, all network interfaces that are supported by Linux can be used.

The kernel command line is controlled through the bootargs variable that is saved in the U-Boot environment on the eMMC or SD Card.

Run the commands below on the U-Boot prompt.

Note

Replace the IP address 192.168.123.123 with the actual IP address of your NFS server.

env set bootargs 'root=/dev/nfs rw ip=dhcp nfsroot=192.168.123.123:/srv/nfsroot,v4,tcp,soft'
env set bootcmd 'load mmc 0 $kernel_addr_r boot/Image &&
load mmc 0 $fdt_addr_r boot/rk3588-jaguar.dtb &&
booti $kernel_addr_r - $fdt_addr_r'
env save
reset

Note

To load the kernel from SD Card instead of eMMC, replace mmc 0 with mmc 1.

8.3. Caveats¶

Details that should be taken into account when running on network boot.

8.3.1. Interface Naming¶

Ethernet interface on the Jaguar baseboard is usually renamed to end0 during early boot. When using nfsroot, this fails, as the interface is already up and used for nfsroot:

# journalctl -b | grep rename
Mar 06 14:56:17 jaguar-debian-debos (udev-worker)[309]: end0: Network interface 'eth0' is already up, cannot rename to 'end0'.
Mar 06 14:56:17 jaguar-debian-debos systemd-networkd[316]: eth0: Interface is being renamed, pending initialization.

In this case, the interface name is eth0.

8.3.2. DNS Failure¶

When you have internet connectivity and nfsroot using the Ethernet interface on the Jaguar baseboard, you may encounter a failure to resolve DNS names:

# ping google.at
ping: google.at: Temporary failure in name resolution

This is caused by a bug in systemd-networkd v252 in Debian Bookworm. A failure to rename an interface (Section 8.3.1 Interface Naming) causes the interface to become stuck in “pending” state:

# networkctl
IDX LINK   TYPE     OPERATIONAL SETUP
lo     loopback carrier     unmanaged
dummy0 ether    off         unmanaged
can0   can      off         unmanaged
eth0   ether    routable    pending

links listed.

This in turn prevents DNS from being properly configured.

To work around this issue, run

rm /etc/resolv.conf
echo nameserver 8.8.8.8 > /etc/resolv.conf

Note

This is only required for our legacy Debian Bookworm images.

8.3.3. DHCP Lease Expiration¶

The Linux kernel obtains an IP address via DHCP, which is then used for the nfsroot connection. This DHCP lease is not renewed, and when it expires, another device may get assigned the same IP address, causing severe connectivity issues.

To prevent this issue, statically reserve an IP address for the MAC address of each Jaguar on your DHCP server.

Alternatively, give Linux a static IP address via the ip= kernel command line option. Details are in the Linux nfsroot documentation at https://www.kernel.org/doc/html/latest/admin-guide/nfs/nfsroot.html .

8.4. Troubleshooting¶

The following steps may help to debug and recover from failures.

8.4.1. Increase Loglevel¶

Often it is helpful to increase the kernel loglevel to see all details of an issue.

To increse the kernel loglevel to max, add loglevel=8 to the APPEND line in /srv/nfsroot/pxelinux.cfg/default-arm-rk3588-jaguar_rk3588,

8.4.2. Revert to Local Boot¶

You can revert to local boot via the following command on the U-Boot prompt:

env default -a
env save
reset

Note that the following messages are normal:

=> env default -a
## Resetting to default environment
himport_r: can't insert "stdout=serial,vidconsole" into hash table
himport_r: can't insert "stderr=serial,vidconsole" into hash table
=> env save
Saving Environment to MMC... Writing to MMC(0)... OK
=> reset
resetting ...