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