1.\" $NetBSD: diskless.8,v 1.22 2002/02/13 08:18:23 ross 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 January 25, 1998 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.Em diskless 37or 38.Em dataless 39machines, or as a temporary measure while repairing or 40re-installing file systems 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.Sh OPERATION 46When booting a system over the network, there are three 47phases of interaction between client and server: 48.Pp 49.Bl -tag -width 1.2 -compact 50.It 1 . 51The PROM (or stage-1 bootstrap) loads a boot program. 52.It 2 . 53The boot program loads a kernel. 54.It 3 . 55The kernel does 56.Tn NFS 57mounts for root. 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 whomever 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 82.Nx Ns Tn /hp300 Ns . ) 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 117.Tn NFS 118mounts for root. 119The kernel repeats much of the work done by the boot program 120because there is no standard way for the boot program to pass 121the information it gathered on to the kernel. 122The procedure used by the kernel is as follows: 123.Pp 124.Bl -tag -width 2.2 -compact 125.It 3.1 126The kernel finds a boot server using the same procedure 127as described in steps 2.1 and 2.2 above. 128In general, the GENERIC 129.Xr config 8 130files 131for any particular architecture will specify options to activate in 132the kernel the 133same protocol used by the boot program for that 134architecture, however, the kernel can 135be compiled to use any of BOOTP, DHCP, or BOOTPARAMS. See 136.Xr options 4 . 137.It 3.2 138The kernel gets the 139.Tn NFS 140file handle for root using the same procedure 141as described in steps 2.3 through 2.5 above. 142.It 3.3 143The kernel calls the 144.Tn NFS 145getattr function to get the last-modified time of the root 146directory, and uses it to check the system clock. 147.El 148.Sh CONFIGURATION 149Before a client can boot over the network, 150its server must be configured correctly. 151This example will demonstrate how a Sun client 152might be configured -- other clients should be similar. 153.Pp 154Assuming the client's hostname is to be 155.Dq myclient , 156.Pp 157.Bl -tag -width 2.1 -compact 158.It 1 . 159Add an entry to 160.Pa /etc/ethers 161corresponding to the client's ethernet address: 162.Bd -literal -offset indent -compact 1638:0:20:7:c5:c7 myclient 164.Ed 165This will be used by 166.Xr rarpd 8 . 167.Pp 168.It 2 . 169Assign an IP address for myclient in your 170.Pa /etc/hosts 171or DNS database: 172.Bd -literal -offset indent -compact 173192.197.96.12 myclient 174.Ed 175.Pp 176.It 3 . 177If booting a Sun machine, ensure that 178.Pa /etc/inetd.conf 179is configured to run 180.Xr tftpd 8 181in the directory 182.Pa /tftpboot . 183.Pp 184If booting an HP 300-series machine, ensure that 185.Pa /etc/rbootd.conf 186is configured properly to transfer the boot program to the client. 187An entry might look like this: 188.Bd -literal -offset indent -compact 18908:00:09:01:23:E6 SYS_UBOOT # myclient 190.Ed 191.Pp 192See the 193.Xr rbootd 8 194manual page for more information. 195.Pp 196.It 4 . 197If booting a SPARC machine, install a copy of the appropriate diskless boot 198loader (such as 199.Pa /usr/mdec/boot 200or 201.Pa ofwboot.net ) 202in the 203.Pa /tftpboot 204directory. 205Make a link such that the boot program is 206accessible by a file name composed of the client's IP address 207in HEX, a dot, and the architecture name (all upper case). 208For example: 209.Bd -literal -offset indent -compact 210# cd /tftpboot 211# ln -s boot C0C5600C.SUN4 212.Ed 213.Pp 214For a Sun3 or Ultra Sparc machine, the name would be just C0C5600C 215(there the PROM does not append the architecture name). The name 216used is architecture dependent, it simply has to match what the 217booting client's PROM wishes to it to be. 218If the client's PROM fails to fetch the expected file, 219.Xr tcpdump 8 220can be used to discover which filename the client is trying to read. 221.Pp 222If booting an HP 300-series machine, ensure that the network boot program 223.Pa SYS_UBOOT 224(which may be called 225.Pa uboot.lif 226before installation) 227is installed in the directory 228.Pa /usr/mdec/rbootd . 229.Pp 230.It 5 . 231Add myclient to the bootparams database 232.Pa /etc/bootparams : 233.Bd -literal -offset indent -compact 234myclient root=server:/export/myclient/root \\ 235 gateway=mygw:255.255.255.0 236.Ed 237and ensure that 238.Xr rpc.bootparamd 8 239is running. 240.Pp 241.It 6 . 242Build the swap file for myclient: 243.Bd -literal -offset indent -compact 244# cd /export/myclient/root 245# dd if=/dev/zero of=swap bs=16k count=1024 246.Ed 247This creates a 16 Megabyte swap file. 248.Pp 249.It 7 . 250Populate myclient's 251.Pa / 252file system on the server. How this is done depends on the 253client architecture and the version of the 254.Nx 255distribution. 256It can be as simple as copying and modifying the server's root 257file system, or perhaps you need to get those files out of the 258standard binary distribution. 259.Pp 260.It 8 . 261Export the required file systems in 262.Pa /etc/exports : 263.Bd -literal -offset indent -compact 264/usr -ro myclient 265# for SunOS: 266# /export/myclient -rw=myclient,root=myclient 267# for NetBSD: 268/export/myclient -maproot=root -alldirs myclient 269.Ed 270.Pp 271If the server and client are of the same architecture, then the client 272can share the server's 273.Pa /usr 274file system (as is done above). 275If not, you must build a properly fleshed out 276.Pa /usr 277partition for the client in some other place. 278.Pp 279If your server was a sparc, and your client a sun3, 280you might create and fill 281.Pa /export/usr.sun3 282and then use the following 283.Pa /etc/exports 284lines: 285.Bd -literal -offset indent -compact 286/export/usr.sun3 -ro myclient 287/export/myclient -rw=myclient,root=myclient 288.Ed 289.Pp 290Of course, in either case you will have to have an 291.Tn NFS 292server running on the server side. 293.Pp 294.It 9 . 295Copy and customize at least the following files in 296.Pa /export/myclient/root : 297.Bd -literal -offset indent -compact 298# cd /export/myclient/root/etc 299# vi fstab 300# cp /etc/hosts hosts 301# echo 'hostname="myclient"' \*[Gt]\*[Gt] rc.conf 302# echo "inet 192.197.96.12" \*[Gt] ifconfig.le0 303.Ed 304.Pp 305Note that "le0" above should be replaced with the name of 306the network interface that the client will use for booting. 307.Pp 308.It 10 . 309Correct the critical mount points and the swap file in the client's 310.Pa /etc/fstab 311(which will be 312.Pa /export/myclient/root/etc/fstab ) 313i.e. 314.Bd -literal -offset indent -compact 315myserver:/export/myclient/root / nfs rw 0 0 316myserver:/usr /usr nfs rw 0 0 317/swap none swap sw 318.Ed 319.Pp 320Note, you must specify the swap file in 321.Pa /etc/fstab 322or it will not be used! 323.El 324.Sh FILES 325.Bl -tag -width /usr/mdec/rbootd -compact 326.It Pa /etc/ethers 327Ethernet addresses of known clients 328.It Pa /etc/bootparams 329client root pathname 330.It Pa /etc/exports 331exported 332.Tn NFS 333mount points 334.It Pa /etc/rbootd.conf 335configuration file for HP Remote Boot Daemon 336.It Pa /tftpboot 337location of boot programs loaded by the Sun PROM 338.It Pa /usr/mdec/rbootd 339location of boot programs loaded by the HP Boot ROM 340.El 341.Sh SEE ALSO 342.Xr bootparams 5 , 343.Xr ethers 5 , 344.Xr exports 5 , 345.Xr mountd 8 , 346.Xr nfsd 8 , 347.Xr rarpd 8 , 348.Xr rbootd 8 , 349.Xr reboot 8 , 350.Xr rpc.bootparamd 8 , 351.Xr tftpd 8 352