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.\" $FreeBSD$ 29.\" 30.Dd October 2, 1994 31.Dt DISKLESS 8 32.Os 33.Sh NAME 34.Nm diskless 35.Nd booting a system over the network 36.Sh DESCRIPTION 37The ability to boot a machine over the network is useful for 38.Xr diskless 39or 40.Xr dataless 41machines, or as a temporary measure while repairing or 42re-installing filesystems on a local disk. 43This file provides a general description of the interactions between 44a client and its server when a client is booting over the network. 45The general description is followed by specific instructions for 46configuring a server for diskless Sun clients. 47.Pp 48.Sh OPERATION 49When booting a system over the network, there are three 50phases of interaction between client and server: 51.Pp 52.Bl -tag -width 1.2 -compact 53.It 1. 54The PROM (or stage-1 bootstrap) loads a boot program. 55.It 2. 56The boot program loads a kernel. 57.It 3. 58The kernel does NFS mounts for root. 59.El 60.Pp 61Each of these phases are described in further detail below. 62.Pp 63In phase 1, the PROM loads a boot program. PROM designs 64vary widely, so this phase is inherently machine-specific. 65Sun machines use 66.Tn RARP 67to determine the client's 68.Tn IP 69address and then use 70.Tn TFTP 71to download a boot program from whoever sent the 72.Tn RARP 73reply. HP 300-series machines use the 74.Tn HP Remote Maintenance Protocol 75to download a boot program. 76Typical personal computers may load a 77network boot program either from diskette or 78using a special PROM on the network card. 79.Pp 80In phase 2, the boot program loads a kernel. Operation in 81this phase depends on the design of the boot program. 82(The design described here is the one used by Sun and NetBSD/hp300.) 83The boot program: 84.Pp 85.Bl -tag -width 2.2 -compact 86.It 2.1 87gets the client IP address using 88.Tn RARP . 89.It 2.2 90gets the client name and server 91.Tn IP 92address by broadcasting an 93.Tn RPC / BOOTPARAMS / WHOAMI 94request with the client IP address. 95.It 2.3 96gets the server path for this client's 97root using an 98.Tn RPC / BOOTPARAMS / GETFILE 99request with the client name. 100.It 2.4 101gets the root file handle by calling 102.Xr mountd 8 103with the server path for the client root. 104.It 2.5 105gets the kernel file handle by calling 106.Tn NFS 107lookup on the root file handle. 108.It 2.6 109loads the kernel using 110.Tn NFS 111read calls on the kernel file handle. 112.It 2.7 113transfers control to the kernel entry point. 114.El 115.Pp 116In phase 3, the kernel does NFS mounts for root. 117The kernel repeats much of the work done by the boot program 118because there is no standard way for the boot program to pass 119the information it gathered on to the kernel. 120The procedure used by the kernel is as follows: 121.Pp 122.Bl -tag -width 2.2 -compact 123.It 3.1 124The kernel finds a boot server using the same procedure 125as described in steps 2.1 and 2.2 above. 126.It 3.2 127The kernel gets the 128.Tn NFS 129file handle for root using the same procedure 130as described in steps 2.3 through 2.5 above. 131.It 3.3 132The kernel calls the 133.Tn NFS 134getattr function to get the last-modified time of the root 135directory, and uses it to check the system clock. 136.El 137.Sh CONFIGURATION 138Before a client can boot over the network, 139its server must be configured correctly. 140This example will demonstrate how a Sun client 141might be configured -- other clients should be similar. 142.Pp 143Assuming the client's hostname is to be 144"myclient", 145.Pp 146.Bl -tag -width 2.1 -compact 147.It 1. 148Add an entry to 149.Pa /etc/ethers 150corresponding to the client's ethernet address: 151.Bd -literal -offset indent -compact 1528:0:20:7:c5:c7 myclient 153.Ed 154This will be used by 155.Xr rarpd 8 . 156.Pp 157.It 2. 158Assign an IP address for myclient in your 159.Pa /etc/hosts 160or DNS database: 161.Bd -literal -offset indent -compact 162192.197.96.12 myclient 163.Ed 164.Pp 165.It 3. 166If booting a Sun machine, ensure that 167.Pa /etc/inetd.conf 168is configured to run 169.Xr tftpd 8 170in the directory 171.Pa /tftpboot . 172.Pp 173If booting an HP 300-series machine, ensure that 174.Pa /etc/rbootd.conf 175is configured properly to transfer the boot program to the client. 176An entry might look like this: 177.Bd -literal -offset indent -compact 17808:00:09:01:23:E6 SYS_UBOOT # myclient 179.Ed 180.Pp 181See the 182.Xr rbootd 8 183manual page for more information. 184.Pp 185.It 4. 186If booting a SPARC machine, install a copy of the appropriate diskless boot 187loader (such as 188.Pa /usr/mdec/boot ) 189in the 190.Pa /tftpboot 191directory. 192Make a link such that the boot program is 193accessible by a file name composed of the client's IP address 194in HEX, a dot, and the architecture name (all upper case). 195For example: 196.Bd -literal -offset indent -compact 197# cd /tftpboot 198# ln -s boot C0C5600C.SUN4 199.Ed 200.Pp 201For a Sun3 machine, the name would be just C0C5600C 202(the sun3 PROM does not append the architecture name). The name 203used is architecture dependent, it simply has to match what the 204booting client's PROM wishes to it to be. 205If the client's PROM fails to fetch the expected file, 206.Xr tcpdump 1 207can be used to discover which filename the client is trying to read. 208.Pp 209If booting an HP 300-series machine, ensure that the network boot program 210.Pa SYS_UBOOT 211(which may be called 212.Pa uboot.lif 213before installation) 214is installed in the directory 215.Pa /usr/mdec/rbootd . 216 217.It 5. 218Add myclient to the bootparams database 219.Pa /etc/bootparams : 220.Bd -literal -offset indent -compact 221myclient root=server:/export/myclient/root 222.Ed 223.Pp 224.It 6. 225Build the swap file for myclient: 226.Bd -literal -offset indent -compact 227# mkdir /export/myclient 228# cd /export/myclient 229# dd if=/dev/zero of=swap bs=16k count=1024 230.Ed 231This creates a 16 Megabyte swap file. 232.Pp 233.It 7. 234Populate myclient's 235.Pa / 236filesystem on the server. How this is done depends on the 237client architecture and the version of the NetBSD distribution. 238It can be as simple as copying and modifying the server's root 239filesystem, or perhaps you need to get those files out of the 240standard binary distribution. 241.Pp 242Note that, unlike SunOS, you need to create a mount point for the 243client's swap: 244.Bd -literal -offset indent -compact 245# mkdir /export/myclient/root/swap 246.Ed 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 and the swap file 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 301myserver:/export/myclient/swap none swap sw,nfsmntpt=/swap 302.Ed 303.Pp 304Note, you must specify the swap file in 305.Pa /etc/fstab 306or it will not be used! 307.El 308.Sh FILES 309.Bl -tag -width /usr/mdec/rbootd -compact 310.It Pa /etc/ethers 311Ethernet addresses of known clients 312.It Pa /etc/bootparams 313client root pathname 314.It Pa /etc/exports 315exported NFS mount points 316.It Pa /etc/rbootd.conf 317configuration file for HP Remote Boot Daemon 318.It Pa /tftpboot 319location of boot programs loaded by the Sun PROM 320.It Pa /usr/mdec/rbootd 321location of boot programs loaded by the HP Boot ROM 322.El 323.Sh "SEE ALSO" 324.Xr bootparams 5 , 325.Xr ethers 5 , 326.Xr exports 5 , 327.Xr bootparamd 8 , 328.Xr mountd 8 , 329.Xr nfsd 8 , 330.Xr rarpd 8 , 331.Xr rbootd 8 , 332.Xr reboot 8 , 333.Xr tftpd 8 334