Category:How to - Network Boot - Revision history

Ashcharles: /* Setup */

2016-04-01T21:03:37Z

‎Setup

Sellis: Ubuntu 10.04 tftpd-hpa config file format change

2010-05-03T14:25:43Z

Ubuntu 10.04 tftpd-hpa config file format change

Sellis: Added ethaddr error note

2010-02-19T16:00:34Z

Added ethaddr error note

Sellis: Added links to kernel docs, cleanup

2010-02-11T13:39:26Z

Added links to kernel docs, cleanup

Sellis: Note to disable inetd

2010-02-07T16:37:36Z

Note to disable inetd

Sellis: Missing restart arg

2010-02-02T16:26:04Z

Missing restart arg

Ashcharles at 19:54, 1 February 2010

2010-02-01T19:54:28Z

Sellis: Clarify when nand u-boot is used

2010-01-19T11:27:28Z

Clarify when nand u-boot is used

Sellis: Formatting, reason for missing display kernel parameters

2010-01-14T14:38:01Z

Formatting, reason for missing display kernel parameters

Sellis: New Network Boot page

2010-01-14T14:27:28Z

New Network Boot page

New page

==Overview==

Network booting can be very convenient during the development cycle
for an embedded device. Current Gumstix Overos have a bootloader
and kernel ready for network booting if you have an expansion board
with an ethernet connector. Older Gumstix Overos can upgrade their
version of u-boot to get support for network booting.

The procedures that follow are for setting up a workstation to act
as both the tftp server and the nfs server to host the root file
system.

The procedure described does not require a dhcp server.

==Setup==

The following procedure assumes a Linux workstation to host all
the services. The workstation for the example is running Ubuntu 9.10.

There are multiple ways to configure the nfs server and the tftpd
server. This is just one example.

The names of the packages may be different if you are using another
Linux distribution.

The example will use the following network configuration.

Workstation IP: 192.168.4.4
Gumstix IP: 192.168.4.50

You will also need a Gumstix Overo kernel and rootfs on the workstation.

You can either
[http://www.gumstix.net/Setup-and-Programming/view/Overo-Setup-and-Programming/Setting-up-a-build-environment/111.html build]
one yourself or download one
[http://www.gumstix.net/Setup-and-Programming/view/Overo-Setup-and-Programming/Downloading-pre-built-images/111.html here.]

I'll assume an omap3-console-image custom built with OE located in the standard location.
Any image will work though.

==Packages==

Install the following Ubuntu packages on the workstation

tftp-hpa

nfs-common

nfs-kernel-server

portmap

==Create a root filesystem==

Create and populate the /exports directory with a kernel and a root filesystem

sudo mkdir -p /exports/overo
sudo tar -C /exports/overo -xvjf ${OVEROTOP}/tmp/deploy/glibc/images/overo/omap3-console-image-overo.tar.bz2

==Configure the tftp server==

Edit /etc/default/tftpd-hpa

RUN_DAEMON="yes"
OPTIONS="-l -s /exports/overo/boot"

What we are doing here is pointing the tftp daemon at the Gumstix root
filesystem we created above. The uImage kernel image sits here.

$ ls -all /exports/overo/boot/*
lrwxrwxrwx 1 root root 13 2010-01-13 11:50 /exports/overo/boot/uImage -> uImage-2.6.32
-rw-r--r-- 1 root root 3147516 2010-01-10 11:12 /exports/overo/boot/uImage-2.6.32

==Configure the nfs server==

Add the following line to /etc/exports

/exports/overo 192.168.4.50(rw,no_root_squash,no_subtree_check)

This tells the nfs server what directories to export as an nfs mountpoint and what machines have access to it.
Use man exports to get the documentation for /etc/exports.

==Restart the servers==

sudo /etc/init.d/tftpd-hpa restart
sudo service portmap restart
sudo /etc/init.d/nfs-kernel-server

==Configure u-boot==

Establish a serial console connection with the gumstix.

Power the gumstix unit and hit a key to stop the process in uboot.

Add some environment variables to u-boot.

Overo # setenv ipaddr 192.168.4.50
Overo # setenv netmask 255.255.255.0
Overo # setenv serverip 192.168.4.4
Overo # setenv gatewayip 192.168.4.1
Overo # setenv hostname overo

Overo # setenv ip ${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:eth0:none
Overo # setenv nfsroot /exports/overo
Overo # setenv nfsargs setenv bootargs console=\${console} root=/dev/nfs rootfstype=nfs ip=\${ip} nfsroot=\${nfsroot} rootwait
Overo # setenv loadnfskernel tftp \${loadaddr} uImage

Save what you've entered in the u-boot environment so far. None of these variables
are used by the default boot process so there will be no booting behavior changes
yet.

Overo # saveenv

==Testing==

The next step is to test the network boot by running each step manually.
Later we will modify u-boot to run this automatically.

1. First tftp load the kernel into the overo memory

Overo # print loadaddr
loadaddr=0x82000000

Overo # tftp ${loadaddr} uImage
smc911x: detected LAN9221 controller
smc911x: phy initialized
smc911x: MAC 00:15:c9:28:c1:78
Using smc911x-0 device
TFTP from server 192.168.4.4; our IP address is 192.168.4.50
Filename 'uImage'.
Load address: 0x82000000
Loading: T ######################################################
######################################################
######################################################
#####################################################
done
Bytes transferred = 3147516 (3006fc hex)

Okay, if that worked, make sure the loadnfskernel variable we created doesn't
have a typo by running the same process again using the u-boot run command.

Overo # run loadnfskernel

You should get the same results, a kernel tftp loaded into memory.

If it did not work, use a network monitoring tool like tcpdump or wireshark to
see if you are getting any traffic.

See the Notes section for some troubleshooting tips.

2. Test the loading of the boot arguments.

Overo # print bootargs
## Error: "bootargs" not defined
Overo # print nfsargs
nfsargs=setenv bootargs console=${console} root=/dev/nfs rootfstype=nfs ip=${ip} nfsroot=${nfsroot} rootwait
Overo # run nfsargs
Overo # print bootargs
bootargs=console=ttyS2,115200n8 root=/dev/nfs rootfstype=nfs ip=192.168.4.50:192.168.4.4:192.168.4.1:255.255.255.0:overo:eth0:none nfsroot=/exports/overo rootwait

Make sure that bootargs looks correct.

3. Boot the kernel

With a kernel of the correct format loaded into memory, the u-boot command bootm will
transfer control of the processor to this kernel.

Overo # bootm ${loadaddr}

...normal kernel boot messages here, then...
net eth0: SMSC911x/921x identified at 0xd08c8000, IRQ: 336
IP-Config: Complete:
device=eth0, addr=192.168.4.50, mask=255.255.255.0, gw=192.168.4.1,
host=overo, domain=, nis-domain=(none),
bootserver=192.168.4.4, rootserver=192.168.4.4, rootpath=
Looking up port of RPC 100003/2 on 192.168.4.4
Looking up port of RPC 100005/1 on 192.168.4.4
VFS: Mounted root (nfs filesystem) on device 0:13.
Freeing init memory: 928K
INIT: version 2.86 booting
...
The Angstrom Distribution overo ttyS2
Angstrom 2009.X-test-20100110 overo ttyS2
overo login:

==Making it automatic==

So if everything worked and you want to boot this way every time you need to modify the
bootcmd u-boot variable.

Reboot the gumstix and hit a key to stop it in u-boot again.

Overo # print bootcmd
bootcmd=if mmc init; then if run loadbootscript; then run bootscript; else if run loaduimage; then run mmcboot; else run nandboot; fi; fi; else run nandboot; fi

You may want to save this for the future or see the Notes section for where it is defined in the build.

Make a new bootcmd using the u-boot environment variables that we created.

Overo # setenv bootcmd echo Booting nfs ...\; run loadnfskernel\; run nfsargs\; bootm \${loadaddr}

Overo # saveenv

Now reboot and the gumstix should nfsboot by default.

Overo # reset

==Notes==

1. The default u-boot environment variables are defined in the u-boot source tree under include/configs/omap3-overo.h

2. The documentation for linux kernel parameters for nfs booting can be found in the linux source tree under
Documentation/filesystems/nfsroot.txt and Documentation/kernel-parameters.txt.

3. tftp listens over udp on port 69
$ grep tftp /etc/services
tftp 69/udp

You can check if it is listening with the following command.

$ netstat -an | grep udp
udp 0 0 0.0.0.0:111 0.0.0.0:*
udp 0 0 0.0.0.0:880 0.0.0.0:*
udp 0 0 0.0.0.0:39921 0.0.0.0:*
udp 0 0 0.0.0.0:56957 0.0.0.0:*
udp 0 0 0.0.0.0:2049 0.0.0.0:*
udp 0 0 0.0.0.0:59435 0.0.0.0:*
udp 0 0 0.0.0.0:69 0.0.0.0:*

4. nfs listens on port 2049 both tcp and udp. The nfs root process uses only udp.
$ grep nfs /etc/services
nfs 2049/tcp # Network File System
nfs 2049/udp # Network File System

5. The following is a tcpdump command for watching the gumstix boot traffic. Choose the appropriate
interface for your workstation.

$ sudo tcpdump -i eth1 -l -n udp

6. A cross-over ethernet cable connected between the workstation and the gumstix works well
if you can't host services on your regular network. You may want to check before starting a
tftp server on a shared network. A dedicated switch/hub will also work to keep things isolated.

7. You can check for running firewall rules with this command

$ sudo iptables --list
Chain INPUT (policy ACCEPT)
target prot opt source destination
Chain FORWARD (policy ACCEPT)
target prot opt source destination
Chain OUTPUT (policy ACCEPT)
target prot opt source destination

If you get output different then this (nothing running) and you are having problems booting, then
you should ensure you are not blocking any of the required traffic.

7. There is a patch to u-boot in the current gumstix overo-oe tree that improves the ethernet
network speeds on the overos. You can save about 10 seconds on an nfs boot using a u-boot
built with this patch as well as get better ethernet performance after booting. (The patch is
a tuning of the timing registers of the GPMC connected to the ethernet controller. This
configuration is done by u-boot when the board is brought up and not modified by Linux kernel
after booting.) When you do a network boot, you are using the u-boot on the NAND flash which
was probably built without this patch.
Build a newer version of u-boot following the standard build procedures. (U-boot is built
whenever you build an image.) Then copy it to NAND using the instructions
[http://www.gumstix.net/Setup-and-Programming/view/Overo-Setup-and-Programming/Writing-images-to-onboard-nand/111.html here.]

@@ Line 69: / Line 69: @@
 or if you don't need inetd for any other service, which a Ubuntu desktop install typically doesn't, disable inetd completely this way
-  sudo mv /etc/rc2.d/S20openbsd-inetd /etc/rc2.d/s20openbsd-inetd
+  sudo mv /etc/rc2.d/S20openbsd-inetd /etc/rc2.d/K20openbsd-inetd
 See the NOTES(1) section.
-Edit /etc/default/tftpd-hpa
+Edit /etc/default/tftpd-hpa (for 9.10)
   RUN_DAEMON="yes"
   OPTIONS="-l -s /exports/overo/boot"
 What we are doing is pointing the tftp daemon at the Gumstix root filesystem we created above so that it will find the uImage kernel that sits there.

@@ Line 147: / Line 147: @@
   Bytes transferred = 3147516 (3006fc hex)
 Okay, if that worked, make sure the loadnfskernel variable we created doesn't
 have a typo by running the same process again using the u-boot run command.
@@ Line 309: / Line 319: @@
 You'll need to include (directly, not as modules) CONFIG_NFS_FS, CONFIG_ROOT_NFS, CONFIG_NET_ETHERNET,
 and, the appropriate Ethernet chip driver, in my case, CONFIG_SMC911X.

@@ Line 35: / Line 35: @@
 You can either
-[http://www.gumstix.net/Setup-and-Programming/view/Overo-Setup-and-Programming/Setting-up-a-build-environment/111.html build]
+[http://gumstix.org/software-development/open-embedded/61-using-the-open-embedded-build-system.html build]
 one yourself or download one
-[http://www.gumstix.net/Setup-and-Programming/view/Overo-Setup-and-Programming/Downloading-pre-built-images/111.html here.]
+[https://www.gumstix.com/software/software-downloads/ here.]
 I'll assume an omap3-console-image custom built with OE located in the standard location.

@@ Line 17: / Line 17: @@
 ==Setup==
-The following procedure assumes a Linux workstation to host all
+A workstation running Ubuntu 9.10 is used for the example.
-the services. The workstation for the example is running Ubuntu 9.10.
 There are multiple ways to configure the nfs server and the tftpd
-server. This example tries to keep it simple.
+server. This is just one method.
-−
-The names of the packages may be different if you are using another
-Linux distribution.
-The example will use the following network configuration.
+Here is the network configuration.
   Workstation IP: 192.168.4.4
@@ Line 32: / Line 32: @@
   Gumstix IP: 192.168.4.50
-You will also need a Gumstix Overo kernel and rootfs on the workstation.
+You will also need a Gumstix Overo rootfs on the workstation.
 You can either
@@ Line 71: / Line 71: @@
   sudo mv /etc/rc2.d/S20openbsd-inetd /etc/rc2.d/s20openbsd-inetd
-See the NOTES section.
+See the NOTES(1) section.
@@ Line 79: / Line 79: @@
   OPTIONS="-l -s /exports/overo/boot"
-What we are doing here is pointing the tftp daemon at the Gumstix root
+What we are doing is pointing the tftp daemon at the Gumstix root filesystem we created above so that it will find the uImage kernel that sits there.
-filesystem we created above. The uImage kernel image sits here.
   $ ls -all /exports/overo/boot/*
@@ Line 93: / Line 92: @@
 This tells the nfs server what directories to export as an nfs mountpoint and what machines have access to it.
-Use man exports to get the documentation for /etc/exports.
+Use <b>man exports</b> to get the documentation for /etc/exports.
 ==Restart the servers==
@@ Line 114: / Line 113: @@
   Overo # setenv gatewayip 192.168.4.1
   Overo # setenv hostname overo
   Overo # setenv ip ${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:eth0:none
   Overo # setenv nfsroot /exports/overo
@@ Line 120: / Line 118: @@
   Overo # setenv loadnfskernel tftp \${loadaddr} uImage
-Save what you've entered in the u-boot environment so far. None of these variables
+Save what you've entered in the u-boot environment so far. None of these variables are used by default, so the boot behavior is still unchanged.
-are used by the default boot process so there will be no booting behavior changes
-yet.
   Overo # saveenv
@@ Line 174: / Line 170: @@
   bootargs=console=ttyS2,115200n8 root=/dev/nfs rootfstype=nfs ip=192.168.4.50:192.168.4.4:192.168.4.1:255.255.255.0:overo:eth0:none nfsroot=/exports/overo rootwait
-Make sure that bootargs looks correct.
+Make sure that bootargs looks correct. The format of the <b>ip</b> kernel command line argument is found in the kernel documentation under  [http://www.kernel.org/pub/linux/kernel/people/marcelo/linux-2.4/Documentation/nfsroot.txt filesystems/nfsroot.txt]
@@ Line 239: / Line 235: @@
   sudo mv /etc/rc2.d/S20tftpd-hpa /etc/rc2.d/s20tftpd-hpa
-. The default u-boot environment variables are defined in the u-boot source tree under include/configs/omap3-overo.h
+. The default u-boot environment variables for the overo are defined in the u-boot source tree under <b>include/configs/omap3-overo.h</b> if you wanted to customize or go back to defaults.
 . The documentation for linux kernel parameters for nfs booting can be found in the linux source tree under
-Documentation/filesystems/nfsroot.txt and Documentation/kernel-parameters.txt.
+[http://www.kernel.org/pub/linux/kernel/people/marcelo/linux-2.4/Documentation/nfsroot.txt Documentation/filesystems/nfsroot.txt]

@@ Line 61: / Line 61: @@
   sudo tar -C /exports/overo -xvjf ${OVEROTOP}/tmp/deploy/glibc/images/overo/omap3-console-image-overo.tar.bz2
 ==Configure the tftp server==
 Edit /etc/default/tftpd-hpa
@@ Line 213: / Line 224: @@
 ==Notes==
-. The default u-boot environment variables are defined in the u-boot source tree under include/configs/omap3-overo.h
+. tftp and inetd. You can use inetd to run tftp if you want. Just edit the -s option for tftp appropriately in  /etc/inetd.conf
-. The documentation for linux kernel parameters for nfs booting can be found in the linux source tree under
+and instead of this restart command
 Documentation/filesystems/nfsroot.txt and Documentation/kernel-parameters.txt.
 . tftp listens over udp on port 69
   $ grep tftp /etc/services
   tftp		69/udp
@@ Line 236: / Line 268: @@
 . nfs listens on port 2049 both tcp and udp. The nfs root process uses only udp.
   $ grep nfs /etc/services
   nfs		2049/tcp			# Network File System
@@ Line 242: / Line 274: @@
 . The following is a tcpdump command for watching the gumstix boot traffic. Choose the appropriate
 interface for your workstation.
@@ Line 248: / Line 280: @@
 . A cross-over ethernet cable connected between the workstation and the gumstix works well
 if you can't host services on your regular network. You may want to check before starting a
 tftp server on a shared network. A dedicated switch/hub will also work to keep things isolated.
 . You can check for running firewall rules with this command
   $ sudo iptables --list
@@ Line 267: / Line 299: @@
 . I removed the kernel parameters for the kernel display configuration for wiki formatting reasons.
 You should add the settings you require to the bootcmd variable in the example.
 . There is a patch to u-boot in the current gumstix overo-oe tree that improves the ethernet
 network speeds on the overos. You can save about 10 seconds on an nfs boot using a u-boot
 built with this patch as well as get better ethernet performance after booting. When you do a
@@ Line 280: / Line 312: @@
 [http://www.gumstix.net/Setup-and-Programming/view/Overo-Setup-and-Programming/Writing-images-to-onboard-nand/111.html here.]
-. If the gumstix seems unwilling to connect to your NFS server, ensure you've enabled NFS options in your kernel.
 You'll need to include (directly, not as modules) CONFIG_NFS_FS, CONFIG_ROOT_NFS, CONFIG_NET_ETHERNET,
 and, the appropriate Ethernet chip driver, in my case, CONFIG_SMC911X.

@@ Line 88: / Line 88: @@
   sudo /etc/init.d/tftpd-hpa restart
   sudo service portmap restart
-  sudo /etc/init.d/nfs-kernel-server
+  sudo /etc/init.d/nfs-kernel-server restart
 ==Configure u-boot==

@@ Line 5: / Line 5: @@
 and kernel ready for network booting if you have an expansion board
 with an ethernet connector. Older Gumstix Overos can upgrade their
-version of u-boot to get support for network booting.
+version of u-boot to get support for network booting. This procedure
 The procedures that follow are for setting up a workstation to act
@@ Line 277: / Line 279: @@
 whenever you build an image.) Then copy it to NAND using the instructions
 [http://www.gumstix.net/Setup-and-Programming/view/Overo-Setup-and-Programming/Writing-images-to-onboard-nand/111.html here.]

@@ Line 271: / Line 271: @@
 . There is a patch to u-boot in the current gumstix overo-oe tree that improves the ethernet
 network speeds on the overos. You can save about 10 seconds on an nfs boot using a u-boot
-built with this patch as well as get better ethernet performance after booting. (The patch is
+built with this patch as well as get better ethernet performance after booting. When you do a
-a tuning of the timing registers of the GPMC connected to the ethernet controller. This
+network boot without a microSD card, you are using the u-boot on the NAND flash which
-configuration is done by u-boot when the board is brought up and not modified by Linux kernel
-after booting.) When you do a network boot, you are using the u-boot on the NAND flash which
 was probably built without this patch.
 Build a newer version of u-boot following the standard build procedures. (U-boot is built
 whenever you build an image.) Then copy it to NAND using the instructions
 [http://www.gumstix.net/Setup-and-Programming/view/Overo-Setup-and-Programming/Writing-images-to-onboard-nand/111.html here.]