1.\" $NetBSD: diskless.8,v 1.29 2006/10/07 22:23:45 elad 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 tfptd 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 ISC ; 475.Pa http://www.isc.org/ 476.Pp 477.Tn DHCP 478can provide a wide range of information to a requesting client; 479the key data for bootstrapping a diskless client are: 480.Pp 481.Bl -enum -compact 482.It 483an 484.Tn \&IP 485address 486.It 487a subnet mask 488.It 489a 490.Tn TFTP 491server address for loading the secondary bootstrap and the 492.Nx 493kernel 494.It 495a filename of the secondary bootstrap 496.It 497an 498.Tn NFS 499server address for the client's file system 500.It 501the client's root file system path, to be 502.Tn NFS 503mounted. 504.El 505.Pp 506An example for 507.Pa /etc/dhcpd.conf 508.Pp 509.Bd -literal -offset indent 510host myclient { 511 hardware ethernet 8:0:20:7:c5:c7; 512 fixed-address myclient; # client's assigned IP address 513 filename "myclient.netboot"; # secondary bootstrap 514 next-server myserver; # TFTP server for secondary bootstrap 515 option swap-server myserver; # NFS server for root filesystem 516 option root-path "/export/myclient/root"; 517} 518.Ed 519.Pp 520That 521.Sy host 522declaration goes inside a 523.Sy subnet 524declaration, which gives parameters for all hosts on the subnet 525that will be using 526.Tn DHCP , 527such as the 528.Qq routers 529.Pq the default route , 530.Qq subnet-mask , 531.Qq broadcast-address , 532.Qq domain-name-servers , 533etc. 534See 535.Xr dhcpd.conf 5 536for details. 537In that example, 538.Sy myclient 539has an assigned IP address. 540.Pp 541The 542.Tn DHCP 543parameters required for network bootstrapping a system will vary 544from platform to platform, as dictated by each system's firmware. 545In particular, because the 546.Tn DHCP 547is extensible, some hardware vendors have specified 548.Tn DHCP 549options to return information to requesting clients that are specific 550to that platform. 551Please see your platform's 552.Xr boot 8 553for details. 554.Ss TFTP 555If booting a 556.Tn Sun 557system, or other system that expects to use 558.Tn TFTP , 559ensure that 560.Xr inetd 8 561is configured to run 562.Xr tftpd 8 . 563The 564.Xr tftpd 8 565server should be set up to serve the directory 566.Pa /tftpboot . 567.Pp 568If booting a 569.Tn SPARC 570system, install a copy of the appropriate diskless secondary boot 571loader 572.Po 573such as 574.Pa /usr/mdec/boot 575or 576.Pa ofwboot.net 577.Pc 578in the 579.Pa /tftpboot 580directory. 581Make a link such that the boot program is 582accessible by a filename composed of the client's 583.Tn \&IP 584address in hexadecimal, a dot, and the architecture name 585.Pq all upper case . 586For example: 587.Pp 588.Bd -literal -offset indent -compact 589# cd /tftpboot 590# ln -s boot C0C5600C.SUN4 591.Ed 592.Pp 593For a 594.Tn Sun-3 595or 596.Tn UltraSPARC 597system, the filename would be just C0C5600C 598.Po 599these systems' firmware does not append the architecture name 600.Pc . 601The name used is architecture dependent, it simply has to match 602what the booting client's system firmware wishes to it to be. 603.Pp 604If the client's system firmware fails to fetch the expected file, 605.Xr tcpdump 8 606can be used to discover which filename the client is being requested. 607Also, examination of 608.Xr tftpd 8 609log entries 610.Po 611typically in 612.Pa /var/log/messages 613.Pc 614should show whether the server is hearing the client system, and 615what filename the client is asking for. 616.Ss HP RMP 617If booting an 618.Tn HP 619300-series system, ensure that 620.Pa /etc/rbootd.conf 621is configured properly to transfer the boot program to the client. 622An entry might look like this: 623.Pp 624.Bd -literal -offset indent -compact 62508:00:09:01:23:E6 SYS_UBOOT # myclient 626.Ed 627.Pp 628The secondary bootstrap program for an 629.Tn \&HP 630300-series system 631.Pa SYS_UBOOT 632.Po 633which may be called 634.Pa uboot.lif 635before installation 636.Pc 637must be installed in the directory 638.Pa /usr/mdec/rbootd . 639.Pp 640See the 641.Xr rbootd 8 642manual page for more information. 643.Ss Sun RPC BOOTPARAMS 644Add 645.Sy myclient 646to the bootparams database in 647.Pa /etc/bootparams : 648.Pp 649.Bd -literal -offset indent -compact 650myclient root=myserver:/export/myclient/root \\ 651 swap=myserver:/export/myclient/root/swap \\ 652 dump=myserver:/export/myclient/root/swap 653.Ed 654.Pp 655and ensure that 656.Xr rpc.bootparamd 8 657and 658.Xr rpcbind 8 659are running. 660Both 661.Sy myclient 662and 663.Sy myserver 664must have 665.Tn \&IP 666addresses in the 667.Tn DNS 668or 669.Pa /etc/hosts . 670.Ss Diskless Client File Systems 671Build the swap file for 672.Sy myclient 673on the 674.Tn NFS 675server: 676.Pp 677.Bd -literal -offset indent -compact 678# cd /export/myclient/root 679# dd if=/dev/zero of=swap bs=16k count=1024 680.Ed 681.Pp 682This creates a 16 megabyte swap file. 683.Pp 684Populate 685.Sy myclient Ns No 's 686root file system on the 687.Tn NFS 688server. 689How this is done depends on the client architecture and the version 690of the 691.Nx 692distribution. 693It can be as simple as copying and modifying the server's root 694file system, or unpack a complete 695.Nx 696binary distribution for the appropriate platform. 697.Pp 698If the 699.Tn NFS 700server is going to support multiple different architectures 701.Po 702e.g. 703.Tn Alpha , 704.Tn PowerPC , 705.Tn SPARC , 706.Tn MIPS 707.Pc , 708then it is important to think carefully about how to lay out the 709.Tn NFS 710server's exported file systems, to share what can be shared 711.Pq e.g. text files, configuration files, user home directories , 712and separate that which is distinct to each architecture 713.Pq e.g. binary executables, libraries . 714.Ss NFS 715Export the client-populated file systems on the 716.Tn NFS 717server in 718.Pa /etc/exports : 719.Pp 720.Bd -literal -offset indent -compact 721/usr -ro myclient 722# for SunOS: 723# /export/myclient -rw=myclient,root=myclient 724# for NetBSD: 725/export/myclient -maproot=root -alldirs myclient 726.Ed 727.Pp 728If the server and client are of the same architecture, then the client 729can share the server's 730.Pa /usr 731file system 732.Pq as is done above . 733If not, you must build a properly fleshed out 734.Pa /usr 735partition for the client in some other part of the server's 736file system, to serve to the client. 737.Pp 738If your server is a 739.Tn SPARC , 740and your client a 741.Tn Sun-3 , 742you might create and fill 743.Pa /export/usr.sun3 744and then use the following 745.Pa /etc/exports 746lines: 747.Pp 748.Bd -literal -offset indent -compact 749/export/usr.sun3 -ro myclient 750/export/myclient -rw=myclient,root=myclient 751.Ed 752.Pp 753Of course, in either case you will have to have an 754.Tn NFS 755server running on the server side. 756.Sh CLIENT CONFIGURATION 757Copy and customize at least the following files in 758.Pa /export/myclient/root : 759.Pp 760.Bd -literal -offset indent -compact 761# cd /export/myclient/root/etc 762# vi fstab 763# cp /etc/hosts hosts 764# echo 'hostname="myclient"' \*[Gt]\*[Gt] rc.conf 765# echo "inet 192.197.96.12" \*[Gt] ifconfig.le0 766.Ed 767.Pp 768Note that "le0" above should be replaced with the name of 769the network interface that the client will use for booting; 770the network interface name is device dependent in 771.Nx . 772.Pp 773Correct the critical mount points and the swap file in the client's 774.Pa /etc/fstab 775.Po 776which will be 777.Pa /export/myclient/root/etc/fstab 778.Pc 779i.e. 780.Pp 781.Bd -literal -offset indent -compact 782myserver:/export/myclient/root / nfs rw 0 0 783myserver:/usr /usr nfs rw 0 0 784/swap none swap sw 0 0 785.Ed 786.Pp 787Note, you 788.Em must 789specify the swap file in 790.Pa /etc/fstab 791or it will not be used! 792See 793.Xr swapctl 8 . 794.Sh FILES 795.Bl -tag -width /usr/mdec/rbootd -compact 796.It Pa /etc/hosts 797table of associated 798.Tn \&IP 799addresses and 800.Tn \&IP 801host names; see 802.Xr hosts 5 803.It Pa /etc/ethers 804table of associated 805.Tn Ethernet 806.Tn MAC 807addresses and 808.Tn \&IP 809host names used by 810.Xr rarpd 8 ; 811see 812.Xr ethers 5 813.It Pa /etc/bootparams 814client root pathname and swap pathname; see 815.Xr bootparams 5 816.It Pa /etc/exports 817exported 818.Tn NFS 819mount points; see 820.Xr exports 5 821.It Pa /etc/rbootd.conf 822configuration file for 823.Tn \&HP RMP ; 824see 825.Xr rbootd 8 826.It Pa /usr/mdec/rbootd 827location of boot programs offered by 828.Xr rbootd 8 829.It Pa /tftpboot 830location of boot programs offered by 831.Xr tftpd 8 832.El 833.Sh SEE ALSO 834.Xr bootparams 5 , 835.Xr dhcpd.conf 5 , 836.Xr ethers 5 , 837.Xr exports 5 , 838.Xr fstab 5 , 839.Xr hosts 5 , 840.Xr networks 5 , 841.Xr boot 8 , 842.Xr dhcpd 8 , 843.Xr mopd 8 , 844.Xr mountd 8 , 845.Xr nfsd 8 , 846.Xr rarpd 8 , 847.Xr rbootd 8 , 848.Xr reboot 8 , 849.Xr rpc.bootparamd 8 , 850.Xr tftpd 8 851.Rs 852.%R RFC 853.%N 903 854.%D June 1984 855.%T "Reverse Address Resolution Protocol" 856.Re 857.Rs 858.%R RFC 859.%N 906 860.%D June 1984 861.%T "Bootstrap Loading using TFTP" 862.Re 863.Rs 864.%R RFC 865.%N 951 866.%D September 1985 867.%T "Bootstrap Protocol" 868.Re 869.Rs 870.%R RFC 871.%N 1350 872.%D July 1992 873.%T "The TFTP Protocol (Revision 2)" 874.Re 875.Rs 876.%R RFC 877.%N 2131 878.%D March 1997 879.%T "Dynamic Host Configuration Protocol" 880.Re 881.Rs 882.%R RFC 883.%N 2132 884.%D March 1997 885.%T "DHCP Options and BOOTP Vendor Extensions" 886.Re 887.Pp 888.Pa http://www.rfc-editor.org/ 889