1 .\" $NetBSD: diskless.8,v 1.28 2005/06/20 13:25:25 peter Exp $
3 .\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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.
33 .Nd booting a system over the network
35 The ability to boot a system over the network is useful for
38 .Bl -tag -width diskless
40 a system with no attached mass storage media to boot or run from
41 .Pq e.g. a network computer .
43 a system with a hard drive that only contains system and application
44 software, and user data is mounted over the network from a central server.
47 It can also be done as a temporary measure while repairing or
48 re-installing file systems on a local disk.
49 This capability is necessarily platform dependent because of its
50 dependence on system firmware support; not all platforms supported by
52 are capable of being network booted.
54 The protocols used to obtain a network address
55 .Pq e.g. an Tn \&IP host address ,
56 include, but are not limited to:
58 .Bl -tag -width BOOTP -offset indent -compact
60 Reverse Address Resolution Protocol
63 Dynamic Host Configuration Protocol
68 This information can also be derived from non-volatile
70 or by a transform of a network interface
75 The protocols used to load a
77 kernel over a network include, but are not limited to:
79 .Bl -tag -width TFTP -offset indent -compact
81 Trivial File Transfer Protocol
87 Remote Maintenance Protocol
90 Maintenance Operations Protocol
93 Derivation of the filename of the secondary bootstrap program can
94 be done by a transform of a network interface
97 .Pq or other protocol address ,
98 or provided by a server as with
102 How this is done is platform dependent; see
107 kernel doesn't care how it gets loaded and started.
108 The protocols used to boot
110 can be completely different than the ones that
112 uses operationally, i.e. you can netboot the system using
119 to communicate after bootstrap.
121 There is no standard way to pass all the required information
122 from a boot loader to an operating system kernel, so the
124 kernel usually has to recapitulate the same
126 protocol exchanges over the network to obtain a network address,
127 determine which servers to use, and so on.
129 supports obtaining this information from
138 for a list of methods that can be compiled into a
147 for mounting its root file system over a network.
149 can use any local mass storage device for which it has a driver,
150 after bootstrap, even if that device is not supported by the system's
151 firmware for booting.
155 is essentially a series of extensions to
160 is capable of responding to both kinds of protocol requests.
162 In the majority of configurations, network boot servers and clients
163 are attached to the same
165 so that broadcast queries from the clients can be heard by the servers.
166 Unless specially configured, routers block broadcasts from propagating from
170 some routers can be configured to
176 attached to that router, which permits a server on that remote
178 to respond to the client's broadcast query.
180 When booting a system over the network, there are three
181 phases of interaction between client and server:
186 .Pq or stage-1 bootstrap
187 loads a boot program.
189 The boot program loads a
197 mount of the root file system.
200 Each of these phases are described in further detail below.
201 .Ss 1. loading a boot program
202 In phase 1, the system firmware loads a boot program.
203 Firmware designs vary widely,
204 so this phase is inherently machine-specific.
210 to determine the client's
214 load a secondary bootstrap program from the server and filename
219 Alpha systems can also use
221 to load a program to run the system.
226 to determine the client's
228 address, transform that address to a hexadecimal string to form
229 the filename of the secondary boot program, and then use
231 to download the boot program from the server that sent the
236 300-series systems use the
239 to download a boot program.
241 Typical personal computers may load a network boot program either
242 from diskette or from a
244 on a Network Interface Card
248 support booting from a network interface.
249 .Ss 2. loading a kernel
250 In phase 2, the secondary boot program loads a kernel.
251 Operation in this phase depends on the design of the boot program
253 the design described here is the one used by
267 gets the client name and server
269 address by broadcasting an
270 .Tn RPC / BOOTPARAMS / WHOAMI
271 request with the client
275 gets the server path for this client's
277 .Tn RPC / BOOTPARAMS / GETFILE
278 request with the client name.
280 gets the root file handle by calling
282 with the server path for the client root file system.
284 gets the kernel file handle by calling
287 on the root file handle.
289 loads the kernel using
291 read calls on the kernel file handle.
293 transfers control to the kernel entry point.
300 secondary bootstrap program will do the following:
304 query for the client's bootstrap parameters.
305 The response must include the client's
319 transfers control to the kernel entry point.
321 .Ss 3. NFS mounting the root file system
322 In phase 3, the kernel performs an
324 mount of the root file system.
325 The kernel repeats much of the work done by the boot program
326 because there is no standard way for the boot program to pass
327 the information it gathered on to the kernel.
329 In general, the GENERIC kernel
331 file for any particular architecture will specify compile-time
332 options to use the same protocol used by the secondary boot program
333 for that architecture.
336 kernel can be compiled to use any of
340 .Tn Sun RPC BOOTPARAMS ;
344 The procedure typically used by the kernel is as follows:
348 The kernel finds a boot server using the same procedures
349 as described above to determine the client's
357 file handle for root using the same procedure as described above.
362 function to get the last-modified time of the root
363 directory, and uses it to check the system clock.
365 .Sh SERVER CONFIGURATION
366 Before a client can bootstrap over the network,
367 its server must be configured.
368 Each daemon that implements these protocols must be set up so
369 that it can answer queries from the clients.
370 Some of these daemons are invoked as packets come in, by
372 and some must run independently, started from
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
392 is essentially a series of extensions to
397 is capable of responding to both kinds of protocol requests.
398 Since they both bind to the same
400 port, only one may be run on a given server.
402 In the following examples, the client's hostname is
406 and the addresses are all fictional.
408 the hostnames may be Fully Qualified Domain Names
409 .Pq FQDN, e.g. Qq myclient.mydomain.com
410 provided that they are used consistently.
417 an entry must be added for each client to
422 address and Internet hostname:
424 .Bd -literal -offset indent -compact
425 8:0:20:7:c5:c7 myclient
430 to reply to queries from the clients.
431 There must be one entry per client system.
436 address is often printed on the system case, or on a chip on its
437 motherboard, or on the
443 when the client is powered-on should reveal its
448 Each client system that uses
450 must have its own, unique
452 address assigned to it.
455 address for myclient in your
457 file, or in the master file for your
462 the entry should look like:
464 .Bd -literal -offset indent -compact
465 192.197.96.12 myclient
473 was developed by the Internet Software Consortium
475 .Pa http://www.isc.org/
478 can provide a wide range of information to a requesting client;
479 the key data for bootstrapping a diskless client are:
491 server address for loading the secondary bootstrap and the
495 a filename of the secondary bootstrap
499 server address for the client's file system
501 the client's root file system path, to be
509 .Bd -literal -offset indent
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";
522 declaration goes inside a
524 declaration, which gives parameters for all hosts on the subnet
529 .Pq the default route ,
531 .Qq broadcast-address ,
532 .Qq domain-name-servers ,
539 has an assigned IP address.
543 parameters required for network bootstrapping a system will vary
544 from platform to platform, as dictated by each system's firmware.
545 In particular, because the
547 is extensible, some hardware vendors have specified
549 options to return information to requesting clients that are specific
551 Please see your platform's
557 system, or other system that expects to use
565 server should be set up to serve the directory
570 system, install a copy of the appropriate diskless secondary boot
581 Make a link such that the boot program is
582 accessible by a filename composed of the client's
584 address in hexadecimal, a dot, and the architecture name
588 .Bd -literal -offset indent -compact
590 # ln -s boot C0C5600C.SUN4
597 system, the filename would be just C0C5600C
599 these systems' firmware does not append the architecture name
601 The name used is architecture dependent, it simply has to match
602 what the booting client's system firmware wishes to it to be.
604 If the client's system firmware fails to fetch the expected file,
606 can be used to discover which filename the client is being requested.
612 .Pa /var/log/messages
614 should show whether the server is hearing the client system, and
615 what filename the client is asking for.
619 300-series system, ensure that
621 is configured properly to transfer the boot program to the client.
622 An entry might look like this:
624 .Bd -literal -offset indent -compact
625 08:00:09:01:23:E6 SYS_UBOOT # myclient
628 The secondary bootstrap program for an
637 must be installed in the directory
638 .Pa /usr/mdec/rbootd .
642 manual page for more information.
643 .Ss Sun RPC BOOTPARAMS
646 to the bootparams database in
647 .Pa /etc/bootparams :
649 .Bd -literal -offset indent -compact
650 myclient root=myserver:/export/myclient/root \\
651 swap=myserver:/export/myclient/root/swap \\
652 dump=myserver:/export/myclient/root/swap
670 .Ss Diskless Client File Systems
671 Build the swap file for
677 .Bd -literal -offset indent -compact
678 # cd /export/myclient/root
679 # dd if=/dev/zero of=swap bs=16k count=1024
682 This creates a 16 megabyte swap file.
685 .Sy myclient Ns No 's
686 root file system on the
689 How this is done depends on the client architecture and the version
693 It can be as simple as copying and modifying the server's root
694 file system, or unpack a complete
696 binary distribution for the appropriate platform.
700 server is going to support multiple different architectures
708 then it is important to think carefully about how to lay out the
710 server's exported file systems, to share what can be shared
711 .Pq e.g. text files, configuration files, user home directories ,
712 and separate that which is distinct to each architecture
713 .Pq e.g. binary executables, libraries .
715 Export the client-populated file systems on the
720 .Bd -literal -offset indent -compact
723 # /export/myclient -rw=myclient,root=myclient
725 /export/myclient -maproot=root -alldirs myclient
728 If the server and client are of the same architecture, then the client
729 can share the server's
732 .Pq as is done above .
733 If not, you must build a properly fleshed out
735 partition for the client in some other part of the server's
736 file system, to serve to the client.
742 you might create and fill
744 and then use the following
748 .Bd -literal -offset indent -compact
749 /export/usr.sun3 -ro myclient
750 /export/myclient -rw=myclient,root=myclient
753 Of course, in either case you will have to have an
755 server running on the server side.
756 .Sh CLIENT CONFIGURATION
757 Copy and customize at least the following files in
758 .Pa /export/myclient/root :
760 .Bd -literal -offset indent -compact
761 # cd /export/myclient/root/etc
763 # cp /etc/hosts hosts
764 # echo 'hostname="myclient"' \*[Gt]\*[Gt] rc.conf
765 # echo "inet 192.197.96.12" \*[Gt] ifconfig.le0
768 Note that "le0" above should be replaced with the name of
769 the network interface that the client will use for booting;
770 the network interface name is device dependent in
773 Correct the critical mount points and the swap file in the client's
777 .Pa /export/myclient/root/etc/fstab
781 .Bd -literal -offset indent -compact
782 myserver:/export/myclient/root / nfs rw 0 0
783 myserver:/usr /usr nfs rw 0 0
784 /swap none swap sw 0 0
789 specify the swap file in
791 or it will not be used!
795 .Bl -tag -width /usr/mdec/rbootd -compact
813 .It Pa /etc/bootparams
814 client root pathname and swap pathname; see
821 .It Pa /etc/rbootd.conf
822 configuration file for
826 .It Pa /usr/mdec/rbootd
827 location of boot programs offered by
830 location of boot programs offered by
849 .Xr rpc.bootparamd 8 ,
855 .%T "Reverse Address Resolution Protocol"
861 .%T "Bootstrap Loading using TFTP"
867 .%T "Bootstrap Protocol"
873 .%T "The TFTP Protocol (Revision 2)"
879 .%T "Dynamic Host Configuration Protocol"
885 .%T "DHCP Options and BOOTP Vendor Extensions"
888 .Pa http://www.rfc-editor.org/