1.\" $NetBSD: diskless.8,v 1.2 1994/11/30 19:36:23 jtc 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. Typical personal computers may load a 73network boot program either from diskette or 74using a special PROM on the network card. 75.Pp 76In phase 2, the boot program loads a kernel. Operation in 77this phase depends on the design of the boot program. 78(The design described here is the one used by Sun.) 79The boot program: 80.Pp 81.Bl -tag -width 2.2 -compact 82.It 2.1 83gets the client IP address using 84.Tn RARP . 85.It 2.2 86gets the client name and server 87.Tn IP 88address by broadcasting an 89.Tn RPC / BOOTPARAMS / WHOAMI 90request with the client IP address. 91.It 2.3 92gets the server path for this client's 93root using an 94.Tn RPC / BOOTPARAMS / GETFILE 95request with the client name. 96.It 2.4 97gets the root file handle by calling 98.Xr mountd 8 99with the server path for the client root. 100.It 2.5 101gets the kernel file handle by calling 102.Tn NFS 103lookup on the root file handle. 104.It 2.6 105loads the kernel using 106.Tn NFS 107read calls on the kernel file handle. 108.It 2.7 109transfers control to the kernel entry point. 110.El 111.Pp 112In phase 3, the kernel does NFS mounts for root and swap. 113The kernel repeats much of the work done by the boot program 114because there is no standard way for the boot program to pass 115the information it gathered on to the kernel. 116The procedure used by the kernel is as follows: 117.Pp 118.Bl -tag -width 2.2 -compact 119.It 3.1 120The kernel finds a boot server using the same procedure 121as described in steps 2.1 and 2.2 above. 122.It 3.2 123The kernel gets the 124.Tn NFS 125file handle for root using the same procedure 126as described in steps 2.3 through 2.5 above. 127.It 3.3 128The kernel calls the 129.Tn NFS 130getattr function to get the last-modified time of the root 131directory, and uses it to check the system clock. 132.It 3.4 133If the kernel is configured for swap on 134.Tn NFS , 135it uses the same mechanism as for root, but uses the 136.Tn NFS 137getattr funciton to determine the size of the swap area. 138.El 139.Sh CONFIGURATION 140Before a client can boot over the network, 141its server must be configured correctly. 142This example will demonstrate how a NetBSD/sun3 client 143might be configured -- other setups will be similar. 144.Pp 145Assuming the client's hostname is to be 146"myclient", 147.Pp 148.Bl -tag -width 2.1 -compact 149.It 1. 150Add an entry to 151.Pa /etc/ethers 152corresponding to the client's ethernet address: 153.Bd -literal -offset indent -compact 1548:0:20:7:c5:c7 myclient 155.Ed 156This will be used by 157.Xr rarpd 8 . 158.Pp 159.It 2. 160Assign an IP address for myclient in your 161.Pa /etc/hosts 162or DNS database: 163.Bd -literal -offset indent -compact 164192.197.96.12 myclient 165.Ed 166.Pp 167.It 3. 168Ensure that 169.Pa /etc/inetd.conf 170is configured to run 171.Xr tftpd 8 172in the directory 173.Pa /tftpboot . 174.Pp 175.It 4. 176Install a copy of the appropriate diskless boot loader (such as 177.Pa boot.sun3.sunos.4.1.1 178from the SunOS media) in the 179.Pa /tftpboot 180directory. 181Make a link such that the boot program is 182accessible by a file name composed of the client's IP adddress 183in HEX, a dot, and the architecture name (all upper case). 184For example: 185.Bd -literal -offset indent -compact 186# cd /tftpboot 187# ln -s boot.sun3.sunos.4.1.1 C0C5600C.SUN3 188.Ed 189.Pp 190For a Sun4C machine, the name would be C0C5600C.SUN4C. The name 191used is architecture dependent, it simply has to match what the 192booting client's rom wishes to it to be. 193If the client's PROM fails to fetch the expected file, 194.Xr tcpdump 8 195can be used to discover which filename the client is trying to read. 196.Pp 197.It 5. 198Add myclient to the bootparams database 199.Pa /etc/bootparams : 200.Bd -literal -offset indent -compact 201myclient root=server:/export/myclient/root \\ 202 swap=server:/export/myclient/swap 203.Ed 204.Pp 205.It 6. 206Build the swap file for myclient: 207.Bd -literal -offset indent -compact 208# mkdir /export/myclient 209# cd /export/myclient 210# dd if=/dev/zero of=swap bs=16k count=1024 211.Ed 212This creates a 16 Megabyte swap file. 213.Pp 214.It 7. 215Populate myclient's 216.Pa / 217filesystem on the server. How this is done depends on the 218client architecture and the version of the NetBSD distribution. 219It can be as simple as copying and modifying the server's root 220filesystem, or perhaps you need to get those files out of the 221standard binary distribution. 222.Pp 223.It 8. 224Export the required filesystems in 225.Pa /etc/exports : 226.Bd -literal -offset indent -compact 227/usr -ro myclient 228/export/myclient -rw=myclient,root=myclient 229.Ed 230.Pp 231If the server and client are of the same architecture, then the client 232can share the server's 233.Pa /usr 234filesystem (as is done above). 235If not, you must build a properly fleshed out 236.Pa /usr 237partition for the client in some other place. 238.Pp 239If your server was a sparc, and your client a sun3, 240you might create and fill 241.Pa /export/usr.sun3 242and then use the following 243.Pa /etc/exports 244lines: 245.Bd -literal -offset indent -compact 246/export/usr.sun3 -ro myclient 247/export/myclient -rw=myclient,root=myclient 248.Ed 249.Pp 250.It 9. 251Copy and customize at least the following files in 252.Pa /export/myclient/root : 253.Bd -literal -offset indent -compact 254# cd /export/myclient/root/etc 255# cp fstab.nfs fstab 256# cp /etc/hosts hosts 257# echo myclient > myname 258# echo 192.197.96.12 > hostname.le0 259.Ed 260.Pp 261Note that "le0" above should be replaced with the name of 262the network interface that the client will use for booting. 263.Pp 264.It 10. 265Correct the critical mountpoints in the client's 266.Pa /etc/fstab 267(which will be 268.Pa /export/myclient/root/etc/fstab ) 269ie. 270.Bd -literal -offset indent -compact 271myserver:/export/myclient/root / nfs rw 0 0 272myserver:/usr /usr nfs rw 0 0 273.Ed 274.El 275.Sh FILES 276.Bl -tag -width /etc/bootparams -compact 277.It Pa /etc/ethers 278Ethernet addresses of known clients 279.It Pa /tftpboot 280location of boot programs loaded by PROM 281.It Pa /etc/bootparams 282client root and swap pathnames 283.It Pa /etc/exports 284exported NFS mount points 285.El 286.Sh "SEE ALSO" 287.Xr diskless 8 , 288.Xr rarpd 8 , 289.Xr ethers 5 , 290.Xr tftpd 8 , 291.Xr rpc.bootparamd 8 , 292.Xr bootparams 5 , 293.Xr mountd 8 , 294.Xr exports 5 , 295.Xr nfsd 8 , 296.Xr reboot 8 297