1.\" $OpenBSD: diskless.8,v 1.72 2022/06/26 12:34:41 deraadt 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: June 26 2022 $ 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.Pa 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, i386, 176or sparc64 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, i386, 195or sparc64 client, 196install a copy of the appropriate diskless boot loader in the 197.Pa /tftpboot 198directory. 199.Pp 200If booting a Motorola or Sun client, 201make a link such that the boot program is 202accessible as a file named after the client's IP address in hex. 203For example: 204.Bd -literal -offset indent 205# cd /tftpboot 206# ln -s boot.net C0C5600C 207.Ed 208.Pp 209The following example converts an IP address to hex: 210.Bd -literal -offset indent 211$ echo 192.197.96.12 | awk -F . \e 212 '{ printf "%02X%02X%02X%02X\en", $1, $2, $3, $4 }' 213.Ed 214.Pp 215Sun Sparc machines also require a 216.Dq . Ns Aq Ar arch 217suffix. 218So the filename in the example above for a Sun4 machine would be 219.Dq C0C5600C.SUN4 . 220The name used is really architecture dependent: 221it simply has to match what the booting client's PROM wishes it to be. 222If the client's PROM fails to fetch the expected file, 223.Xr tcpdump 8 224can be used to discover which filename the client is trying to read. 225.Pp 226Architectures using DHCP 227(newer alpha, amd64, hppa, or i386) 228should ensure that 229.Xr dhcpd 8 230is configured on the server to serve BOOTP protocol requests. 231An example entry in 232.Xr dhcpd.conf 5 : 233.Bd -literal -offset indent 234subnet 10.0.0.0 netmask 255.0.0.0 { 235 host myclient { 236 filename "netboot"; 237 option root-path "/export/myclient/root"; 238 hardware ethernet 00:02:56:00:73:31; 239 fixed-address 10.42.42.42; 240 } 241} 242.Ed 243.Pp 244Note that procedures for AMD64 and i386 clients vary somewhat. 245See 246.Xr pxeboot 8 247for more detailed information. 248.Pp 249Architectures using the HP remote boot server 250(HP 300 or older HPPA) 251should ensure that the general purpose 252boot program is installed in the directory 253.Pa /usr/mdec/rbootd . 254.Pp 255Architectures using MOP 256(older Alpha) 257should follow the instructions in 258.Xr mopd 8 259for setting up a TFTP boot. 260.It 261Add myclient to the bootparams database 262.Pa /etc/bootparams : 263.Bd -literal -offset indent 264myclient root=server:/export/myclient/root \e 265 swap=server:/export/myclient/swap 266.Ed 267.Pp 268Note that some bootparam servers are somewhat sensitive. 269Some require fully qualified hostnames or partially qualified hostnames 270(which can be solved by having both fully and partially qualified entries). 271Other servers are case sensitive. 272.It 273Build the swap file for myclient: 274.Bd -literal -offset indent 275# mkdir -p /export/myclient/root/swap 276# cd /export/myclient 277# dd if=/dev/zero of=swap bs=1m count=120 278.Ed 279.Pp 280This creates a 120 Megabyte swap file and an empty /swap directory. 281A smaller swap file may be created if the boot is for 282maintenance (i.e. temporary) purposes only. 283.It 284Populate myclient's root 285filesystem on the server. 286How this is done depends on the client architecture and the version of the 287.Ox 288distribution. 289It can be as simple as copying and modifying the server's root 290filesystem, or perhaps the files can be taken from the 291standard binary distribution. 292.It 293Export the required filesystems in 294.Pa /etc/exports : 295.Bd -literal -offset indent 296/usr -ro myclient 297/export/myclient -maproot=root -alldirs myclient 298.Ed 299.Pp 300If the server and client are of the same architecture, then the client 301can share the server's 302.Pa /usr 303filesystem (as is done above). 304If not, a properly fleshed out 305.Pa /usr 306partition will have to be built for the client in some other place. 307.It 308Copy and customize at least the following files in 309.Pa /export/myclient/root : 310.Bd -literal -offset indent 311# cd /export/myclient/root/etc 312# cp /etc/fstab fstab 313# cp /etc/hosts hosts 314# echo myclient > myname 315# echo inet 192.197.96.12 > hostname.le0 316.Ed 317.Pp 318Note that "le0" above should be replaced with the name of 319the network interface that the client will use for booting. 320.It 321Correct at least 322the critical mount points in the client's 323.Xr fstab 5 324(which will be 325.Pa /export/myclient/root/etc/fstab ) : 326.Bd -literal -offset indent 327myserver:/export/myclient/root / nfs rw 0 0 328myserver:/export/myclient/swap none swap sw,nfsmntpt=/swap 329myserver:/export/myclient/root/usr /usr nfs rw,nodev 0 0 330.Ed 331.Pp 332The above example works even if 333.Pa /usr 334is not on a separate partition. 335It allows them to be mounted with NFSv3, 336if the server allows it, 337and to specify per-partition mount options, 338such as 339.Cm nodev . 340.Pp 341If the 342.Pa /usr 343partition is to be shared between machines, 344as in the example 345.Pa /etc/exports 346above, a more suitable entry might be: 347.Bd -literal -offset indent 348myserver:/usr /usr nfs ro 0 0 349.Ed 350.It 351Make sure the correct processes are enabled on the server. 352See 353.Xr rc.conf 8 354for details of how to start these processes at boot. 355.Pp 356For all clients: 357.Xr mountd 8 , 358.Xr nfsd 8 , 359.Xr portmap 8 , 360.Xr rarpd 8 , 361and 362.Xr rpc.bootparamd 8 . 363.Pp 364For alpha, amd64, hppa, i386, and sparc64 clients: 365.Xr tftpd 8 366.Pp 367For HP 300 and older HPPA clients: 368.Xr rbootd 8 369.Pp 370For newer alpha, amd64, hppa, and i386 clients: 371.Xr dhcpd 8 372.Pp 373For older alpha clients: 374.Xr mopd 8 375.It 376Net boot the client. 377.El 378.Sh FILES 379.Bl -tag -width "/usr/mdec/rbootdXX" -compact 380.It Pa /etc/bootparams 381Client root and swap pathnames. 382.It Pa /etc/dhcpd.conf 383DHCP daemon configuration file. 384.It Pa /etc/ethers 385Ethernet addresses of known clients. 386.It Pa /etc/exports 387Exported NFS mount points. 388.It Pa /etc/fstab 389Static information about the filesystems. 390.It Pa /etc/hostname.$if 391Interface-specific configuration file. 392.It Pa /etc/hosts 393Host name database. 394.It Pa /etc/myname 395Default hostname. 396.It Pa /etc/mygate 397Default gateway. 398.It Pa /etc/rbootd.conf 399Configuration file for HP Remote Boot Daemon. 400.It Pa /tftpboot 401Location of boot programs loaded by the Sun PROM. 402.It Pa /usr/mdec/rbootd 403Location of boot programs loaded by the HP Boot ROM. 404.El 405.Sh SEE ALSO 406.Xr bootparams 5 , 407.Xr dhcpd.conf 5 , 408.Xr ethers 5 , 409.Xr exports 5 , 410.Xr fstab 5 , 411.Xr hostname.if 5 , 412.Xr hosts 5 , 413.Xr mygate 5 , 414.Xr myname 5 , 415.Xr dhcpd 8 , 416.Xr mopd 8 , 417.Xr mountd 8 , 418.Xr nfsd 8 , 419.Xr portmap 8 , 420.Xr pxeboot 8 , 421.Xr rarpd 8 , 422.Xr rbootd 8 , 423.Xr rpc.bootparamd 8 , 424.Xr tcpdump 8 , 425.Xr tftpd 8 426