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