BBB NFS root file system setup.

I’ve just spent two or three days sorting out an NFS mounted root file
system for the BBB, and while it’s easy when you know how, an awful lot
of details have to be right for things to work.

I hadn’t planned to use NFS, since I thought that a USB flash drive would
be robust enough for the small amount of native compiling I’d need, but
cross-compiling Mesa, for instance, is beyond me, and the (new) flash drive
I was using went read-only in less that a week.

Setting up the NFS server was twenty minutes work, and since I’m using
one of Robert Wilson’s kernels (22.3), which have NFS enabled, I could
mount the exported rootfs as an ordinary file system with no problems.

However, I couldn’t find the way to set up uEnv.txt to boot off an SD Card
and use an NFS root file system; the boot process simply hung and then
crashed. In the end I dismantled the various attachments to my BBB, set
up the serial debug interface to watch the boot process, and gradually
found the various snags. If you are booting an NFS root for the first
time I’d strongly suggest that you use the debug interface - even if the
BBB finds the NFS root, things can still go wrong in the boot sequence.

Note that the following setup has no security: I’ve subverted, thwarted
and generally destroyed it. Do do this at home, nowhere near any sort
of Internet access.

The server (V4 NFS) needs an /etc/exports file:

/etc/exports on server.

insecure - allow ports > 1024

no_root_squash - allow root access

no_subtree_check - don’t check further than filesystem


and an /exports/rootfs directory:
drwxr-xr-x 23 root root 4096 Jul 1 16:51 /exports/rootfs

and the actual automounted root filesystem:

/etc/fstab on server.

/home/beagle /exports/rootfs none bind 0 0

and of course the NFS server daemons running, however you start them.

The client fstab uses the NFS description for its root filesystem.

/etc/fstab on rootfs, ie. used by client. / nfs defaults 0 0

Again, the NFS client daemons need to be run on startup.

While testing, rather than mess around with uEnv.txt I simply booted into
u-boot and added entries directly until it worked. A typical (working)
u-boot console sequence is:

Hit any key to stop autoboot: 0
U-Boot# ext4load mmc 0:2 0x80F80000 /boot/dtbs/am335x-boneblack.dtb
24129 bytes read in 54 ms (435.5 KiB/s)
U-Boot# ext4load mmc 0:2 0x80200000 /boot/zImage
3320912 bytes read in 616 ms (5.1 MiB/s)
U-Boot# setenv bootargs console=ttyO0,115200n8 root=/dev/nfs rw nfsroot=,vers=4 ip=dhcp
U-Boot# bootz 0x80200000 - 0x80F80000

That is:

  1. Load the BBB dtb from the second partition of the SD card, which
    is in ext4 format, and put it at address 0x80F80000.
  2. Load the BBB kernel from the second partition of the SD card, which
    is in ext4 format, and put it at address 0x80200000.
  3. Set the bootargs environment variable, which contains the arguments
    passed to the kernel. In this case the console is set to the serial
    debug interface, the root filesystem is described as nfs (there is no
    actual /dev/nfs) and set read/write, and the nfsroot file system is set
    to the server’s address and path, together with the appropriate NFS
    version. The ip entry can describe the whole IP environment, client
    address, server address, netmask and so on, but it’s easier just to
    say “dhcp” and let the network sort things out. (In this case the NFS
    server also handles DHCP.)
  4. Run the bootz command, which starts the loaded kernel and dtb.

You may need to run u-boot’s printenv command to get your own values for
fdtaddr and loadaddr, the addresses to which the dtb and kernel are loaded.

To get a login on the serial debug interface you may need to add the
following line to the client’s /etc/inittab:

/etc/inittab on client (NB. tty/capital O/zero).

s0:12345:respawn:/sbin/agetty 115200 ttyO0 linux

Once the NFS boots it’s a question of updating the various macros in your
version of uEnv.txt to produce the same result - the uEnv.txt macro format
is so baroque that there’s no point in discussing it here.

Good luck - Will

3 steps are necessary.

netargs=setenv bootargs console=${console} ${optargs} root=/dev/nfs nfsroot=${serverip}:${rootpath},vers=3 rw ip=${ipaddr}

uenvcmd=run boot_ftd; run netargs; bootz 0×80200000 – 0x815f0000

Setting up rootfs is actually an all day sort of thing if you want to do it right, and if you’re starting from scratch. But well worth it IMHO, especially if you boot via network too.

I have outlined a guide here:

And another for network boot here:

Both of these guides assume you’re ok with running Debian. On a support system( cross dev system ), and on the BBB as well. Ubuntu may also work, with minor adjustments, but personally I only care about Debian, and as such have not tested on/with Ubuntu.

Anyhow sorry if the website doesn’t look great. I have been more interested in doing work with the BBB than trying to make my website look pretty… .