Quickstart: wish nnr.tk ------------------------------------------------------------------------ Netwinder-NFS-Rescue v0.4 by Mike Montour This package consists of 3 parts: 1. A root filesystem and kernel, in the nnr-root.tar.gz file 2. A configuration utility (nnr.tk) that will install the above image, and assist you in configuring the necessary network services (TFTP, NFS, DHCP). This utility requires Tcl/Tk. 3. A program (nnr_serialkern) to download a kernel over a serial null-modem cable, using a Debug feature of the Netwinder firmware. Hopefully you won't need this one, but if you do, call it as: ./nnr_serialkern It is set up to use the kernel provided in the nnr-root.tar.gz file. You should first review the various HOWTOs and FAQs on www.netwinder.org to get an overview of network booting, and the operation of the Netwinder Firmware. It is assumed that you are generally familiar with Unix network services like TFTP and NFS, and in particular the security risks which may be caused by running these programs in a public environment. You should also ensure that operation of these services (particularly DHCP) will not cause interference for other users on your network. PREPARATION: You must have the following packages installed: Tcl/Tk, tftp, dhcp (server), NFS (server). If you are using the serial-console option, you will need a terminal program like minicom or Seyon. Set the terminal to 19200,8n1. This package was developed and tested with Firmware version 2.0.8e (not an "official" release) but should work down to 2.0.4 (most features even work with version 1.2). To start, run the command "wish nnr.tk" ('wish' is part of Tcl/Tk, which you must have installed). This will bring up a 'checklist' window that will assist you in the configuration process. For each one, you should first click "Do it", perform the operation, then click "Did it" to advance to the next one. 1. Configure - General configuration options installhere The directory where the disk image will be installed. NW_MAC The hardware (MAC) address of the Netwinder ethernet port which you will be using to boot the disk image. You can get this by running 'ifconfig' on your Netwinder, or by calculating it. The formula is: 00:10:57:n0:SS:SS where "n" is 0 for eth0 and "c" for eth1, and "SS:SS" is your *BOARD* serial number expressed in hex. The Board serial number can be found by 'cat /proc/cpuinfo', or can be seen on a white sticker inside the Netwinder case, on the underside of the main board (visible through the ventilation slots). It is also printed to the serial port when using certain versions of the Firmware. Note that you may have problems using eth1 with older versions of the Firmware. eth0 should always work. consoledev This is the device to use as the console. For "normal" use, this should be "tty0". For a serial-console, this should be "ttyS0". If you are using serial-console, set your terminal to 19200-8N1. Also ensure that your terminal program is set up for "direct connection" so it won't send any modem commands. ThisIP The IP address of the computer on which you are installing this package (which will be your TFTP/NFS/DHCP server). NW_IP The IP address to be assigned to the Netwinder (with DHCP). This must not be in use elsewhere. Subnet The network address shared by this computer and the Netwinder. SubnetMask The subnet mask shared by this computer and the Netwinder. After entering these values, click "Update" then "Done". Note that these values are NOT SAVED and will revert to their defaults the next time you run the program (unless you edit nnr.tk). 2. Install package This will create the directory $installhere/nnr-root, and will unpack the contents of nnr-root.tar.gz into it. It will then disable write permissions (to enhance security with TFTP) and set up a few configuration items. 3. Install TFTP services This will open an xterm and prompt you to configure TFTP. A default configuration line will be written to "inetd.conf_stub"; you may either append this line to /etc/inetd.conf (cat inetd.conf_stub >>/etc/inetd.conf) or otherwise modify your system so that the nnr-root image will be visible by tftp. By default "tcpd" (part of the tcpwrappers package) will be used to allow you to restrict TFTP access with /etc/hosts.{allow,deny} (see your system documentation). For this to work, it must be possible to resolve the Netwinder's IP address ($NW_IP) to a hostname. If necessary (e.g. if your Netwinder is normally your nameserver) you may have to add a static entry to /etc/hosts (a sample is created in hosts_stub). After changing /etc/inetd.conf, it will be necessary to restart inetd. When finished with this step, type "exit" to close the xterm, then click "Did it". 4. Install NFS server Similar to step #3, this step configures NFS. Add "exports_stub" to /etc/exports, or otherwise configure your system. Then restart NFS. NOTE: NFS is quite complicated, and it is beyond the scope of this doucment to explain how it works and what the configuration options mean. 5. Configure and start DHCP This is the step where you will activate your configuration. If you are not already running a bootp or dhcp server, then you can just run dhcpd as specified by the program (using a local configuration file). If you are already running a bootp or dhcp server, then you must figure out how to merge this configuration information into your system configuration files. 6. Cleanup This just provides an opportunity for you to deactivate or remove any of the changes you have made during the above procedure (to ensure you don't leave any security holes active on your system). This step is optional. ----------- During step 5 you will activate a DHCP server. At this point, you are ready to initiate a boot request from the Netwinder. Boot the machine, and press ENTER at the [5 4 3 ... countdown (on 2.0 Firmware; see docs at www.netwinder.org for other cases). Then enter the following commands: load-defaults setnetwork eth1 [ or eth0] setenv kernconfig tftp setenv rootconfig nfs boot If you are using eth0, you can use the shortcut "boot diskless" after "load-defaults". If you are using eth1, the "setnetwork eth1" command may fail with some error messages. If this happens, try the command again a couple of times. When a DHCP request is successful, you should see a block of configuration information matching what you set up on the server. If you are running dhcpd in the debug (-d) mode, you should also see some DHCPREQUEST / DHCPACK messages on the server. When you "boot", the Firmware will attempt to transfer the kernel by TFTP. You should see a count of blocks (up to about 2600) then the message "booting kernel". A few seconds after booting, the kernel will attempt to configure itself with BOOTP (similar to DHCP). The dhcp server will re-send the configuration information, then the kernel should mount the NFS root filesystem. At this point, you should see a startup screen and a shell (ash) prompt. Do whatever you want, then execute the script "finished" to unmount disks and reboot the Netwinder. [TODO: Write more about what can be done and how to do it] ---------------------------------------------------------- BUGS Configuration options are not saved; configuration must be repeated each time the program is run. Workaround: Edit the default values in nnr.tk with any text editor. If you are experimenting with different interfaces and IP addresses, you may need to manually clear out stale ARP entries (look at 'arp -n'). The program may get confused if you have DHCP servers active on both ethernet ports. There is no initrd / flashroot support at present. There is no error checking. "setnetwork eth1" doesn't always work on the first try. This is probably a nettrom bug. "printenv" with older nettrom will lock up if you are using serial-console. This is fixed in 2.0.8e. (TODO: A feature considered for a future release is to make a system that fits into the flashroot, which will use the Network Block Device (nbd) driver to give full access (partition, format, mount) to the Netwinder's disk over the network. Stay tuned...) Please see http://www.netwinder.org/~mmontour for updated bug reports, and please E-mail me if you find bugs that aren't listed there.