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