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