1.\" $OpenBSD: diskless.8,v 1.14 2001/08/17 11:13:58 mpech Exp $ 2.\" $NetBSD: diskless.8,v 1.7.4.1 1996/05/30 18:58:10 cgd Exp $ 3.\" 4.\" 5.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. The name of the author may not be used to endorse or promote products 17.\" derived from this software without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 20.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 21.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 22.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 23.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 24.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 28.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 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.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. 63PROM designs vary widely, so this phase is inherently 64machine-specific. 65Sun and Motorola 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. 74HP 300-series machines use the 75.Tn HP Remote Maintenance Protocol 76to download a boot program. 77Other machines may load a 78network boot program either from diskette or 79using a special PROM on the network card. 80.Pp 81In phase 2, the boot program loads a kernel. Operation in 82this phase depends on the design of the boot program. 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 and swap. 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.It 3.4 137If the kernel is configured for swap on 138.Tn NFS , 139it uses the same mechanism as for root, but uses the 140.Tn NFS 141getattr function to determine the size of the swap area. 142.El 143.Sh CONFIGURATION 144Before a client can boot over the network, 145its server must be configured correctly. 146This example will demonstrate how a Sun client 147might be configured -- other clients should be similar. 148.Pp 149Assuming the client's hostname is to be 150"myclient", 151.Pp 152.Bl -tag -width 2.1 -compact 153.It 1. 154Add an entry to 155.Pa /etc/ethers 156corresponding to the client's ethernet address: 157.Bd -literal -offset indent -compact 1588:0:20:7:c5:c7 myclient 159.Ed 160This will be used by 161.Xr rarpd 8 . 162.Pp 163.It 2. 164Assign an IP address for myclient in your 165.Pa /etc/hosts 166or DNS database: 167.Bd -literal -offset indent -compact 168192.197.96.12 myclient 169.Ed 170.Pp 171.It 3. 172If booting a Sun or Motorola client, ensure that 173.Pa /etc/inetd.conf 174is configured to run 175.Xr tftpd 8 176in the directory 177.Pa /tftpboot . 178.Pp 179If booting an HP 300-series machine, ensure that 180.Pa /etc/rbootd.conf 181is configured properly to transfer the boot program to the client. 182An entry might look like this: 183.Bd -literal -offset indent -compact 18408:00:09:01:23:E6 SYS_UBOOT # myclient 185.Ed 186.Pp 187See the 188.Xr rbootd 8 189manual page for more information. 190.Pp 191.It 4. 192If booting a Sun or Motorola client, install a copy of the 193appropriate diskless boot loader (such as 194.Pa boot.net 195from the root directory of the 196.Ox 197sparc tree) in 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.net 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 general purpose 218boot program 219.Pa SYS_UBOOT 220(which may be called 221.Pa netboot.lif 222before installation) 223is installed in the directory 224.Pa /usr/mdec/rbootd . 225 226.It 5. 227Add myclient to the bootparams database 228.Pa /etc/bootparams : 229.Bd -literal -offset indent -compact 230myclient root=server:/export/myclient/root \\ 231 swap=server:/export/myclient/swap 232.Ed 233Note that some bootparam servers are somewhat sensitive. Some require 234fully qualified hostnames or partially qualified hostnames (which can 235be solved by having both fully and partially qualified entries). Other 236servers are case sensitive. 237.Pp 238.It 6. 239Build the swap file for myclient: 240.Bd -literal -offset indent -compact 241# mkdir /export/myclient 242# cd /export/myclient 243# dd if=/dev/zero of=swap bs=16k count=1024 244.Ed 245This creates a 16 Megabyte swap file. 246.Pp 247.It 7. 248Populate myclient's 249.Pa / 250filesystem on the server. How this is done depends on the 251client architecture and the version of the 252.Ox 253distribution. 254It can be as simple as copying and modifying the server's root 255filesystem, or perhaps you need to get those files out of the 256standard binary distribution. 257.Pp 258.It 8. 259Export the required filesystems in 260.Pa /etc/exports : 261.Bd -literal -offset indent -compact 262/usr -ro myclient 263# for SunOS: 264# /export/myclient -rw=myclient,root=myclient 265# for OpenBSD: 266/export/myclient -maproot=root -alldirs myclient 267.Ed 268.Pp 269If the server and client are of the same architecture, then the client 270can share the server's 271.Pa /usr 272filesystem (as is done above). 273If not, you must build a properly fleshed out 274.Pa /usr 275partition for the client in some other place. 276.Pp 277If your server was a sparc, and your client a sun3, 278you might create and fill 279.Pa /export/usr.sun3 280and then use the following 281.Pa /etc/exports 282lines: 283.Bd -literal -offset indent -compact 284/export/usr.sun3 -ro myclient 285/export/myclient -rw=myclient,root=myclient 286.Ed 287.Pp 288.It 9. 289Copy and customize at least the following files in 290.Pa /export/myclient/root : 291.Bd -literal -offset indent -compact 292# cd /export/myclient/root/etc 293# cp fstab.nfs fstab 294# cp /etc/hosts hosts 295# echo myclient > myname 296# echo inet 192.197.96.12 > hostname.le0 297.Ed 298.Pp 299Note that "le0" above should be replaced with the name of 300the network interface that the client will use for booting. 301.Pp 302.It 10. 303Correct the critical mount points in the client's 304.Pa /etc/fstab 305(which will be 306.Pa /export/myclient/root/etc/fstab ) 307i.e., 308.Bd -literal -offset indent -compact 309myserver:/export/myclient/root / nfs rw 0 0 310myserver:/usr /usr nfs rw 0 0 311.Ed 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 and swap pathnames 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 rarpd 8 , 330.Xr ethers 5 , 331.Xr tftpd 8 , 332.Xr rpc.bootparamd 8 , 333.Xr bootparams 5 , 334.Xr mountd 8 , 335.Xr exports 5 , 336.Xr nfsd 8 , 337.Xr rbootd 8 , 338.Xr reboot 8 339