1.\" $OpenBSD: diskless.8,v 1.13 2001/08/03 15:21:17 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 OpenBSD sparc tree) in the 196.Pa /tftpboot 197directory. 198Make a link such that the boot program is 199accessible by a file name composed of the client's IP address 200in HEX, a dot, and the architecture name (all upper case). 201For example: 202.Bd -literal -offset indent -compact 203# cd /tftpboot 204# ln -s boot.net C0C5600C.SUN4 205.Ed 206.Pp 207For a Sun3 machine, the name would be just C0C5600C 208(the sun3 PROM does not append the architecture name). The name 209used is architecture dependent, it simply has to match what the 210booting client's PROM wishes to it to be. 211If the client's PROM fails to fetch the expected file, 212.Xr tcpdump 8 213can be used to discover which filename the client is trying to read. 214.Pp 215If booting an HP 300-series machine, ensure that the general purpose 216boot program 217.Pa SYS_UBOOT 218(which may be called 219.Pa netboot.lif 220before installation) 221is installed in the directory 222.Pa /usr/mdec/rbootd . 223 224.It 5. 225Add myclient to the bootparams database 226.Pa /etc/bootparams : 227.Bd -literal -offset indent -compact 228myclient root=server:/export/myclient/root \\ 229 swap=server:/export/myclient/swap 230.Ed 231Note that some bootparam servers are somewhat sensitive. Some require 232fully qualified hostnames or partially qualified hostnames (which can 233be solved by having both fully and partially qualified entries). Other 234servers are case sensitive. 235.Pp 236.It 6. 237Build the swap file for myclient: 238.Bd -literal -offset indent -compact 239# mkdir /export/myclient 240# cd /export/myclient 241# dd if=/dev/zero of=swap bs=16k count=1024 242.Ed 243This creates a 16 Megabyte swap file. 244.Pp 245.It 7. 246Populate myclient's 247.Pa / 248filesystem on the server. How this is done depends on the 249client architecture and the version of the OpenBSD distribution. 250It can be as simple as copying and modifying the server's root 251filesystem, or perhaps you need to get those files out of the 252standard binary distribution. 253.Pp 254.It 8. 255Export the required filesystems in 256.Pa /etc/exports : 257.Bd -literal -offset indent -compact 258/usr -ro myclient 259# for SunOS: 260# /export/myclient -rw=myclient,root=myclient 261# for OpenBSD: 262/export/myclient -maproot=root -alldirs myclient 263.Ed 264.Pp 265If the server and client are of the same architecture, then the client 266can share the server's 267.Pa /usr 268filesystem (as is done above). 269If not, you must build a properly fleshed out 270.Pa /usr 271partition for the client in some other place. 272.Pp 273If your server was a sparc, and your client a sun3, 274you might create and fill 275.Pa /export/usr.sun3 276and then use the following 277.Pa /etc/exports 278lines: 279.Bd -literal -offset indent -compact 280/export/usr.sun3 -ro myclient 281/export/myclient -rw=myclient,root=myclient 282.Ed 283.Pp 284.It 9. 285Copy and customize at least the following files in 286.Pa /export/myclient/root : 287.Bd -literal -offset indent -compact 288# cd /export/myclient/root/etc 289# cp fstab.nfs fstab 290# cp /etc/hosts hosts 291# echo myclient > myname 292# echo inet 192.197.96.12 > hostname.le0 293.Ed 294.Pp 295Note that "le0" above should be replaced with the name of 296the network interface that the client will use for booting. 297.Pp 298.It 10. 299Correct the critical mount points in the client's 300.Pa /etc/fstab 301(which will be 302.Pa /export/myclient/root/etc/fstab ) 303i.e., 304.Bd -literal -offset indent -compact 305myserver:/export/myclient/root / nfs rw 0 0 306myserver:/usr /usr nfs rw 0 0 307.Ed 308.El 309.Sh FILES 310.Bl -tag -width /usr/mdec/rbootd -compact 311.It Pa /etc/ethers 312Ethernet addresses of known clients 313.It Pa /etc/bootparams 314client root and swap pathnames 315.It Pa /etc/exports 316exported NFS mount points 317.It Pa /etc/rbootd.conf 318configuration file for HP Remote Boot Daemon 319.It Pa /tftpboot 320location of boot programs loaded by the Sun PROM 321.It Pa /usr/mdec/rbootd 322location of boot programs loaded by the HP Boot ROM 323.El 324.Sh SEE ALSO 325.Xr rarpd 8 , 326.Xr ethers 5 , 327.Xr tftpd 8 , 328.Xr rpc.bootparamd 8 , 329.Xr bootparams 5 , 330.Xr mountd 8 , 331.Xr exports 5 , 332.Xr nfsd 8 , 333.Xr rbootd 8 , 334.Xr reboot 8 335