1.\" $NetBSD: diskless.8,v 1.34 2018/10/29 21:04:18 wiz Exp $ 2.\" 3.\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd October 23, 2018 29.Dt DISKLESS 8 30.Os 31.Sh NAME 32.Nm diskless 33.Nd booting a system over the network 34.Sh DESCRIPTION 35The ability to boot a system over the network is useful for 36two kinds of systems: 37.Bl -tag -width diskless 38.It Em diskless 39a system with no attached mass storage media to boot or run from 40.Pq e.g. a network computer . 41.It Em dataless 42a system with a hard drive that only contains system and application 43software, and user data is mounted over the network from a central server. 44.El 45.Pp 46It can also be done as a temporary measure while repairing or 47re-installing file systems on a local disk. 48This capability is necessarily platform dependent because of its 49dependence on system firmware support; not all platforms supported by 50.Nx 51are capable of being network booted. 52.Pp 53The protocols used to obtain a network address 54.Pq e.g. an Tn \&IP host address , 55include, but are not limited to: 56.Pp 57.Bl -tag -width BOOTP -offset indent -compact 58.It Tn RARP 59Reverse Address Resolution Protocol 60.Pq Tn ARP 61.It Tn DHCP 62Dynamic Host Configuration Protocol 63.It Tn BOOTP 64Bootstrap Protocol 65.El 66.Pp 67This information can also be derived from non-volatile 68.Tn RAM 69or by a transform of a network interface 70.Pq e.g. Tn Ethernet 71.Tn MAC 72address. 73.Pp 74The protocols used to load a 75.Nx 76kernel over a network include, but are not limited to: 77.Pp 78.Bl -tag -width TFTP -offset indent -compact 79.It Tn TFTP 80Trivial File Transfer Protocol 81.It Tn NFS 82.Tn Sun 83Network File System 84.It Tn RMP 85.Tn \&HP 86Remote Maintenance Protocol 87.It Tn MOP 88.Tn DEC 89Maintenance Operations Protocol 90.El 91.Pp 92Derivation of the filename of the secondary bootstrap program can 93be done by a transform of a network interface 94.Tn MAC 95address 96.Pq or other protocol address , 97or provided by a server as with 98.Tn BOOTP , 99and 100.Tn DHCP . 101How this is done is platform dependent; see 102.Xr boot 8 . 103.Pp 104The 105.Nx 106kernel doesn't care how it gets loaded and started. 107The protocols used to boot 108.Nx 109can be completely different than the ones that 110.Nx 111uses operationally, i.e. you can netboot the system using 112.Tn \&HP 113.Tn RMP 114and the 115.Nx 116kernel can use 117.Tn \&IP 118to communicate after bootstrap. 119.Pp 120There is no standard way to pass all the required information 121from a boot loader to an operating system kernel, so the 122.Nx 123kernel usually has to recapitulate the same 124.Pq or similar 125protocol exchanges over the network to obtain a network address, 126determine which servers to use, and so on. 127.Nx 128supports obtaining this information from 129.Tn RARP , 130.Tn BOOTP , 131.Tn DHCP , 132and 133.Tn Sun RPC 134.Qq bootparams . 135See 136.Xr options 4 137for a list of methods that can be compiled into a 138.Nx 139kernel. 140.Pp 141.Nx 142only supports the 143.Tn Sun 144Network File System 145.Pq Tn NFS 146for mounting its root file system over a network. 147.Nx 148can use any local mass storage device for which it has a driver, 149after bootstrap, even if that device is not supported by the system's 150firmware for booting. 151.Pp 152.Sy N.B. 153.Tn DHCP 154is essentially a series of extensions to 155.Tn BOOTP ; 156the 157.Nx 158.Xr dhcpd 8 159is capable of responding to both kinds of protocol requests. 160.Pp 161In the majority of configurations, network boot servers and clients 162are attached to the same 163.Tn LAN 164so that broadcast queries from the clients can be heard by the servers. 165Unless specially configured, routers block broadcasts from propagating from 166.Tn LAN 167to 168.Tn LAN ; 169some routers can be configured to 170.Qq forward 171broadcast 172.Tn BOOTP 173packets to another 174.Tn LAN 175attached to that router, which permits a server on that remote 176.Tn LAN 177to respond to the client's broadcast query. 178.Sh OPERATION 179When booting a system over the network, there are three 180phases of interaction between client and server: 181.Pp 182.Bl -enum -compact 183.It 184The system firmware 185.Pq or stage-1 bootstrap 186loads a boot program. 187.It 188The boot program loads a 189.Nx 190kernel. 191.It 192The 193.Nx 194kernel performs an 195.Tn NFS 196mount of the root file system. 197.El 198.Pp 199Each of these phases are described in further detail below. 200.Ss 1. loading a boot program 201In phase 1, the system firmware loads a boot program. 202Firmware designs vary widely, 203so this phase is inherently machine-specific. 204Some examples: 205.Pp 206.Tn DEC 207Alpha systems use 208.Tn BOOTP 209to determine the client's 210.Tn \&IP 211address and then use 212.Tn TFTP 213load a secondary bootstrap program from the server and filename 214specified in the 215.Tn BOOTP 216reply. 217.Tn DEC 218Alpha systems can also use 219.Tn MOP 220to load a program to run the system. 221.Pp 222.Tn Sun 223systems use 224.Tn RARP 225to determine the client's 226.Tn \&IP 227address, transform that address to a hexadecimal string to form 228the filename of the secondary boot program, and then use 229.Tn TFTP 230to download the boot program from the server that sent the 231.Tn RARP 232reply. 233.Pp 234.Tn \&HP 235300-series systems use the 236.Tn \&HP 237.Tn RMP 238to download a boot program. 239.Pp 240Typical personal computers may load a network boot program either 241from diskette or from a 242.Tn PROM 243on a Network Interface Card 244.Pq Tn NIC . 245Some 246.Tn BIOS Ns No \&es 247support booting from a network interface. 248.Ss 2. loading a kernel 249In phase 2, the secondary boot program loads a kernel. 250Operation in this phase depends on the design of the boot program 251.Po 252the design described here is the one used by 253.Tn Sun 254and 255.Nx Ns Tn /hp300 256.Pc . 257The boot program: 258.Pp 259.Bl -enum -compact 260.It 261gets the client 262.Tn \&IP 263address using 264.Tn RARP . 265.It 266gets the client name and server 267.Tn \&IP 268address by broadcasting an 269.Tn RPC / BOOTPARAMS / WHOAMI 270request with the client 271.Tn \&IP 272address. 273.It 274gets the server path for this client's 275root using an 276.Tn RPC / BOOTPARAMS / GETFILE 277request with the client name. 278.It 279gets the root file handle by calling 280.Xr mountd 8 281with the server path for the client root file system. 282.It 283gets the kernel file handle by calling 284.Tn NFS 285.Fn lookup 286on the root file handle. 287.It 288loads the kernel using 289.Tn NFS 290read calls on the kernel file handle. 291.It 292transfers control to the kernel entry point. 293.El 294.Pp 295A 296.Tn BOOTP 297and/or 298.Tn DHCP 299secondary bootstrap program will do the following: 300.Pp 301.Bl -enum -compact 302.It 303query for the client's bootstrap parameters. 304The response must include the client's 305.Tn \&IP 306address, and a 307.Tn TFTP 308server to load the 309.Nx 310kernel from. 311.It 312loads the 313.Nx 314kernel from the 315.Tn TFTP 316server. 317.It 318transfers control to the kernel entry point. 319.El 320.Ss 3. NFS mounting the root file system 321In phase 3, the kernel performs an 322.Tn NFS 323mount of the root file system. 324The kernel repeats much of the work done by the boot program 325because there is no standard way for the boot program to pass 326the information it gathered on to the kernel. 327.Pp 328In general, the GENERIC kernel 329.Xr config 1 330file for any particular architecture will specify compile-time 331options to use the same protocol used by the secondary boot program 332for that architecture. 333A 334.Nx 335kernel can be compiled to use any of 336.Tn BOOTP , 337.Tn DHCP , 338or 339.Tn Sun RPC BOOTPARAMS ; 340see 341.Xr options 4 . 342.Pp 343The procedure typically used by the kernel is as follows: 344.Pp 345.Bl -enum -compact 346.It 347The kernel finds a boot server using the same procedures 348as described above to determine the client's 349.Tn \&IP 350address, an 351.Tn NFS 352server, etc. 353.It 354The kernel gets the 355.Tn NFS 356file handle for root using the same procedure as described above. 357.It 358The kernel calls the 359.Tn NFS 360.Fn getattr 361function to get the last-modified time of the root 362directory, and uses it to check the system clock. 363.El 364.Sh SERVER CONFIGURATION 365Before a client can bootstrap over the network, 366its server must be configured. 367Each daemon that implements these protocols must be set up so 368that it can answer queries from the clients. 369Some of these daemons are invoked as packets come in, by 370.Xr inetd 8 , 371and some must run independently, started from 372.Pa /etc/rc ; 373see 374.Xr rc.conf 5 . 375.Bl -column "Protocol" "rpc.bootparamd" "inetd.conf(5)" -offset indent 376.It Sy Protocol Ta Sy Program Ta Sy Startup 377.It RARP Ta rarpd Ta Xr rc.conf 5 378.It DHCP Ta dhcpd Ta Xr rc.conf 5 379.It BOOTP Ta bootpd Ta Xr inetd.conf 5 380.It TFTP Ta tftpd Ta Xr inetd.conf 5 381.It Sun RPC Ta rpcbind Ta Xr rc.conf 5 382.It Sun RPC Ta rpc.bootparamd Ta Xr rc.conf 5 383.It Sun NFS Ta mountd Ta Xr rc.conf 5 384.It Sun NFS Ta nfsiod Ta Xr rc.conf 5 385.It \&HP RMP Ta rbootd Ta Xr rc.conf 5 386.El 387.Pp 388.Sy N.B. 389.Tn DHCP 390is essentially a series of extensions to 391.Tn BOOTP ; 392the 393.Nx 394.Xr dhcpd 8 395is capable of responding to both kinds of protocol requests. 396Since they both bind to the same 397.Tn UDP 398port, only one may be run on a given server. 399.Pp 400In the following examples, the client's hostname is 401.Sy myclient ; 402the server is 403.Sy myserver , 404and the addresses are all fictional. 405In these examples 406the hostnames may be Fully Qualified Domain Names 407.Pq FQDN, e.g. Qq myclient.mydomain.com 408provided that they are used consistently. 409.Ss RARP 410For clients that use 411.Tn RARP 412to obtain their 413.Tn \&IP 414address, 415an entry must be added for each client to 416.Pa /etc/ethers 417with the client's 418.Tn Ethernet 419.Tn MAC 420address and Internet hostname: 421.Pp 422.Bd -literal -offset indent -compact 4238:0:20:7:c5:c7 myclient 424.Ed 425.Pp 426This will be used by 427.Xr rarpd 8 428to reply to queries from the clients. 429There must be one entry per client system. 430.Pp 431A client system's 432.Tn Ethernet 433.Tn MAC 434address is often printed on the system case, or on a chip on its 435motherboard, or on the 436.Tn NIC . 437If not, 438.Qq sniffing 439the network with 440.Xr tcpdump 8 441when the client is powered-on should reveal its 442.Tn Ethernet 443.Tn MAC 444address. 445.Pp 446Each client system that uses 447.Tn RARP 448must have its own, unique 449.Tn \&IP 450address assigned to it. 451Assign an 452.Tn \&IP 453address for myclient in your 454.Pa /etc/hosts 455file, or in the master file for your 456.Tn DNS 457zone. 458For 459.Pa /etc/hosts 460the entry should look like: 461.Pp 462.Bd -literal -offset indent -compact 463192.197.96.12 myclient 464.Ed 465.Ss DHCP/BOOTP 466The 467.Nx 468.Tn DHCP 469server 470.Xr dhcpd 8 471was developed by the Internet Software Consortium 472.Pq Lk http://www.isc.org/ "ISC" . 473.Pp 474.Tn DHCP 475can provide a wide range of information to a requesting client; 476the key data for bootstrapping a diskless client are: 477.Pp 478.Bl -enum -compact 479.It 480an 481.Tn \&IP 482address 483.It 484a subnet mask 485.It 486a 487.Tn TFTP 488server address for loading the secondary bootstrap and the 489.Nx 490kernel 491.It 492a filename of the secondary bootstrap 493.It 494an 495.Tn NFS 496server address for the client's file system 497.It 498the client's root file system path, to be 499.Tn NFS 500mounted. 501.El 502.Pp 503An example for 504.Pa /etc/dhcpd.conf 505.Bd -literal -offset indent 506host myclient { 507 hardware ethernet 8:0:20:7:c5:c7; 508 fixed-address myclient; # client's assigned IP address 509 filename "myclient.netboot"; # secondary bootstrap 510 next-server myserver; # TFTP server for secondary bootstrap 511 option swap-server myserver; # NFS server for root filesystem 512 option root-path "/export/myclient/root"; 513} 514.Ed 515.Pp 516That 517.Sy host 518declaration goes inside a 519.Sy subnet 520declaration, which gives parameters for all hosts on the subnet 521that will be using 522.Tn DHCP , 523such as the 524.Qq routers 525.Pq the default route , 526.Qq subnet-mask , 527.Qq broadcast-address , 528.Qq domain-name-servers , 529etc. 530See 531.Xr dhcpd.conf 5 532for details. 533In that example, 534.Sy myclient 535has an assigned IP address. 536.Pp 537The 538.Tn DHCP 539parameters required for network bootstrapping a system will vary 540from platform to platform, as dictated by each system's firmware. 541In particular, because the 542.Tn DHCP 543is extensible, some hardware vendors have specified 544.Tn DHCP 545options to return information to requesting clients that are specific 546to that platform. 547Please see your platform's 548.Xr boot 8 549for details. 550.Ss TFTP 551If booting a 552.Tn Sun 553system, or other system that expects to use 554.Tn TFTP , 555ensure that 556.Xr inetd 8 557is configured to run 558.Xr tftpd 8 . 559The 560.Xr tftpd 8 561server should be set up to serve the directory 562.Pa /tftpboot . 563.Pp 564If booting a 565.Tn SPARC 566system, install a copy of the appropriate diskless secondary boot 567loader 568.Po 569such as 570.Pa /usr/mdec/boot 571or 572.Pa ofwboot.net 573.Pc 574in the 575.Pa /tftpboot 576directory. 577Make a link such that the boot program is 578accessible by a filename composed of the client's 579.Tn \&IP 580address in hexadecimal, a dot, and the architecture name 581.Pq all upper case . 582For example: 583.Pp 584.Bd -literal -offset indent -compact 585# cd /tftpboot 586# ln -s boot C0C5600C.SUN4 587.Ed 588.Pp 589For a 590.Tn Sun-3 591or 592.Tn UltraSPARC 593system, the filename would be just C0C5600C 594.Po 595these systems' firmware does not append the architecture name 596.Pc . 597The name used is architecture dependent, it simply has to match 598what the booting client's system firmware wishes to it to be. 599.Pp 600If the client's system firmware fails to fetch the expected file, 601.Xr tcpdump 8 602can be used to discover which filename the client is being requested. 603Also, examination of 604.Xr tftpd 8 605log entries 606.Po 607typically in 608.Pa /var/log/messages 609.Pc 610should show whether the server is hearing the client system, and 611what filename the client is asking for. 612.Ss HP RMP 613If booting an 614.Tn HP 615300-series system, ensure that 616.Pa /etc/rbootd.conf 617is configured properly to transfer the boot program to the client. 618An entry might look like this: 619.Pp 620.Bd -literal -offset indent -compact 62108:00:09:01:23:E6 SYS_UBOOT # myclient 622.Ed 623.Pp 624The secondary bootstrap program for an 625.Tn \&HP 626300-series system 627.Pa SYS_UBOOT 628.Po 629which may be called 630.Pa uboot.lif 631before installation 632.Pc 633must be installed in the directory 634.Pa /usr/mdec/rbootd . 635.Pp 636See the 637.Xr rbootd 8 638manual page for more information. 639.Ss Sun RPC BOOTPARAMS 640Add 641.Sy myclient 642to the bootparams database in 643.Pa /etc/bootparams : 644.Pp 645.Bd -literal -offset indent -compact 646myclient root=myserver:/export/myclient/root \\ 647 swap=myserver:/export/myclient/root/swap \\ 648 dump=myserver:/export/myclient/root/swap 649.Ed 650.Pp 651and ensure that 652.Xr rpc.bootparamd 8 653and 654.Xr rpcbind 8 655are running. 656Both 657.Sy myclient 658and 659.Sy myserver 660must have 661.Tn \&IP 662addresses in the 663.Tn DNS 664or 665.Pa /etc/hosts . 666.Ss Diskless Client File Systems 667Build the swap file for 668.Sy myclient 669on the 670.Tn NFS 671server: 672.Pp 673.Bd -literal -offset indent -compact 674# cd /export/myclient/root 675# dd if=/dev/zero of=swap bs=16k count=1024 676.Ed 677.Pp 678This creates a 16 megabyte swap file. 679.Pp 680Populate 681.Sy myclient Ns No 's 682root file system on the 683.Tn NFS 684server. 685How this is done depends on the client architecture and the version 686of the 687.Nx 688distribution. 689It can be as simple as copying and modifying the server's root 690file system, or unpack a complete 691.Nx 692binary distribution for the appropriate platform. 693.Pp 694If the 695.Tn NFS 696server is going to support multiple different architectures 697.Po 698e.g. 699.Tn Alpha , 700.Tn PowerPC , 701.Tn SPARC , 702.Tn MIPS 703.Pc , 704then it is important to think carefully about how to lay out the 705.Tn NFS 706server's exported file systems, to share what can be shared 707.Pq e.g. text files, configuration files, user home directories , 708and separate that which is distinct to each architecture 709.Pq e.g. binary executables, libraries . 710.Ss NFS 711Export the client-populated file systems on the 712.Tn NFS 713server in 714.Pa /etc/exports : 715.Pp 716.Bd -literal -offset indent -compact 717/usr -ro myclient 718# for SunOS: 719# /export/myclient -rw=myclient,root=myclient 720# for NetBSD: 721/export/myclient -maproot=root -alldirs myclient 722.Ed 723.Pp 724If the server and client are of the same architecture, then the client 725can share the server's 726.Pa /usr 727file system 728.Pq as is done above . 729If not, you must build a properly fleshed out 730.Pa /usr 731partition for the client in some other part of the server's 732file system, to serve to the client. 733.Pp 734If your server is a 735.Tn SPARC , 736and your client a 737.Tn Sun-3 , 738you might create and fill 739.Pa /export/usr.sun3 740and then use the following 741.Pa /etc/exports 742lines: 743.Pp 744.Bd -literal -offset indent -compact 745/export/usr.sun3 -ro myclient 746/export/myclient -rw=myclient,root=myclient 747.Ed 748.Pp 749Of course, in either case you will have to have an 750.Tn NFS 751server running on the server side. 752.Sh CLIENT CONFIGURATION 753Copy and customize at least the following files in 754.Pa /export/myclient/root : 755.Pp 756.Bd -literal -offset indent -compact 757# cd /export/myclient/root/etc 758# vi fstab 759# cp /etc/hosts hosts 760# echo 'hostname="myclient"' >> rc.conf 761# echo "inet 192.197.96.12" > ifconfig.le0 762.Ed 763.Pp 764Note that "le0" above should be replaced with the name of 765the network interface that the client will use for booting; 766the network interface name is device dependent in 767.Nx . 768.Pp 769Correct the critical mount points and the swap file in the client's 770.Pa /etc/fstab 771.Po 772which will be 773.Pa /export/myclient/root/etc/fstab 774.Pc 775i.e. 776.Pp 777.Bd -literal -offset indent -compact 778myserver:/export/myclient/root / nfs rw 0 0 779myserver:/usr /usr nfs rw 0 0 780/swap none swap sw 0 0 781.Ed 782.Pp 783Note, you 784.Em must 785specify the swap file in 786.Pa /etc/fstab 787or it will not be used! 788See 789.Xr swapctl 8 . 790.Pp 791It may be useful to set 792.Dq flushroutes=NO 793in 794.Pa /etc/rc.conf 795to avoid the default route supplied by the boot setup 796disappearing mid-boot. 797.Sh FILES 798.Bl -tag -width /usr/mdec/rbootd -compact 799.It Pa /etc/hosts 800table of associated 801.Tn \&IP 802addresses and 803.Tn \&IP 804host names; see 805.Xr hosts 5 806.It Pa /etc/ethers 807table of associated 808.Tn Ethernet 809.Tn MAC 810addresses and 811.Tn \&IP 812host names used by 813.Xr rarpd 8 ; 814see 815.Xr ethers 5 816.It Pa /etc/bootparams 817client root pathname and swap pathname; see 818.Xr bootparams 5 819.It Pa /etc/exports 820exported 821.Tn NFS 822mount points; see 823.Xr exports 5 824.It Pa /etc/rbootd.conf 825configuration file for 826.Tn \&HP RMP ; 827see 828.Xr rbootd 8 829.It Pa /usr/mdec/rbootd 830location of boot programs offered by 831.Xr rbootd 8 832.It Pa /tftpboot 833location of boot programs offered by 834.Xr tftpd 8 835.El 836.Sh SEE ALSO 837.Xr bootparams 5 , 838.Xr dhcpd.conf 5 , 839.Xr ethers 5 , 840.Xr exports 5 , 841.Xr fstab 5 , 842.Xr hosts 5 , 843.Xr networks 5 , 844.Xr boot 8 , 845.Xr dhcpd 8 , 846.Xr mopd 8 , 847.Xr mountd 8 , 848.Xr nfsd 8 , 849.Xr rarpd 8 , 850.Xr rbootd 8 , 851.Xr reboot 8 , 852.Xr rpc.bootparamd 8 , 853.Xr tftpd 8 854.Rs 855.%R RFC 856.%N 903 857.%D June 1984 858.%T "Reverse Address Resolution Protocol" 859.Re 860.Rs 861.%R RFC 862.%N 906 863.%D June 1984 864.%T "Bootstrap Loading using TFTP" 865.Re 866.Rs 867.%R RFC 868.%N 951 869.%D September 1985 870.%T "Bootstrap Protocol" 871.Re 872.Rs 873.%R RFC 874.%N 1350 875.%D July 1992 876.%T "The TFTP Protocol (Revision 2)" 877.Re 878.Rs 879.%R RFC 880.%N 2131 881.%D March 1997 882.%T "Dynamic Host Configuration Protocol" 883.Re 884.Rs 885.%R RFC 886.%N 2132 887.%D March 1997 888.%T "DHCP Options and BOOTP Vendor Extensions" 889.Re 890.Pp 891.Lk http://www.rfc-editor.org/ "RFC Editor" 892