1.\" $NetBSD: diskless.8,v 1.11 1997/06/16 07:50:35 mrg Exp $ 2.\" 3.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd October 2, 1994 29.Dt DISKLESS 8 30.Os 31.Sh NAME 32.Nm diskless 33.Nd booting a system over the network 34.Sh DESCRIPTION 35The ability to boot a machine over the network is useful for 36.Xr diskless 37or 38.Xr dataless 39machines, or as a temporary measure while repairing or 40re-installing filesystems on a local disk. 41This file provides a general description of the interactions between 42a client and its server when a client is booting over the network. 43The general description is followed by specific instructions for 44configuring a server for diskless Sun clients. 45.Pp 46.Sh OPERATION 47When booting a system over the network, there are three 48phases of interaction between client and server: 49.Pp 50.Bl -tag -width 1.2 -compact 51.It 1. 52The PROM (or stage-1 bootstrap) loads a boot program. 53.It 2. 54The boot program loads a kernel. 55.It 3. 56The kernel does NFS mounts for root. 57.El 58.Pp 59Each of these phases are described in further detail below. 60.Pp 61In phase 1, the PROM loads a boot program. PROM designs 62vary widely, so this phase is inherently machine-specific. 63Sun machines use 64.Tn RARP 65to determine the client's 66.Tn IP 67address and then use 68.Tn TFTP 69to download a boot program from whoever sent the 70.Tn RARP 71reply. HP 300-series machines use the 72.Tn HP Remote Maintenance Protocol 73to download a boot program. 74Typical personal computers may load a 75network boot program either from diskette or 76using a special PROM on the network card. 77.Pp 78In phase 2, the boot program loads a kernel. Operation in 79this phase depends on the design of the boot program. 80(The design described here is the one used by Sun and NetBSD/hp300.) 81The boot program: 82.Pp 83.Bl -tag -width 2.2 -compact 84.It 2.1 85gets the client IP address using 86.Tn RARP . 87.It 2.2 88gets the client name and server 89.Tn IP 90address by broadcasting an 91.Tn RPC / BOOTPARAMS / WHOAMI 92request with the client IP address. 93.It 2.3 94gets the server path for this client's 95root using an 96.Tn RPC / BOOTPARAMS / GETFILE 97request with the client name. 98.It 2.4 99gets the root file handle by calling 100.Xr mountd 8 101with the server path for the client root. 102.It 2.5 103gets the kernel file handle by calling 104.Tn NFS 105lookup on the root file handle. 106.It 2.6 107loads the kernel using 108.Tn NFS 109read calls on the kernel file handle. 110.It 2.7 111transfers control to the kernel entry point. 112.El 113.Pp 114In phase 3, the kernel does NFS mounts for root. 115The kernel repeats much of the work done by the boot program 116because there is no standard way for the boot program to pass 117the information it gathered on to the kernel. 118The procedure used by the kernel is as follows: 119.Pp 120.Bl -tag -width 2.2 -compact 121.It 3.1 122The kernel finds a boot server using the same procedure 123as described in steps 2.1 and 2.2 above. 124.It 3.2 125The kernel gets the 126.Tn NFS 127file handle for root using the same procedure 128as described in steps 2.3 through 2.5 above. 129.It 3.3 130The kernel calls the 131.Tn NFS 132getattr function to get the last-modified time of the root 133directory, and uses it to check the system clock. 134.El 135.Sh CONFIGURATION 136Before a client can boot over the network, 137its server must be configured correctly. 138This example will demonstrate how a Sun client 139might be configured -- other clients should be similar. 140.Pp 141Assuming the client's hostname is to be 142"myclient", 143.Pp 144.Bl -tag -width 2.1 -compact 145.It 1. 146Add an entry to 147.Pa /etc/ethers 148corresponding to the client's ethernet address: 149.Bd -literal -offset indent -compact 1508:0:20:7:c5:c7 myclient 151.Ed 152This will be used by 153.Xr rarpd 8 . 154.Pp 155.It 2. 156Assign an IP address for myclient in your 157.Pa /etc/hosts 158or DNS database: 159.Bd -literal -offset indent -compact 160192.197.96.12 myclient 161.Ed 162.Pp 163.It 3. 164If booting a Sun machine, ensure that 165.Pa /etc/inetd.conf 166is configured to run 167.Xr tftpd 8 168in the directory 169.Pa /tftpboot . 170.Pp 171If booting an HP 300-series machine, ensure that 172.Pa /etc/rbootd.conf 173is configured properly to transfer the boot program to the client. 174An entry might look like this: 175.Bd -literal -offset indent -compact 17608:00:09:01:23:E6 SYS_UBOOT # myclient 177.Ed 178.Pp 179See the 180.Xr rbootd 8 181manual page for more information. 182.Pp 183.It 4. 184If booting a SPARC machine, install a copy of the appropriate diskless boot 185loader (such as 186.Pa /usr/mdec/boot ) 187in the 188.Pa /tftpboot 189directory. 190Make a link such that the boot program is 191accessible by a file name composed of the client's IP address 192in HEX, a dot, and the architecture name (all upper case). 193For example: 194.Bd -literal -offset indent -compact 195# cd /tftpboot 196# ln -s boot C0C5600C.SUN4 197.Ed 198.Pp 199For a Sun3 machine, the name would be just C0C5600C 200(the sun3 PROM does not append the architecture name). The name 201used is architecture dependent, it simply has to match what the 202booting client's PROM wishes to it to be. 203If the client's PROM fails to fetch the expected file, 204.Xr tcpdump 8 205can be used to discover which filename the client is trying to read. 206.Pp 207If booting an HP 300-series machine, ensure that the network boot program 208.Pa SYS_UBOOT 209(which may be called 210.Pa uboot.lif 211before installation) 212is installed in the directory 213.Pa /usr/mdec/rbootd . 214 215.It 5. 216Add myclient to the bootparams database 217.Pa /etc/bootparams : 218.Bd -literal -offset indent -compact 219myclient root=server:/export/myclient/root 220.Ed 221.Pp 222.It 6. 223Build the swap file for myclient: 224.Bd -literal -offset indent -compact 225# mkdir /export/myclient 226# cd /export/myclient 227# dd if=/dev/zero of=swap bs=16k count=1024 228.Ed 229This creates a 16 Megabyte swap file. 230.Pp 231.It 7. 232Populate myclient's 233.Pa / 234filesystem on the server. How this is done depends on the 235client architecture and the version of the NetBSD distribution. 236It can be as simple as copying and modifying the server's root 237filesystem, or perhaps you need to get those files out of the 238standard binary distribution. 239.Pp 240Note that, unlike SunOS, you need to create a mount point for the 241client's swap: 242.Bd -literal -offset indent -compact 243# mkdir /export/myclient/root/swap 244.Ed 245.Pp 246.It 8. 247Export the required filesystems in 248.Pa /etc/exports : 249.Bd -literal -offset indent -compact 250/usr -ro myclient 251# for SunOS: 252# /export/myclient -rw=myclient,root=myclient 253# for NetBSD: 254/export/myclient -maproot=root -alldirs myclient 255.Ed 256.Pp 257If the server and client are of the same architecture, then the client 258can share the server's 259.Pa /usr 260filesystem (as is done above). 261If not, you must build a properly fleshed out 262.Pa /usr 263partition for the client in some other place. 264.Pp 265If your server was a sparc, and your client a sun3, 266you might create and fill 267.Pa /export/usr.sun3 268and then use the following 269.Pa /etc/exports 270lines: 271.Bd -literal -offset indent -compact 272/export/usr.sun3 -ro myclient 273/export/myclient -rw=myclient,root=myclient 274.Ed 275.Pp 276.It 9. 277Copy and customize at least the following files in 278.Pa /export/myclient/root : 279.Bd -literal -offset indent -compact 280# cd /export/myclient/root/etc 281# cp fstab.nfs fstab 282# cp /etc/hosts hosts 283# echo myclient > myname 284# echo 192.197.96.12 > hostname.le0 285.Ed 286.Pp 287Note that "le0" above should be replaced with the name of 288the network interface that the client will use for booting. 289.Pp 290.It 10. 291Correct the critical mount points and the swap file in the client's 292.Pa /etc/fstab 293(which will be 294.Pa /export/myclient/root/etc/fstab ) 295ie. 296.Bd -literal -offset indent -compact 297myserver:/export/myclient/root / nfs rw 0 0 298myserver:/usr /usr nfs rw 0 0 299myserver:/export/myclient/swap none swap sw,nfsmntpt=/swap 300.Ed 301.Pp 302Note, you must specify the swap file in 303.Pa /etc/fstab 304or it will not be used! 305.El 306.Sh FILES 307.Bl -tag -width /usr/mdec/rbootd -compact 308.It Pa /etc/ethers 309Ethernet addresses of known clients 310.It Pa /etc/bootparams 311client root pathname 312.It Pa /etc/exports 313exported NFS mount points 314.It Pa /etc/rbootd.conf 315configuration file for HP Remote Boot Daemon 316.It Pa /tftpboot 317location of boot programs loaded by the Sun PROM 318.It Pa /usr/mdec/rbootd 319location of boot programs loaded by the HP Boot ROM 320.El 321.Sh "SEE ALSO" 322.Xr bootparams 5 , 323.Xr ethers 5 , 324.Xr exports 5 , 325.Xr bootparamd 8 , 326.Xr mountd 8 , 327.Xr nfsd 8 , 328.Xr rarpd 8 , 329.Xr rbootd 8 , 330.Xr reboot 8 , 331.Xr tftpd 8 332