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 224Note: For the swap file to be mountable, you have to make sure that mountd is 225started with the 226.Fl r 227flag. 228 229.It 6. 230Build the swap file for myclient: 231.Bd -literal -offset indent -compact 232# mkdir /export/myclient 233# cd /export/myclient 234# dd if=/dev/zero of=swap bs=16k count=1024 235.Ed 236This creates a 16 Megabyte swap file. 237.Pp 238.It 7. 239Populate myclient's 240.Pa / 241filesystem on the server. How this is done depends on the 242client architecture and the version of the NetBSD distribution. 243It can be as simple as copying and modifying the server's root 244filesystem, or perhaps you need to get those files out of the 245standard binary distribution. 246.Pp 247Note that, unlike SunOS, you need to create a mount point for the 248client's swap: 249.Bd -literal -offset indent -compact 250# mkdir /export/myclient/root/swap 251.Ed 252.Pp 253.It 8. 254Export the required filesystems in 255.Pa /etc/exports : 256.Bd -literal -offset indent -compact 257/usr -ro myclient 258# for SunOS: 259# /export/myclient -rw=myclient,root=myclient 260# for NetBSD: 261/export/myclient -maproot=root -alldirs myclient 262.Ed 263.Pp 264If the server and client are of the same architecture, then the client 265can share the server's 266.Pa /usr 267filesystem (as is done above). 268If not, you must build a properly fleshed out 269.Pa /usr 270partition for the client in some other place. 271.Pp 272If your server was a sparc, and your client a sun3, 273you might create and fill 274.Pa /export/usr.sun3 275and then use the following 276.Pa /etc/exports 277lines: 278.Bd -literal -offset indent -compact 279/export/usr.sun3 -ro myclient 280/export/myclient -rw=myclient,root=myclient 281.Ed 282.Pp 283.It 9. 284Copy and customize at least the following files in 285.Pa /export/myclient/root : 286.Bd -literal -offset indent -compact 287# cd /export/myclient/root/etc 288# cp fstab.nfs fstab 289# cp /etc/hosts hosts 290# echo myclient > myname 291# echo 192.197.96.12 > hostname.le0 292.Ed 293.Pp 294Note that "le0" above should be replaced with the name of 295the network interface that the client will use for booting. 296.Pp 297.It 10. 298Correct the critical mount points and the swap file in the client's 299.Pa /etc/fstab 300(which will be 301.Pa /export/myclient/root/etc/fstab ) 302ie. 303.Bd -literal -offset indent -compact 304myserver:/export/myclient/root / nfs rw 0 0 305myserver:/usr /usr nfs rw 0 0 306myserver:/export/myclient/swap none swap sw,nfsmntpt=/swap 307.Ed 308.Pp 309Note, you must specify the swap file in 310.Pa /etc/fstab 311or it will not be used! 312.El 313.Sh FILES 314.Bl -tag -width /usr/mdec/rbootd -compact 315.It Pa /etc/ethers 316Ethernet addresses of known clients 317.It Pa /etc/bootparams 318client root pathname 319.It Pa /etc/exports 320exported NFS mount points 321.It Pa /etc/rbootd.conf 322configuration file for HP Remote Boot Daemon 323.It Pa /tftpboot 324location of boot programs loaded by the Sun PROM 325.It Pa /usr/mdec/rbootd 326location of boot programs loaded by the HP Boot ROM 327.El 328.Sh "SEE ALSO" 329.Xr bootparams 5 , 330.Xr ethers 5 , 331.Xr exports 5 , 332.Xr bootparamd 8 , 333.Xr mountd 8 , 334.Xr nfsd 8 , 335.Xr rarpd 8 , 336.Xr rbootd 8 , 337.Xr reboot 8 , 338.Xr tftpd 8 339