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