The NetWinder Disk-Update-HOWTO <author>Ralph Siemsen, <tt>ralphs@netwinder.org</tt> <date>$Revision: 1.11 $, $Date: 2000/11/19 17:13:24 $ <abstract> This manual explains various ways of installing or upgrading disk images on a NetWinder. It really comes down to untarring an image in the right spot, then changing a few settings in the firmware. Note that if you are using an OfficeServer, you should read <url url="Rescue-HOWTO.html"> instead of this document. </abstract> <toc> <sect>Introduction There are a variety of reasons you'd want to update the hard disk image on your NetWinder. From a simple update to a newer disk image, to a forced reinstallation because something went badly wrong, this manual covers the various possibilities. Each chapter in this manual covers a different installation method. Consult the section `Choosing an installation method' below for advice on how to determine the best method for your particular circumstances. There is a general `Troubleshooting' chapter at the end. <sect1>Obtaining a new disk image Official disk images for the NetWinder can be downloaded from <url url="ftp://ftp.netwinder.org/pub/netwinder/images/"> directory (older disk images are in <tt>/pub/ccc/images/</tt> instead). For more information about the various disk images, please see <url url="http://www.netwinder.org/~ralphs/diskimage.html">. There are also some unofficial disk images that may be of interest. Having not tried them myself, I withold further comments and will only say that there is an ongoing port of Debian (see <url url="http://www.debian.org/ports/arm/">) and there is also a RedHat port with versioned glibc called Titan (see <url url="http://www.nw.carleton.ca">). <sect1>Choosing an installation method A variety of installation methods can be used to update the NetWinder's disk. Which one is right for you will depend on such factors as how much free space you have on the NetWinder's hard disk, what type of network connection you have got, etc. The following paragraphs are intended to asist you in selecting an appropriate installation method. <sect2>Rescue partition For the OfficeServer and DM built 15, a "rescue partition" is included on <tt>/dev/hda4</tt>. It contains a small filesystem that provides facilities to restore the rest of the drive from either a Windows or Unix host, without having to worry about nfs booting. Use of this new rescue system is covered in the <url url="Rescue-HOWTO.html">. <sect2>Basic method For people with plenty of free disk space, this is the easiest method. You download the compressed disk image (tarball) onto your NetWinder, then expand it onto a free partition. Requires enough space to hold the compressed and uncompressed images simultaneously (about 900 MB for build #12). <sect2>Remote tarball The compressed tarball can be downloaded to another machine and be expanded from there across a (local) network connection. The `other' machine must support NFS file sharing (unix machine) or SMB file sharing (Windows) and must have enough room to hold the compressed disk image. The NetWinder must have enough room for the uncompressed image (ideally on an unused partition). <sect2>Drive swap You can remove the hard disk from the NetWinder and install it in an ordinary PC. This will of course void your warrantee! You'll need a laptop IDE adaptor cable, available at most computer stores, since the connector is physically smaller. Then you can set the drive as slave and format/install to your hearts content from the host PC system. <sect2>Parallel port If you own a parallel-port device such as the Backpack CD-ROM or a tape drive, you can use this to hold the disk image. The NetWinder can even boot off the cd-rom drive (it takes forever, since the parallel port is fairly slow). You can also use ZIP drives, though you won't be able to fit an entire disk image onto one of course. Still useful for emergency booting though. <sect2>Rescue firmware Certain versions of the NetWinder firmware come with a `rescue' filesystem that allows the machine to be booted without using the hard disk or the network connection. It turns your NetWinder into an NFS server, so that another computer on your network can connect to it and decompress the disk image. This method requires a second (unix) machine as an NFS client, with enough room to hold the compressed disk image. <sect2>NFS booting The NetWinder can boot from another server (typically another Linux machine) using TFTP to fetch the kernel and NFS to access the root filesystem. It can be quite tricky to get this setup, so this option is not recommended for novices. It requires a second computer with enough room for the compressed and uncompressed disk image, and it must have tftp and nfs server support. <sect2>NFS rescue Mike Montour has developed a trimmed-down and more automatic method similar to the NFS booting technique, but without the overhead of an entire disk image on the rescue server. His latest version also includes a GUI tool to help set up the server for tftp, nfs, and dhcp services. This method also requires a second (unix) machine that can support network booting. <sect>Basic method The chapter describes the basic method for installing a new diskimage on a NetWinder. The methods described in the other chapters are variations on the basic method, so this chapter makes for good background reading even if you are using one of the other methods. See the first chapter for an overview of the different installation methods. <sect1>Requirements This is the simplest method but requires considerable hard drive space - enough to hold the compressed disk image (about 250 MB for build #12) as well as the uncompressed image (about 650 MB). Add to this the space occupied by the existing disk image, and you'll see that this method is practical only on machines with hard disks of 2 GB or more capacity. A new disk image is also required, of course. It can be downloaded (via FTP) from netwinder.org as a <tt>tar.gz</tt> archive. Alternatively you might have received the image on CDROM or other media; you should transfer the image onto the NetWinder by some means - FTP, NFS, SMB, HTTP - keep in mind that the image is a binary file. <sect1>Preparation Some manipulation may be required to free up space on the partition where the new image is to be installed. While it is not strictly necessary for the partition to be empty, subtle problems can arise if old files are mixed with the new image. We recommend clearing the partition completely to avoid trouble. See also section 4.3 for more information on how to free up a partition. The <tt>df</tt> command will allow you to check disk usage. Typical output from this command is shown below. Don't be alarmed if the values reported by your system differ. <verb> Filesystem 1024-blocks Used Available Capacity Mounted on /dev/hda1 1014784 645694 316651 67% / /dev/hda3 2792760 72888 2575451 3% /home </verb> Here we see that the third partition <tt>/dev/hda3</tt> contains only 72 MB of data, whereas there remain 316 MB of free space on the first partition <tt>/dev/hda1</tt>. If we moved the data from the third partition into the first, then <tt>/dev/hda3</tt> would be empty and we could install the new diskimage there. Since unix doesn't allow files to be moved across filesystems, we first copy the data from <tt>/dev/hda3</tt> and later delete it. You must be root to run these commands of course. <verb> cd / umount /dev/hda3 mount /dev/hda3 /mnt/hda3 cp -ax /mnt/hda3/. /home umount /dev/hda3 </verb> The data has now been copied to the <tt>/home</tt> directory, which is now on <tt>/dev/hda1</tt>. To prevent side effects, you should also edit the <tt>/etc/fstab</tt> file and comment out the line beginning with <tt>/dev/hda3</tt>, or delete the entire line. Otherwise, your system may have difficulty trying to mount <tt>/dev/hda3</tt> next time you reboot. The free partition can now be cleared out, either by formatting it or by deleting all the files (<tt>rm -rf</tt>). Again this isn't strictly necessary but it is recommended. Be sure you give the right partition number otherwise you'll end up formatting the wrong partition. The commands for formatting the third partition, and then mounting it on <tt>/mnt/hda3</tt>, are as follows. <verb> mke2fs /dev/hda3 mount /dev/hda3 /mnt/hda3 </verb> Now you're ready to install the new disk image onto <tt>/mnt/hda3</tt>. You can use the <tt>df</tt> command to verify the amount of free space if you wish. Special note: If you are running dm-3.1-15 disk image, then you must pass extra flags to <tt>mke2fs</tt> otherwise the firmware and kernel won't recognize your filesystem correctly. To format a partition you should use these commands <verb> mke2fs -O sparse_super /dev/hda3 </verb> <sect1>Image installation To install the image, use the <tt>tar</tt> command to extract files from the compressed image. If you have not yet downloaded the image, do so now (placing it wherever there is enough room). Then use the following commands to expand the archive. The example assumes that your "empty" partition has been mounted on <tt>/mnt/hda3</tt> (as in the previous section): <verb> cd /mnt/hda3 tar zxpf YourImage.tar.gz </verb> Replace <tt>YourImage</tt> with the name of the image you downloaded (including the full path, if it's not located in the current directory). This process will take 5 to 10 minutes, on average. <sect1>Updating <tt>etc/fstab</tt> The etc/fstab file will need to be edited before the new image can be booted. Using your favourite text editor, open the file <tt>/mnt/hda3/etc/fstab</tt>. The line that begins with <tt>/dev/hda3</tt> should be deleted or commented out. The line that begins with <tt>/dev/hda1</tt> should then be changed so that it begins with <tt>/dev/hda3</tt> (or whichever partition you've just installed to). Save the modified file and exit the editor. Then unmount the partition in anticipation of rebooting: <verb> sync cd / umount /mnt/hda3 </verb> While it should not be necessary with official disk images, you might want to check that the file <tt>etc/mtab</tt> does not exist in your image (before you unmount it). Delete this file if it does exist (for example, <tt>rm /mnt/hda3/etc/mtab</tt>). <sect1>Firmware settings The last step is to change the firmware settings so as to boot from the new partition. Reboot the machine (using CTRL-ALT-DEL for example) and then upon reboot, at the `Press any key to abort autoboot' prompt, press a key. Enter the following commands to switch over to <tt>/dev/hda3</tt>: <verb> load-defaults setenv kerndev /dev/hda3 setenv rootdev /dev/hda3 save-all boot </verb> The <tt>save-all</tt> command may be omitted if you just want to test boot the new image (you can re-issue it later on). See the Firmware-HOWTO at <url url="http://www.netwinder.org/~ralphs/howto/Firmware-HOWTO.html"> for more information. The new disk image should now boot. If not, consult the Troubleshooting chapter at the end of this manual. To access your old disk image (perhaps to copy out some personal files, for example) you can mount it with a command like: <verb> mount /dev/hda1 /mnt </verb> <sect>Remote tarball This chapter describes a slight variation on the basic method for installing a new disk image on a NetWinder. It is useful if there is not enough disk space on the NetWinder to hold both the compressed and uncompressed images. <sect1>Requirements This method requires sufficient space on the NetWinder to stored the new, uncompressed disk image (about 650 MB for build #12). The NetWinder must also have network connectivity (ethernet) - the <tt>nwconfig</tt> program can used to configure IP address and other parameters. In addition, a second computer is needed to hold the compressed disk image (about 250 MB). This can be another unix machine, or a Windows machine - anything capable of communicating with the NetWinder via ethernet. Configuration of the remote system is not covered in much detail here. <sect1>Preparation On the NetWinder, a disk partition should be freed up. This process is described in detail in section 2.2 of the previous chapter. In the following examples, it will be assumed that an empty partition has been mounted on <tt>/mnt/hda3</tt>. The `other computer' (hereafter called the server) also needs to be set up. The compressed disk image should be downloaded to this server machine. The image should then be made available to the NetWinder by putting it into an NFS share (for unix systems) or into a public folder (for Windows machines). Unix shares are normally listed in the <tt>/etc/exports</tt> file, while Windows handles it by right-clicking on the directory name and changing the properties. The NetWinder must then be configured for access to the (remote) compressed disk image. The process depends on the type of server being used. <sect2>Unix server The following commands show how to mount a remote NFS server so that theNetWinder can access its files. Replace <tt>192.168.1.2</tt> with the IP address of the server and replace <tt>/exportname</tt> with the actual name of the exported filesystem. This must match the name given in the <tt>/etc/exports</tt> file on the server. <verb> mkdir /mnt/server mount 192.168.1.2:/exportname /mnt/server </verb> To verify proper operation, use the command <tt>ls /mnt/server</tt> - you should see the compressed disk image in the listing. <sect2>Windows server In the case of a Windows machine acting as the server, you will have created a shared folder with a name such as SHARE. You can access this share from your NetWinder using the <tt>smbmount</tt> command. Substitute the Windows computer's name for COMPUTER, and specify your windows USERNAME and WORKGROUP as well. You'll be prompted for your password. <verb> mkdir /mnt/server smbmount //COMPUTER/SHARE /mnt/server -U USERNAME -W WORKGROUP </verb> In case of difficulty, consult the <tt>smbmount</tt> man page. To verify that it is working correctly, enter the command <tt>ls /mnt/server</tt> - you should see the compressed disk image in the listing. <sect1>Image installation The proceedure for installing the image is nearly the same as that described in the basic method, except that the image now streams over the ethernet from the server system. The commands for installation are as follows. <verb> cd /mnt/hda3 tar zxpf /mnt/server/YourImage.tar.gz </verb> Replace <tt>YourImage</tt> with the name of the compressed disk image that you downloaded to the server. The process will nominally take about 10 minutes, but it depends on how much traffic is on the network. You can monitor progress by switching to another terminal or window and using the <tt>df</tt> command. <sect1>Post installation Please refer to sections 2.4 and 2.5 in the previous chapter for the post-installation instructions. Note that it is essential to update the etc/fstab file before attempting to boot the new image. <sect>Drive swap This chapter describes how to install a new diskimage on a NetWinder by removing the hard disk and installing it as the slave drive in another system. This method is not recommended since it will void the warrantee, but its a practical method especially for those people with very small hard disks. <sect1>Requirements This method requires a second computer where the NetWinder's hard disk can be installed. The second machine could be another NetWinder, or an ordinary PC running some form of unix. In the case of a regular PC, an adaptor cable is required since the NetWinder hard drive is of the 2.5" laptop variety, which will not plug directly into the normal IDE connectors. Adaptors are available at most computer stores for about $10. Static electricity can kill a NetWinder! Be sure to be properly grounded before you start poking around inside your computer. <sect1>Preparation The NetWinder's hard drive should be connected to the host computers IDE controller, and (possibly) the master/slave jumper will need to be adjusted on the NetWinder's drive. To gain access to the drive, open the four screws on the bottom of the NetWinder. Usually it's possible to move the NetWinder close enough to the PC so that the cable can be directly connected, if not, you'll have to remove the hard drive itself (the screws are on the bottom of the motherboard). Once the drive is connected, the PC can be powered up. Do whatever is necessary for the drive to be detected (this might mean going into the BIOS and specifying the drive parameters, or on modern PC's, the drive will be auto-detected). I'll assume for the purpose of this example that the PC's main hard drive is <tt>/dev/hda</tt> and that the NetWinder's drive is <tt>/dev/hdb</tt> - but you'll have to verify that this is the case on your machine (use the <tt>dmesg</tt> command for this). <sect1>Freeing space There must be enough room to install the new disk image on the NetWinder's drive. You have the option of moving/deleting files to free up a partition, or you might choose to format the NetWinder's hard disk completely and repartition it as you wish. I cannot give you a step-by-step guide here, so I'll describe the available options and let you decide. <sect2>Moving files between partitions To transfer files between partitions, you need to mount both partitions and then use the <tt>cp</tt> and <tt>rm</tt> commands. Two mountpoints are required for this - you can use any two directories - for example <tt>/mnt/one</tt> and <tt>/mnt/two</tt>. Of course the directories must exist before they can be used, so go wild with the <tt>mkdir</tt> command. Then mount the two partitions (picking on <tt>/dev/hdb1</tt> and <tt>/dev/hdb2</tt> for this example): <verb> mount /dev/hdb1 /mnt/one mount /dev/hdb2 /mnt/two </verb> Now files can be copied from <tt>/mnt/one</tt> to <tt>/mnt/two</tt> (or vice-versa) using the <tt>cp</tt> command. To remove the originals after they've been copied, use the <tt>rm</tt> command. When you're done, unmount the partitions again: <verb> sync umount /mnt/one umount /mnt/two </verb> <sect2>Formatting a parition Once a partition has been cleared of files, or if you don't want to keep the old files, the format command can be used to initialize a new filesystem. This will completely wipe out everything on the partition, with no way to restore it. Use with care, and check very carefully that the correct partition and drive are specified. <verb> mke2fs /dev/hdb1 </verb> The preceeding example will format the first partition on the second (slave) drive, presumably the NetWinder drive. In case you're not clear on the naming convention yet, the drives are called <tt>/dev/hdXY</tt> where X is a letter (<tt>a</tt> for the first drive, <tt>b</tt> for the second, etc) and Y is a number indicating the partition (starting from one). <sect2>Repartitioning the drive In some cases it may be desirable to repartition the entire drive, for example if you are updating an old system and don't want to keep the old version anyhow. Note that after repartitioning, you must format the partitions, and this will destroy all data on the drive. To adjust the partition tables, use the <tt>fdisk</tt> command. You have to tell it which drive you want to repartition - for example say <tt>fdisk /dev/hdb</tt> to adjust the partition table on the second (slave) drive. The rest of the commands (for deleting a partition, creating a new one, etc) are explained in the on-line help. There is also a nice man page (<tt>man fdisk</tt>) that gives more information. The recommended disk layout is as follows: the first partition is the root filesystem (type 83, Linux) usually about 1 GB in size. The second partition is used for swap (type 82, Linux swap) and is 64 to 128 MB in size. Anything remaining space is allocated to third partition and gets mounted as <tt>/home</tt>. <sect1>Installing the image To install the image, you need to ensure that both the source and destination partitions are mounted, then you can use the <tt>tar</tt> command to extract files from the diskimage. Most likely, the diskimage is located on your main disk (hda) and the destination is the first partition on hdb. In this case, the appropriate commands are as follows: <verb> mount /dev/hdb1 /mnt/hdb1 cd /mnt/hdb1 tar zxpf /path/to/YourImage.tar.gz </verb> You'll need to ensure that the mountpoint <tt>/dev/hdb1</tt> exists (or use a different name), and you'll need to specify an appropriate path and filname instead of <tt>path/to/YourImage</tt>. This process should be pretty quick, about 5-10 minutes, since the data is moving over the IDE bus directly. <sect1>Post installation After the installation of the disk image is completed, be sure to review the <tt>etc/fstab</tt> file in the installed image. The entries in this file must correspond with the way the partitions are used, eg. if the first partition contains the main image, then it should be mounted as <tt>/</tt> in the fstab file. Keep in mind that the drive names listed in the fstab file should be those that will be seen when the disk drive is booted on the NetWinder (<tt>/dev/hda</tt> in most cases). Also be sure to edit the right <tt>etc/fstab</tt> file - you want to edit the one in the image you just untarred, not the one belonging to the host PC. The drive can then be unmounted and the PC can be powered down. The NetWinder's hard disk should then be reinstalled. If the partition usage has changed, then firmware settings may need to be changed. Consult section 2.5 for details, but remember to use the appropriate <tt>/dev/hdaX</tt> value for your particular situation. <sect>Parallel port It's possible to update or reinstall a NetWinder disk image via a parallel-port device, such as the Backpack CD-ROM. Its pretty slow and therefore not recommended in general, but if you happen to have a suitable drive, and don't mind waiting, then this method is for you. <sect1>Requirements There are two variations on the parallel port method. One way is to use the parallel port device simply as a storage place for the diskimage tar file. In this case, the NetWinder must have enough room on a spare partition to hold the uncompressed disk image. You'll also need to make or obtain a CDROM (or tape or disk, as the case may be) containing the image tar file. Alternatively, it is possible to boot off the parallel port device (at least, San made it work a long time ago). In this case, the NetWinder's hard disk could theoretically be reformatted and the new image installed over top. Therefore you would not need a "spare partition" to hold the new image. The difficulty with this method is that you need a bootable CDROM, and unfortunately I can't tell you how to make/obtain one. If anyone has experience, please let me know. <sect1>Preparation A partition should be freed up to make room for the uncompressed image. The process is described in sections 2.2 and 4.3 (read both if in doubt). It will be assumed in the following that <tt>/dev/hda3</tt> has been freed and is mounted on <tt>/mnt/hda3</tt>. Next, the parallel port device needs to be made available. Ensure that it's plugged in and powered on. Most likely the device will be a CD-ROM player, since zip drives are not large enough to hold the disk image. So the example listed here will assume a Backpack CDROM. This happens to be a device that I have tested. For other parallel devices, consult <url url="http://netwinder.org/~ralphs/parport.html"> for the appropriate commands. <verb> insmod nls insmod isofs insmod paride insmod bpck insmod pcd mount -o ro /dev/pcd0 /mnt/cdrom </verb> To verify that it's working right, issue the command <tt>ls /mnt/cdrom</tt> and you should see the diskimage tarball in the listing. <sect1>Image installation As in the other install methods, the disk image should now be untarred to the free disk partition. The command sequence will be similar to <verb> cd /mnt/hda3 tar zxpf /mnt/cdrom/YourImage.tar.gz </verb> Naturally you have to substitute the appropriate name for <tt>YourImage</tt>. The process could take quite a long time, since the transfer over the parallel port is rather slow. It also uses a lot of CPU power, so the computer may be very slow to respond if you try and do anything else while the image is uncompressing. <sect1>Post installation Be sure to fixup the <tt>etc/fstab</tt> file in the newly installed image before shutting down, and adjust the firmware parameters upon reboot. Please refer to sections 2.4 and 2.5 for the details on how to do this. <sect>Rescue firmware This chapter describes how to restore a NetWinder disk using the `rescue' flash filesystem. This allows a NetWinder to boot completely from the flash memory, and then become an NFS server. You can then use a second computer on your network to connect to the NetWinder and install a new disk image. Thanks go to Mike Montour (mmontour@iname.com) who first put together the rescue filesystem and has been improving it ever since. San Mehat adapted the filesystem so that it could be stored in flash memory. I've also twiddled with it a bit and released my own version (nettrom-2.0.4a+ralphs). Please note that the <tt>startnfs</tt> script described below only exists in the 2.0.4a+ralphs version! <sect1>Requirements First and foremost, this method requires a NetWinder with a rescue filesystem embedded in the firmware. The only sure-fire way to find out is to try and boot the rescue filesystem (see section XX below). If your machine boots as usual off the hard disk, you don't have rescue firmware installed. In that case, either upgrade the flash (see the Firmware-HOWTO at <url url="http://netwinder.org/~ralphs/howto/Firmware-HOWTO.html">), or use one of the other installation methods. The second requirement is to have another computer, preferably a unix machine, which can act as an NFS client. The diskimage tarball should be downloaded to this machine. This machine will then mount the NetWinder's hard disk and untar across the network to the NetWinder. <sect1>Preparation As with the other methods, a partition should be freed on the NetWinder disk (unless you plan to reinstall everything, in which case you can just format the partition, of course). Consult sections 2.2 and 4.3 for more information on how to free a partition. <sect2>NetWinder setup The NetWinder will now be turned into an NFS server and be made to export the (empty) partition so that it can be mounted from the `other' computer. The first step is to reboot the NetWinder and to enter the firmware menu by pressing a key when prompted, `Press any key to abort autoboot'. Configure the NetWinder's IP address and netmask, and enable the rescue filesystem: <verb> setenv netconfig_eth0 flash setenv eth0_ip 192.168.1.1/24 setenv rdconfig flash boot </verb> Be sure to specify the NetWinder's actual IP address and netmask. The welcome message should then be displayed. If you do not see it, or if the system boots off the hard disk like it usually would, then your firmware lacks a rescue filesystem. In this case, you can either change the firmware, or use one of the other installation methods. Optionally, the <tt>mke2fs</tt> and <tt>e2fsck</tt> commands can now be used to format and verify partitions, respectively. The partition table itself cannot be altered, unfortunately, since there is not enough room in the rescue filesystem for the <tt>fdisk</tt> program to be included. The last step is to actually export the (empty) partition, and to start the NFS daemons. Mike has set up a convenient script for doing this. For reasons unknown, firmware versions with the <tt>rescue</tt> suffix don't include this script (perhaps San didn't think it was needed...) There is a corrected version called <tt>nettrom-2.0.4a+ralphs</tt> which does include the script (and is otherwise identical). The following example shows how to use the script. <verb> startnfs 192.168.1.254 /dev/hda3 </verb> This causes <tt>/dev/hda3</tt> to be mounted on <tt>/mnt/localdisk</tt> and then exported to the host 192.168.1.254. You should of course substitute the IP address of your `other' computer in its place. If the <tt>startnfs</tt> command fails, try rebooting and repeating the startnfs process again. Usually it succeeds after a few tries. If you have repeated problems, you can contact me for help (mostly because I'd like to nail down exactly what the conditions are that lead to the problem). <sect2>The `other machine' The other computer will now mount the NetWinder's exported filesystem. I suggest creating a mountpoint <tt>/mnt/netwinder</tt> for this purpose. Substitute the NetWinder's actual IP address into the following mount command: <verb> mkdir /mnt/netwinder mount 192.168.1.1:/mnt/localdisk /mnt/netwinder </verb> If this fails, try pinging the NetWinder to make sure the network connection is working. If <tt>ping</tt> works, but the mount fails, go back to the NetWinder and ensure that the NFS service started without errors. On some systems, you might have to add the flag <tt>-t nfs</tt> to the mount command. To verify that things are working, try doing <tt>ls /mnt/netwinder</tt>. This should show an empty filesystem. The <tt>df</tt> command should show that /mnt/netwinder has sufficient space to hold the uncompressed disk image (about 650 MB for build #12). <sect1>Installing the image The image can be untarred directly to the NFS disk image now. Since the uncompressed data must be transfered over the network, it could take quite some time. Be patient... To monitor progress, you can switch to another terminal and use the <tt>df</tt> command. <verb> cd /mnt/netwinder tar zxpf /path/to/YourImage.tar.gz </verb> You will have to supply the full pathname for <tt>YourImage</tt>. The image could of course be located on another NFS (or otherwise) mounted volume, if you wanted to. <sect1>Post installation Be sure to fixup the <tt>etc/fstab</tt> file in the newly installed image before shutting down, and adjust the firmware parameters upon reboot. Please refer to sections 2.4 and 2.5 for the details on how to do this. Note in the examples in section 2.x assume your new image to be located on <tt>/dev/hda3</tt>; if you've used a different partition, you must adjust the examples to suit. <sect>NFS booting This chapter describes how a NetWinder drive can be updated by NFS booting the system from a remote host. This is the most flexible way to update a NetWinder, and it is also (perhaps) the most tricky one to set up for novices. <sect1>Requirements This method requires a second computer which will act as the boot server for the NetWinder. This server must support NFS and TFTP services, and an ethernet connection of course. It must also have lots of disk space, enough to hold a compressed and an uncompressed version of the NetWinder disk image. The NetWinder in this case needs 2.0 firmware or better, and everything else is negotiable. Since the NetWinder will boot from the server, you can safely format the NetWinder's hard disk and install a new diskimage onto it. Therefore you only need enough room to hold the uncompressed image (so it will even work for the 810 Meg drives). <sect1>Server preparation The server needs to be configured so that it can provide a kernel via TFTP, and a root filesystem via NFS for the NetWinder. The examples that follow are written for a PC running RedHat Linux. Things should be pretty similar for most other unix-like operating systems, but I can't possibly list all the different systems. It is possible to use a second NetWinder as the boot server. The only thing to watch out for is that the tftp daemon that's shipped on all disk images up to #14 suffers from an alignment bug, and therefore doesn't work. The symptoms include an error message about "GAL tftp operation". The fix is pretty simple: <tt>arpa/tftp.h</tt> must be fixed, then tftpd must be rebuilt. For simplicity, the following examples assume static IP addresses for both the NetWinder and the rescue server. It is possible to use DHCP, and if you plan on NFS booting many NetWinders, it is even a good idea. However, to improve your chances of actually getting this proceedure to work, the topic of DHCP is left out here. <sect2>Preparing <tt>/nwroot</tt> Begin by unpacking the NetWinder diskimage tarball on your server. Create a directory called <tt>nwroot</tt> (or other name if you prefer) in the filesystem root. If you don't have room to unpack the image there, you can put the directory elsewhere and make a symbolic link. <verb> mkdir /nwroot cd /nwroot tar zxpf /path/to/YourImage.tar.gz </verb> The fstab file in the image must be updated to match the way this image will be booted. Therefore, edit <tt>/nwroot/etc/fstab</tt> and comment out all the lines that begin with <tt>/dev/hdaX</tt>. Then add a line as follows, but replace the IP address with the server's actual IP address: <verb> 192.168.1.254:/nwroot / nfs defaults 0 0 </verb> Save the file and your <tt>/nwroot</tt> will be ready for action. Notes for kernel 2.2.x and beyond: Upon booting you may encounter the message `<tt>Unable to open initial console</tt>' if using the older rescue packages or disk images. If this happens, the solution is to create a <tt>/dev/console</tt> entry (major 5, minor 1) in your NFS image. Alternatively, you can create a symbolic link from <tt>/dev/console</tt> to <tt>/dev/tty0</tt>. <sect2>Setting NFS exports The <tt>nwroot</tt> directory now needs to be exported so that the NetWinder can boot from it. I'll assume the NetWinder's IP address to be 192.168.1.1, substitute your real address. On the server, edit (or create) <tt>/etc/exports</tt> so it contains the following line: <verb> /nwroot 192.168.1.1(rw,no_root_squash) </verb> Restart the NFS service, so that the changes take effect. On RedHat systems, the command would be: <verb> /etc/rc.d/init.d/nfs restart </verb> If this causes trouble, ensure that you installed NFS server support in the first place. Additional RPM's might need to be installed. For NFS server support you need the programs <tt>portmap</tt>, <tt>rpc.mountd</tt> and <tt>rpc.nfsd</tt> (and maybe others too..). <sect2>Setting up TFTP booting The server needs to support the TFTP protocol, since the NetWinder will try to get a kernel using this method. Normally, a special directory would be reserved for storing the files to be sent by TFTP. However it's simpler in this case to use the <tt>boot</tt> directory in the NetWinder disk image, since it already contains the kernels (no point in making additional copies). To enable the tftp service, it needs to be added to the <tt>/etc/inetd.conf</tt> file. Most systems will already have an entry for it, probably commented out though. In any case, make sure there is an un-commmented line that reads: <verb> tftp dgram udp wait root /usr/sbin/tcpd in.tftpd /nwroot/boot </verb> Note in particular that the directory has been specified as the last argument. This means that when processing a tftp request for a file, the server will look in that directory. To effectuate the changes, the inetd process must be sent a SIGHUP. On a RedHat system this can be accomplished with the following command. <verb> killall -HUP inetd </verb> In principle, your server should now be ready. <sect1>NetWinder diskless boot The NetWinder will now be booted from the server. Turn on the NetWinder's power (or reboot it if it was running) and interrupt the boot process at the `Press any key to abort autoboot' prompt. Now the settings for diskless booting need to be adjusted in the firmware. The first thing to do is to assign an IP address and netmask for the NetWinder. <verb> setenv netconfig_eth0 flash setenv eth0_ip 192.168.1.1/24 </verb> Naturally you should put in the NetWinder's real IP address and netmask value. The next step is to configure the firmware so that it will fetch the kernel from the server, instead of reading it from the local hard disk: <verb> setenv kernconfig tftp setenv kerntftpserver 192.168.1.254 setenv kerntftpfile vmlinux </verb> Substitute the server's IP address above. Finally, the firwmare is told to use the NFS exported directory as the root filesystem. <verb> setenv rootconfig nfs setenv rootpath 192.168.1.254:/nwroot boot </verb> If you wish, you can issue the <tt>save-all</tt> command before the boot command - if something fails, you won't have to type all those setenv's again. Later on, when the new disk image has been installed, you need only change <tt>kernconfig</tt> and <tt>rootconfig</tt> to switch back to local (disk-based) booting. <sect2>If it doesn't boot Diagnosing what is failing can be quite difficult sometimes. There are a large number of things to check, any of which could cause trouble. The following tips will hopefully help in diagnosing the problem. If you get really stuck, as for help on the mailing lists / newsgroups. The first thing that should happen after the <tt>boot</tt> command is given is that the kernel should be downloaded via TFTP from the server. A counter will show the bytes as they are received, and it should take a couple of seconds at least (the kernel is about 1MB in size). If the count doesn't appear at all, there is a problem with tftp on your server, or a networking problem (NetWinder can't talk to the server). Check the the IP addresses and netmasks. If downloading succeeds, the kernel will then be booted. If your monitor goes black or looses sync for an extended time, then the kernel failed to boot. Check that your firmware is compatible with the kernel that the TFTP server is sending. You might have to upgrade or downgrade one or the other. The kernel should then boot, and print its usual messages about detected hardware. Then it will try to mount the NFS share. IF the mount fails, it might hang here, or give an error. If it says "NFS server not responding, still trying" then be patient, it will probably work. Anything else (error -13 for example) means the NFS export couldn't be mounted. Check the server, maybe try mounting it from yet another machine. One of the first things you'll see after the NFS is successfully mounted is the message "INIT version... starting". In this case you should be home free. Expect some warnings during the nfs boot (for example, ef2sck will complain when it tries to scan the root disk, since it can't handle an nfs filesystem). You should eventually get to a login prompt. <sect1>Installing the image Once the NetWinder is nfs booted, you should login in as root (password is 'vnc') and then type <tt>mount</tt> to ensure that you really are NFS booted. The output from mount should show that "/" is not mounted on <tt>/dev/hda1</tt>. At this point there are a number of options. If you wish, you may repartition the NetWinder's hard disk by typing <tt>fdisk /dev/hda</tt>. If you do so, you'll have to format the new partition with <tt>mke2fs</tt>. This will of course erase everything on the disk. (Please see the note in section 2.2 regarding the <tt>-O sparse_super</tt> option). In any event you should free up a partition to hold the new disk image. For consistency with previous chapters, I'll assume that <tt>/dev/hda3</tt> has been freed in the following examples. See sections 2.2 and 4.3 for tips on how to free a partition. You can untarr the diskimage to the free partition, or you can copy recusively all the files from the NFS mount to the free partition. The former is quicker so I'll describe it here. On the server, the <tt>YourFile.tar.gz</tt> diskimage should be copied or moved into the <tt>/nwroot</tt> directory. It will therefore be visible to the NetWinder. On the NetWinder, the image can be installed using the following commands. <verb> mount /dev/hda3 /mnt/hda3 cd /mnt/hda3 tar zxpf /YourImage.tar.gz </verb> Since the files are being copied across the network, this process could take some time. <sect1>Post installation Be sure to fixup the <tt>etc/fstab</tt> file in the newly installed image before shutting down, and adjust the firmware parameters upon reboot. Please refer to sections 2.4 and 2.5 for the details on how to do this. Note in the examples in section 2.x assume your new image to be located on <tt>/dev/hda3</tt>; if you've used a different partition, you must adjust the examples to suit. If you used the <tt>save-all</tt> command in section 7.3 above, then remember to "undo" those settings so that your machine will boot from its hard disk again: <verb> setenv kernconfig fs setenv rootconfig disk save-all </verb> That's it! <sect>NFS rescue This method was developed by Mike Montour (mmontour@iname.com) as an alternative to the full NFS-boot method described in the previous chapter. It's meant to simplify the process of configuring the server, and it also takes less space on the server (since it doesn't require the whole NetWinder disk image to be decompressed). <sect1>Usage Mike has prepared a README for the use of his rescue filesystem. It is available at <url url="http://www.netwinder.org/~mmontour/">. The NFS-rescue disk images are also available from the same place. Overall, the process is similar to that described in the previous chapter, `NFS booting'. Some of the differences include: <itemize> <item> The package includes a configuration utility to help you set up the tftp and NFS server on the server, and also creates a DHCP configuration file (but it's important to read your HOWTO to understand what the configuration utility is doing). <item> When booting the Netwinder, the Firmware commands are: <verb> load-defaults setnetwork eth1 (or eth0) setenv kernconfig tftp setenv rootconfig nfs boot </verb> (It should get everything else over DHCP) <item> "Installing the image" is the same, except that you don't have to log in, and the local partitions are mounted under <tt>/exports/hdaN</tt> by default. Unpacking the tarball from the NFS host onto the local disk is also the preferred installation method with my package (which now includes tar). </itemize> Notes for kernel 2.2.x and beyond: Upon booting you may encounter the message `<tt>Unable to open initial console</tt>' if using the older rescue packages or disk images. If this happens, the solution is to create a <tt>/dev/console</tt> entry (major 5, minor 1) in your NFS image. Alternatively, you can create a symbolic link from <tt>/dev/console</tt> to <tt>/dev/tty0</tt>. <sect>Troubleshooting Here is a list of things to check when nothing is working. Unfortunately, it is not very complete listing. If you've got suggestions for things to add, please <url url="mailto:ralphs@netwinder.org">. <sect1>Proper <tt>etc/fstab</tt> Be sure to check the <tt>etc/fstab</tt> file in your new disk image before shutting down and trying to boot it for the first time. The default file might not be applicable to the way you've partitioned your disk. Make sure that there are entries for only those partitions you actually use. Comment out any <tt>/dev/hdXY</tt> lines if you don't need them. Also, make sure that the root device is properly specified. The root device is the line whose mountpoint (second column) is simply `/'. Make sure that the device name immediately to the left of it actually is the partition where you've installed the disk image. This should be the same value that you put into the <tt>rootdev</tt> parameter in the firmware. <sect1>Delete <tt>etc/mtab</tt> If there is a file called <tt>etc/mtab</tt> in your newly installed image, delete it. This is used to cache the actual mounted filesystems (it looks much like <tt>/etc/fstab</tt>). The system will re-create a proper file when it needs one. Having an old version of mtab around can prevent the machine from booting. <sect1>Mountpoints for <tt>/proc</tt>, <tt>/mnt</tt> Sometimes the mountpoints don't get included in a disk image. Fix this by going to the root directory of the new image and running the following commands. <verb> mkdir proc mkdir mnt mkdir mnt/hda1 mkdir mnt/hda2 mkdir mnt/hda3 </verb> <sect1>Unable to open initial console! When booting a 2.2.x kernel on a disk image designed for 2.0, you may encounter the message `<tt>Unable to open initial console</tt>' shortly afteer the kernel boots. The solution is pretty simple, you have to create a <tt>/dev/console</tt> entry in your NFS disk image. Either of the following two command can be used; the first one is preferred: <verb> mknod /dev/console c 5 1 ln -s tty0 /dev/console </verb> Keep in mind you want to create the node in the NFS image that's exported to your NetWinder for booting, as opposed to the root filesystem of your NFS server. So you should really say <tt>/path_to_nfs/dev/console</tt> instead of <tt>/dev/console</tt>. <sect1>couldn't mount because of unsupported optional features If you're getting this error whey you try to boot your newly installed system, then the problem is that you used a new version of <tt>mke2fs</tt> and it has turned on some new features, which the NetWinder firmware does not understand. Until the firmware is fixed, the solution is to use <tt>mke2fs -O sparse_super /dev/hdaX</tt> when you format your filesystem. It may also be possibly to change this after-the-fact with the tune2fs program, but I've not tried it. <sect>Misc <sect1>Author The author and maintainer of the NetWinder Disk-Update-HOWTO is Ralph Siemsen (ralphs@netwinder.org). Please send me any comments, additions, corrections so that the can be included in the next release. The latest version of this document can be obtained from <url url="http://www.netwinder.org/~ralphs/howto/Disk-Update-HOWTO.html">. <sect1>To-do The `sgml2info' version of this document doesn't show the examples properly - for some reason the linefeeds are removed. Why is this and how do I fix it? <sect1>History May 22, 1999 (version 1.0): First public release of this document. May 27, 1999 (version 1.1): Completed missing sections, added links to Carelton project, put in more cross-references. Jun 7, 1999 (version 1.4): Added NFS-rescue section (thanks Mike!) Jun 21, 1999 (version 1.5): Fixed typo in section 6.2 NetWinder setup (thanks to Steve Cockwell), added clarification about "rescue" versus "ralphs" versions of the firmware. Dec 12, 1999 (version 1.6): Fixed typo in section 7.2, the filesystem type in the example was incorrectly listed. Apr 10, 2000 (version 1.7): Documented the <tt>-O sparse_super</tt> option for <tt>mke2fs</tt>, which is necessary on dm-3.1-15. <sect1>Contributors Right now this is a product entirely of my own imagination. Mike Montour (mmontour@iname.com) designed the NFS-rescue package. Steve Cockwell (stevec@sierra.lazarus.ca) spotted a typo in the Rescue-firmware chapter. Jason Jackson (jrjackso@warg.uwaterloo.ca) spotted a typo in section 6, it should read <tt>netconfig_eth0</tt>... Sean MacLennan (seanm@netwinder.org) for spotting a typo in section 7.2, the <tt>/etc/fstab</tt> entry should show a filesystem of <tt>nfs</tt> and not <tt>ext2</tt>. Robert Scwartz (roberts@corel.com) caught my silly typo of the <tt>sparse_super</tt> option for <tt>mke2fs</tt>. <sect1>Legal stuff This document is copyright (c) Ralph Siemsen, 1999. Permission is granted to make and distribute copies of this manual provided the copyright notice and this permission notice are preserved on all copies. There is no warrantee whatsoever. </article>