1.\" $OpenBSD: diskless.8,v 1.63 2014/03/18 22:36:31 miod 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 $Mdocdate: March 18 2014 $ 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 clients. 47.Pp 48When booting a system over the network, there are three 49phases of interaction between client and server: 50.Pp 51.Bl -enum -compact 52.It 53The PROM (or stage-1 bootstrap) loads a boot program. 54.It 55The boot program loads a kernel. 56.It 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 63.Em phase 1 , 64the PROM loads a boot program. 65PROM designs vary widely, so this phase is inherently 66machine-specific. 67Sun and Motorola machines use RARP to determine the client's IP address 68and then use TFTP to download a boot program 69from whoever sent the RARP reply. 70HP 300-series machines use the 71HP Remote Maintenance Protocol 72to download a boot program. 73Other machines may load a 74network boot program either from diskette or 75using a special PROM on the network card. 76.Pp 77In 78.Em phase 2 , 79the boot program loads a kernel. 80Operation in this phase depends on the design of the boot program. 81The procedure used by the boot program is as follows: 82.Pp 83.Bl -enum -compact 84.It 85The boot program 86gets the client IP address using RARP. 87.It 88The boot program 89gets the client name and server IP address by broadcasting an 90RPC/BOOTPARAMS/WHOAMI request with the client IP address. 91.It 92The boot program 93gets the server path for this client's root 94using an RPC/BOOTPARAMS/GETFILE request with the client name. 95.It 96The boot program 97gets the root file handle by calling 98.Xr mountd 8 99with the server path for the client root. 100.It 101The boot program 102gets the kernel file handle by calling 103NFS lookup on the root file handle. 104.It 105The boot program 106loads the kernel using 107NFS read calls on the kernel file handle. 108.It 109The boot program 110transfers control to the kernel entry point. 111.El 112.Pp 113In 114.Em phase 3 , 115the kernel does NFS mounts for root and swap. 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 -enum -compact 122.It 123The kernel finds a boot server using the same procedure 124as described in steps 1 and 2 of phase 2, above. 125.It 126The kernel gets the NFS 127file handle for root using the same procedure 128as described in steps 3, 4, and 5 of phase 2, above. 129.It 130The kernel calls the NFS 131getattr function to get the last-modified time of the root 132directory, and uses it to check the system clock. 133.It 134If the kernel is configured for swap on NFS, 135it uses the same mechanism as for root, but uses the NFS 136getattr function to determine the size of the swap area. 137.El 138.Pp 139The 140.No INSTALL. Ns Aq Ar arch 141notes that come with each distribution 142also give details on the specifics of net/diskless booting 143for each architecture. 144.Pp 145The procedures for AMD64 and i386 clients vary somewhat 146to the stages detailed above. 147See 148.Xr pxeboot 8 149for more detailed information. 150.Sh EXAMPLES 151Before a client can boot over the network, 152its server must be configured correctly. 153This example will demonstrate how to configure a server and client. 154.Pp 155Assuming the client's hostname is to be 156"myclient": 157.Bl -enum 158.It 159Add an entry to 160.Pa /etc/ethers 161corresponding to the client's Ethernet address: 162.Bd -literal -offset indent 1638:0:20:7:c5:c7 myclient 164.Ed 165.Pp 166This will be used by 167.Xr rarpd 8 . 168.It 169Assign an IP address for myclient in 170.Pa /etc/hosts : 171.Bd -literal -offset indent 172192.197.96.12 myclient 173.Ed 174.It 175If booting an alpha, amd64, hppa, hppa64, i386, sgi, 176sparc, sparc64, or vax client, 177ensure that 178.Xr tftpd 8 179is configured to run in the directory 180.Pa /tftpboot . 181.Pp 182If booting an HP 300 or older HPPA machine, ensure that 183.Pa /etc/rbootd.conf 184is configured properly to transfer the boot program to the client. 185An entry might look like this: 186.Bd -literal -offset indent 18708:00:09:01:23:E6 SYS_UBOOT # myclient 188.Ed 189.Pp 190See the 191.Xr rbootd 8 192manual page for more information. 193.It 194If booting a newer alpha, amd64, hppa, hppa64, i386, sgi, 195sparc, or sparc64 client, 196install a copy of the appropriate diskless boot loader (such as 197.Pa boot.net 198from the root directory of the 199.Ox 200sparc tree) in the 201.Pa /tftpboot 202directory. 203.Pp 204If booting a Motorola or Sun client, 205make a link such that the boot program is 206accessible as a file named after the client's IP address in hex. 207For example: 208.Bd -literal -offset indent 209# cd /tftpboot 210# ln -s boot.net C0C5600C 211.Ed 212.Pp 213The following example converts an IP address to hex: 214.Bd -literal -offset indent 215$ echo 192.197.96.12 | awk -F . \e 216 '{ printf "%02X%02X%02X%02X\en", $1, $2, $3, $4 }' 217.Ed 218.Pp 219Sun Sparc machines also require a 220.Dq . Ns Aq Ar arch 221suffix. 222So the filename in the example above for a Sun4 machine would be 223.Dq C0C5600C.SUN4 . 224The name used is really architecture dependent: 225it simply has to match what the booting client's PROM wishes it to be. 226If the client's PROM fails to fetch the expected file, 227.Xr tcpdump 8 228can be used to discover which filename the client is trying to read. 229.Pp 230Architectures using DHCP 231(newer alpha, amd64, hppa, hppa64, i386, or sgi) 232should ensure that 233.Xr dhcpd 8 234is configured on the server to serve BOOTP protocol requests. 235An example entry in 236.Xr dhcpd.conf 5 : 237.Bd -literal -offset indent 238subnet 10.0.0.0 netmask 255.0.0.0 { 239 host myclient { 240 filename "netboot"; 241 option root-path "/export/myclient/root"; 242 hardware ethernet 00:02:56:00:73:31; 243 fixed-address 10.42.42.42; 244 } 245} 246.Ed 247.Pp 248Note that procedures for AMD64 and i386 clients vary somewhat. 249See 250.Xr pxeboot 8 251for more detailed information. 252.Pp 253Architectures using the HP remote boot server 254(HP 300 or older HPPA) 255should ensure that the general purpose 256boot program is installed in the directory 257.Pa /usr/mdec/rbootd . 258.Pp 259Architectures using MOP 260(older Alpha and Vax) 261should follow the instructions in 262.Xr mopd 8 263for setting up a TFTP boot. 264.It 265Add myclient to the bootparams database 266.Pa /etc/bootparams : 267.Bd -literal -offset indent 268myclient root=server:/export/myclient/root \e 269 swap=server:/export/myclient/swap 270.Ed 271.Pp 272Note that some bootparam servers are somewhat sensitive. 273Some require fully qualified hostnames or partially qualified hostnames 274(which can be solved by having both fully and partially qualified entries). 275Other servers are case sensitive. 276.It 277Build the swap file for myclient: 278.Bd -literal -offset indent 279# mkdir -p /export/myclient/root/swap 280# cd /export/myclient 281# dd if=/dev/zero of=swap bs=1m count=120 282.Ed 283.Pp 284This creates a 120 Megabyte swap file and an empty /swap directory. 285A smaller swap file may be created if the boot is for 286maintenance (i.e. temporary) purposes only. 287.It 288Populate myclient's root 289filesystem on the server. 290How this is done depends on the client architecture and the version of the 291.Ox 292distribution. 293It can be as simple as copying and modifying the server's root 294filesystem, or perhaps the files can be taken from the 295standard binary distribution. 296.It 297Export the required filesystems in 298.Pa /etc/exports : 299.Bd -literal -offset indent 300/usr -ro myclient 301/export/myclient -maproot=root -alldirs myclient 302.Ed 303.Pp 304If the server and client are of the same architecture, then the client 305can share the server's 306.Pa /usr 307filesystem (as is done above). 308If not, a properly fleshed out 309.Pa /usr 310partition will have to be built for the client in some other place. 311.It 312Copy and customize at least the following files in 313.Pa /export/myclient/root : 314.Bd -literal -offset indent 315# cd /export/myclient/root/etc 316# cp /etc/fstab fstab 317# cp /etc/hosts hosts 318# echo myclient \*(Gt myname 319# echo inet 192.197.96.12 \*(Gt hostname.le0 320.Ed 321.Pp 322Note that "le0" above should be replaced with the name of 323the network interface that the client will use for booting. 324.It 325Correct at least 326the critical mount points in the client's 327.Xr fstab 5 328(which will be 329.Pa /export/myclient/root/etc/fstab ) : 330.Bd -literal -offset indent 331myserver:/export/myclient/root / nfs rw 0 0 332myserver:/export/myclient/swap none swap sw,nfsmntpt=/swap 333myserver:/export/myclient/root/usr /usr nfs rw,nodev 0 0 334myserver:/export/myclient/root/var /var nfs rw,nosuid,nodev 0 0 335.Ed 336.Pp 337The above example works even if 338.Pa /usr 339and 340.Pa /var 341are not on separate partitions. 342It allows them to be mounted with NFSv3, 343if the server allows it, 344and to specify per-partition mount options, 345such as 346.Dq nodev . 347.Pp 348If the 349.Pa /usr 350partition is to be shared between machines, 351as in the example 352.Pa /etc/exports 353above, a more suitable entry might be: 354.Bd -literal -offset indent 355myserver:/usr /usr nfs ro 0 0 356.Ed 357.It 358Make sure the correct processes are enabled on the server. 359See 360.Xr rc.conf 8 361for details of how to start these processes at boot. 362.Pp 363For all clients: 364.Xr mountd 8 , 365.Xr nfsd 8 , 366.Xr portmap 8 , 367.Xr rarpd 8 , 368and 369.Xr rpc.bootparamd 8 . 370.Pp 371For alpha, amd64, hppa, hppa64, i386, sgi, sparc, sparc64, and vax clients: 372.Xr tftpd 8 373.Pp 374For HP 300 and older HPPA clients: 375.Xr rbootd 8 376.Pp 377For newer alpha, amd64, hppa, hppa64, i386, and sgi clients: 378.Xr dhcpd 8 379.Pp 380For older alpha and vax clients: 381.Xr mopd 8 382.It 383Net boot the client. 384.El 385.Sh FILES 386.Bl -tag -width "/usr/mdec/rbootdXX" -compact 387.It /etc/bootparams 388Client root and swap pathnames. 389.It /etc/dhcpd.conf 390DHCP daemon configuration file. 391.It /etc/ethers 392Ethernet addresses of known clients. 393.It /etc/exports 394Exported NFS mount points. 395.It /etc/fstab 396Static information about the filesystems. 397.It /etc/hostname.$if 398Interface-specific configuration file. 399.It /etc/hosts 400Host name database. 401.It /etc/myname 402Default hostname and gateway. 403.It /etc/rbootd.conf 404Configuration file for HP Remote Boot Daemon. 405.It /tftpboot 406Location of boot programs loaded by the Sun PROM. 407.It /usr/mdec/rbootd 408Location of boot programs loaded by the HP Boot ROM. 409.El 410.Sh SEE ALSO 411.Xr bootparams 5 , 412.Xr dhcpd.conf 5 , 413.Xr ethers 5 , 414.Xr exports 5 , 415.Xr fstab 5 , 416.Xr hostname.if 5 , 417.Xr hosts 5 , 418.Xr myname 5 , 419.Xr dhcpd 8 , 420.Xr mopd 8 , 421.Xr mountd 8 , 422.Xr nfsd 8 , 423.Xr portmap 8 , 424.Xr pxeboot 8 , 425.Xr rarpd 8 , 426.Xr rbootd 8 , 427.Xr rpc.bootparamd 8 , 428.Xr tcpdump 8 , 429.Xr tftpd 8 430