No empty .Rs/.Re
[netbsd-mini2440.git] / share / man / man8 / diskless.8
blob1960392b3d58b8858c9079e4b236ac6600715828
1 .\"     $NetBSD: diskless.8,v 1.28 2005/06/20 13:25:25 peter 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
35 The ability to boot a system over the network is useful for
36 two kinds of systems:
37 .Pp
38 .Bl -tag -width diskless
39 .It Em diskless
40 a system with no attached mass storage media to boot or run from
41 .Pq e.g. a network computer .
42 .It Em dataless
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.
45 .El
46 .Pp
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
51 .Nx
52 are capable of being network booted.
53 .Pp
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:
57 .Pp
58 .Bl -tag -width BOOTP -offset indent -compact
59 .It Tn RARP
60 Reverse Address Resolution Protocol
61 .Pq Tn ARP
62 .It Tn DHCP
63 Dynamic Host Configuration Protocol
64 .It Tn BOOTP
65 Bootstrap Protocol
66 .El
67 .Pp
68 This information can also be derived from non-volatile
69 .Tn RAM
70 or by a transform of a network interface
71 .Pq e.g. Tn Ethernet
72 .Tn MAC
73 address.
74 .Pp
75 The protocols used to load a
76 .Nx
77 kernel over a network include, but are not limited to:
78 .Pp
79 .Bl -tag -width TFTP -offset indent -compact
80 .It Tn TFTP
81 Trivial File Transfer Protocol
82 .It Tn NFS
83 .Tn Sun
84 Network File System
85 .It Tn RMP
86 .Tn \&HP
87 Remote Maintenance Protocol
88 .It Tn MOP
89 .Tn DEC
90 Maintenance Operations Protocol
91 .El
92 .Pp
93 Derivation of the filename of the secondary bootstrap program can
94 be done by a transform of a network interface
95 .Tn MAC
96 address
97 .Pq or other protocol address ,
98 or provided by a server as with
99 .Tn BOOTP ,
101 .Tn DHCP .
102 How this is done is platform dependent; see
103 .Xr boot 8 .
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
113 .Tn \&HP
114 .Tn RMP
115 and the
117 kernel can use
118 .Tn \&IP
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
125 .Pq or similar
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
130 .Tn RARP ,
131 .Tn BOOTP ,
132 .Tn DHCP ,
134 .Tn Sun RPC
135 .Qq bootparams .
137 .Xr options 4
138 for a list of methods that can be compiled into a
140 kernel.
143 only supports the
144 .Tn Sun
145 Network File System
146 .Pq Tn NFS
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.
153 .Sy N.B.
154 .Tn DHCP
155 is essentially a series of extensions to
156 .Tn BOOTP ;
159 .Xr dhcpd 8
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
164 .Tn LAN
165 so that broadcast queries from the clients can be heard by the servers.
166 Unless specially configured, routers block broadcasts from propagating from
167 .Tn LAN
169 .Tn LAN ;
170 some routers can be configured to
171 .Qq forward
172 broadcast
173 .Tn BOOTP
174 packets to another
175 .Tn LAN
176 attached to that router, which permits a server on that remote
177 .Tn LAN
178 to respond to the client's broadcast query.
179 .Sh OPERATION
180 When booting a system over the network, there are three
181 phases of interaction between client and server:
183 .Bl -enum -compact
185 The system firmware
186 .Pq or stage-1 bootstrap
187 loads a boot program.
189 The boot program loads a
191 kernel.
195 kernel performs an
196 .Tn NFS
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.
205 Some examples:
207 .Tn DEC
208 Alpha systems use
209 .Tn BOOTP
210 to determine the client's
211 .Tn \&IP
212 address and then use
213 .Tn TFTP
214 load a secondary bootstrap program from the server and filename
215 specified in the
216 .Tn BOOTP
217 reply.
218 .Tn DEC
219 Alpha systems can also use
220 .Tn MOP
221 to load a program to run the system.
223 .Tn Sun
224 systems use
225 .Tn RARP
226 to determine the client's
227 .Tn \&IP
228 address, transform that address to a hexadecimal string to form
229 the filename of the secondary boot program, and then use
230 .Tn TFTP
231 to download the boot program from the server that sent the
232 .Tn RARP
233 reply.
235 .Tn \&HP
236 300-series systems use the
237 .Tn \&HP
238 .Tn RMP
239 to download a boot program.
241 Typical personal computers may load a network boot program either
242 from diskette or from a
243 .Tn PROM
244 on a Network Interface Card
245 .Pq Tn NIC .
246 Some
247 .Tn BIOS Ns No \&es
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
254 .Tn Sun
256 .Nx Ns Tn /hp300
257 .Pc .
258 The boot program:
260 .Bl -enum -compact
262 gets the client
263 .Tn \&IP
264 address using
265 .Tn RARP .
267 gets the client name and server
268 .Tn \&IP
269 address by broadcasting an
270 .Tn RPC / BOOTPARAMS / WHOAMI
271 request with the client
272 .Tn \&IP
273 address.
275 gets the server path for this client's
276 root using an
277 .Tn RPC / BOOTPARAMS / GETFILE
278 request with the client name.
280 gets the root file handle by calling
281 .Xr mountd 8
282 with the server path for the client root file system.
284 gets the kernel file handle by calling
285 .Tn NFS
286 .Fn lookup
287 on the root file handle.
289 loads the kernel using
290 .Tn NFS
291 read calls on the kernel file handle.
293 transfers control to the kernel entry point.
297 .Tn BOOTP
298 and/or
299 .Tn DHCP
300 secondary bootstrap program will do the following:
302 .Bl -enum -compact
304 query for the client's bootstrap parameters.
305 The response must include the client's
306 .Tn \&IP
307 address, and a
308 .Tn TFTP
309 server to load the
311 kernel from.
313 loads the
315 kernel from the
316 .Tn TFTP
317 server.
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
323 .Tn NFS
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
330 .Xr config 1
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
337 .Tn BOOTP ,
338 .Tn DHCP ,
340 .Tn Sun RPC BOOTPARAMS ;
342 .Xr options 4 .
344 The procedure typically used by the kernel is as follows:
346 .Bl -enum -compact
348 The kernel finds a boot server using the same procedures
349 as described above to determine the client's
350 .Tn \&IP
351 address, an
352 .Tn NFS
353 server, etc.
355 The kernel gets the
356 .Tn NFS
357 file handle for root using the same procedure as described above.
359 The kernel calls the
360 .Tn NFS
361 .Fn getattr
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
371 .Xr inetd 8 ,
372 and some must run independently, started from
373 .Pa /etc/rc ;
375 .Xr rc.conf 5 .
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
390 .Sy N.B.
391 .Tn DHCP
392 is essentially a series of extensions to
393 .Tn BOOTP ;
396 .Xr dhcpd 8
397 is capable of responding to both kinds of protocol requests.
398 Since they both bind to the same
399 .Tn UDP
400 port, only one may be run on a given server.
402 In the following examples, the client's hostname is
403 .Sy myclient ;
404 the server is
405 .Sy myserver ,
406 and the addresses are all fictional.
407 In these examples
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.
411 .Ss RARP
412 For clients that use
413 .Tn RARP
414 to obtain their
415 .Tn \&IP
416 address,
417 an entry must be added for each client to
418 .Pa /etc/ethers
419 with the client's
420 .Tn Ethernet
421 .Tn MAC
422 address and Internet hostname:
424 .Bd -literal -offset indent -compact
425 8:0:20:7:c5:c7          myclient
428 This will be used by
429 .Xr rarpd 8
430 to reply to queries from the clients.
431 There must be one entry per client system.
433 A client system's
434 .Tn Ethernet
435 .Tn MAC
436 address is often printed on the system case, or on a chip on its
437 motherboard, or on the
438 .Tn NIC .
439 If not,
440 .Qq sniffing
441 the network with
442 .Xr tcpdump 8
443 when the client is powered-on should reveal its
444 .Tn Ethernet
445 .Tn MAC
446 address.
448 Each client system that uses
449 .Tn RARP
450 must have its own, unique
451 .Tn \&IP
452 address assigned to it.
453 Assign an
454 .Tn \&IP
455 address for myclient in your
456 .Pa /etc/hosts
457 file, or in the master file for your
458 .Tn DNS
459 zone.
461 .Pa /etc/hosts
462 the entry should look like:
464 .Bd -literal -offset indent -compact
465 192.197.96.12           myclient
467 .Ss DHCP/BOOTP
470 .Tn DHCP
471 server
472 .Xr dhcpd 8
473 was developed by the Internet Software Consortium
474 .Pq ISC ;
475 .Pa http://www.isc.org/
477 .Tn DHCP
478 can provide a wide range of information to a requesting client;
479 the key data for bootstrapping a diskless client are:
481 .Bl -enum -compact
484 .Tn \&IP
485 address
487 a subnet mask
490 .Tn TFTP
491 server address for loading the secondary bootstrap and the
493 kernel
495 a filename of the secondary bootstrap
498 .Tn NFS
499 server address for the client's file system
501 the client's root file system path, to be
502 .Tn NFS
503 mounted.
506 An example for
507 .Pa /etc/dhcpd.conf
509 .Bd -literal -offset indent
510 host 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";
520 That
521 .Sy host
522 declaration goes inside a
523 .Sy subnet
524 declaration, which gives parameters for all hosts on the subnet
525 that will be using
526 .Tn DHCP ,
527 such as the
528 .Qq routers
529 .Pq the default route ,
530 .Qq subnet-mask ,
531 .Qq broadcast-address ,
532 .Qq domain-name-servers ,
533 etc.
535 .Xr dhcpd.conf 5
536 for details.
537 In that example,
538 .Sy myclient
539 has an assigned IP address.
542 .Tn DHCP
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
546 .Tn DHCP
547 is extensible, some hardware vendors have specified
548 .Tn DHCP
549 options to return information to requesting clients that are specific
550 to that platform.
551 Please see your platform's
552 .Xr boot 8
553 for details.
554 .Ss TFTP
555 If booting a
556 .Tn Sun
557 system, or other system that expects to use
558 .Tn TFTP ,
559 ensure that
560 .Xr inetd 8
561 is configured to run
562 .Xr tftpd 8 .
564 .Xr tftpd 8
565 server should be set up to serve the directory
566 .Pa /tftpboot .
568 If booting a
569 .Tn SPARC
570 system, install a copy of the appropriate diskless secondary boot
571 loader
573 such as
574 .Pa /usr/mdec/boot
576 .Pa ofwboot.net
578 in the
579 .Pa /tftpboot
580 directory.
581 Make a link such that the boot program is
582 accessible by a filename composed of the client's
583 .Tn \&IP
584 address in hexadecimal, a dot, and the architecture name
585 .Pq all upper case .
586 For example:
588 .Bd -literal -offset indent -compact
589 # cd /tftpboot
590 # ln -s boot C0C5600C.SUN4
593 For a
594 .Tn Sun-3
596 .Tn UltraSPARC
597 system, the filename would be just C0C5600C
599 these systems' firmware does not append the architecture name
600 .Pc .
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,
605 .Xr tcpdump 8
606 can be used to discover which filename the client is being requested.
607 Also, examination of
608 .Xr tftpd 8
609 log entries
611 typically in
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.
616 .Ss HP RMP
617 If booting an
618 .Tn HP
619 300-series system, ensure that
620 .Pa /etc/rbootd.conf
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
629 .Tn \&HP
630 300-series system
631 .Pa SYS_UBOOT
633 which may be called
634 .Pa uboot.lif
635 before installation
637 must be installed in the directory
638 .Pa /usr/mdec/rbootd .
640 See the
641 .Xr rbootd 8
642 manual page for more information.
643 .Ss Sun RPC BOOTPARAMS
645 .Sy myclient
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
655 and ensure that
656 .Xr rpc.bootparamd 8
658 .Xr rpcbind 8
659 are running.
660 Both
661 .Sy myclient
663 .Sy myserver
664 must have
665 .Tn \&IP
666 addresses in the
667 .Tn DNS
669 .Pa /etc/hosts .
670 .Ss Diskless Client File Systems
671 Build the swap file for
672 .Sy myclient
673 on the
674 .Tn NFS
675 server:
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.
684 Populate
685 .Sy myclient Ns No 's
686 root file system on the
687 .Tn NFS
688 server.
689 How this is done depends on the client architecture and the version
690 of the
692 distribution.
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.
698 If the
699 .Tn NFS
700 server is going to support multiple different architectures
702 e.g.
703 .Tn Alpha ,
704 .Tn PowerPC ,
705 .Tn SPARC ,
706 .Tn MIPS
707 .Pc ,
708 then it is important to think carefully about how to lay out the
709 .Tn NFS
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 .
714 .Ss NFS
715 Export the client-populated file systems on the
716 .Tn NFS
717 server in
718 .Pa /etc/exports :
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
728 If the server and client are of the same architecture, then the client
729 can share the server's
730 .Pa /usr
731 file system
732 .Pq as is done above .
733 If not, you must build a properly fleshed out
734 .Pa /usr
735 partition for the client in some other part of the server's
736 file system, to serve to the client.
738 If your server is a
739 .Tn SPARC ,
740 and your client a
741 .Tn Sun-3 ,
742 you might create and fill
743 .Pa /export/usr.sun3
744 and then use the following
745 .Pa /etc/exports
746 lines:
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
754 .Tn NFS
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
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
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
771 .Nx .
773 Correct the critical mount points and the swap file in the client's
774 .Pa /etc/fstab
776 which will be
777 .Pa /export/myclient/root/etc/fstab
779 i.e.
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
787 Note, you
788 .Em must
789 specify the swap file in
790 .Pa /etc/fstab
791 or it will not be used!
793 .Xr swapctl 8 .
794 .Sh FILES
795 .Bl -tag -width /usr/mdec/rbootd -compact
796 .It Pa /etc/hosts
797 table of associated
798 .Tn \&IP
799 addresses and
800 .Tn \&IP
801 host names; see
802 .Xr hosts 5
803 .It Pa /etc/ethers
804 table of associated
805 .Tn Ethernet
806 .Tn MAC
807 addresses and
808 .Tn \&IP
809 host names used by
810 .Xr rarpd 8 ;
812 .Xr ethers 5
813 .It Pa /etc/bootparams
814 client root pathname and swap pathname; see
815 .Xr bootparams 5
816 .It Pa /etc/exports
817 exported
818 .Tn NFS
819 mount points; see
820 .Xr exports 5
821 .It Pa /etc/rbootd.conf
822 configuration file for
823 .Tn \&HP RMP ;
825 .Xr rbootd 8
826 .It Pa /usr/mdec/rbootd
827 location of boot programs offered by
828 .Xr rbootd 8
829 .It Pa /tftpboot
830 location of boot programs offered by
831 .Xr tftpd 8
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
852 .%R RFC
853 .%N 903
854 .%D June 1984
855 .%T "Reverse Address Resolution Protocol"
858 .%R RFC
859 .%N 906
860 .%D June 1984
861 .%T "Bootstrap Loading using TFTP"
864 .%R RFC
865 .%N 951
866 .%D September 1985
867 .%T "Bootstrap Protocol"
870 .%R RFC
871 .%N 1350
872 .%D July 1992
873 .%T "The TFTP Protocol (Revision 2)"
876 .%R RFC
877 .%N 2131
878 .%D March 1997
879 .%T "Dynamic Host Configuration Protocol"
882 .%R RFC
883 .%N 2132
884 .%D March 1997
885 .%T "DHCP Options and BOOTP Vendor Extensions"
888 .Pa http://www.rfc-editor.org/