/[gentoo]/xml/htdocs/doc/en/gentoo-sparc-netboot-howto.xml
Gentoo

Contents of /xml/htdocs/doc/en/gentoo-sparc-netboot-howto.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.7 - (hide annotations) (download) (as text)
Thu Aug 18 13:59:23 2005 UTC (8 years, 10 months ago) by neysx
Branch: MAIN
Changes since 1.6: +28 -28 lines
File MIME type: application/xml
#101641 Add missing <path> tags

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 neysx 1.7 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-sparc-netboot-howto.xml,v 1.6 2005/06/26 12:23:21 smithj Exp $ -->
4 neysx 1.4
5 swift 1.1 <guide link="/doc/en/gentoo-sparc-netboot-howto.xml">
6     <title>Gentoo Linux based Netboot HOWTO</title>
7     <author title="SPARC Developer">
8     <mail link="weeve@gentoo.org">Jason Wever</mail>
9     </author>
10     <abstract>
11     Guide for setting up a netboot server for use with the Gentoo/SPARC netboot installation images.
12     </abstract>
13     <!-- The content of this document is licensed under the CC-BY-SA license -->
14 neysx 1.7 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
15 swift 1.1 <license/>
16    
17 neysx 1.7 <version>1.2</version>
18     <date>2005-08-18</date>
19 swift 1.1
20     <chapter>
21     <title>Introduction</title>
22     <section>
23     <body>
24    
25     <note>
26     This howto is currently very SPARC-centric and expecting that you will be
27     setting up your netboot server on an existing Gentoo Linux machine.
28     </note>
29    
30     <p>
31     This document will describe how to setup a network booting environment for a
32     Sun Microsystems SPARC or UltraSPARC based computer. The document assumes that
33     you have an existing Gentoo Linux computer available to act as the netboot
34     server.
35     </p>
36    
37     <p>
38     Both the netboot server and netboot client will need to be on the same
39     network subnet, as the ARP protocol is typically not forwarded across
40     different network subnets.
41     </p>
42    
43     <p>
44     A generic overview of what happens during the netboot process is as follows;
45     </p>
46    
47     <ol>
48     <li>
49     Client machine sends out a reverse ARP (RARP) request to get an IP address.
50     </li>
51     <li>
52     A server machine returns a response to the client with the IP address.
53     </li>
54     <li>
55     The client then attempts to download a boot image from the RARP server
56     using the tftp protocol.
57     </li>
58     <li>
59     Once the image is downloaded, the netboot client then boots the image.
60     </li>
61     </ol>
62    
63     <p>
64     Based on this overview, we will need to install software for a reverse ARP
65     daemon and a tftp daemon.
66     </p>
67    
68     </body>
69     </section>
70     </chapter>
71    
72     <chapter>
73     <title>Software Installation And Configuration</title>
74     <section>
75     <title>The Reverse ARP Daemon</title>
76     <body>
77    
78    
79     <p>
80     Currently, there are two choices for a reverse ARP daemon. They are
81     net-misc/iputils (installed as part of the system profile) and net-misc/rarpd.
82     </p>
83    
84     <note>
85 klasikahl 1.2 Installing net-misc/rarpd will overwrite the rarpd and rarpd manpage from
86 swift 1.1 net-misc/iputils
87     </note>
88    
89     <p>
90     <b>Setting up common rarpd elements</b>: <path>/etc/ethers</path>
91     </p>
92    
93     <p>
94     No matter which rarpd you choose to use, you will need to setup the
95     <path>/etc/ethers</path> file. This file indicates which hosts rarpd should
96     respond to when a request is seen, and what address to reply with.
97     </p>
98    
99     <p>
100     The format of <path>/etc/ethers</path> is MAC address of the NIC the machine
101     will be netbooting from and the hostname. Whitespace delimits the MAC address
102     from the hostname, and each entry should have its own line. The following
103     example is for a host named sparc-netboot.gentoo.org:
104     </p>
105    
106     <pre caption="Example /etc/ethers">
107     08:00:20:77:1f:3e sparc-netboot.gentoo.org
108     </pre>
109    
110     <note>
111     If a given hexidecimal number in the MAC address starts or is 0, you can
112     chose to omit the first 0 (i.e. 08:00:20:77:1f:3e becomes 8:0:20:77:1f:3e).
113     </note>
114    
115     <p>
116 neysx 1.7 If you desire to add additional hosts to <path>/etc/ethers</path>, you do not need to
117 swift 1.1 restart the rarpd services as the file is checked each time a request is
118     received.
119     </p>
120    
121     <p>
122     <b>Resolving hostnames</b>: <path>/etc/hosts</path>
123     </p>
124    
125     <p>
126 neysx 1.7 Since each entry in <path>/etc/ethers</path> has a hostname, the netboot server needs to
127 swift 1.1 be able to resolve the hostname into its IP address. This can be done two
128 neysx 1.7 ways, <path>/etc/hosts</path> or the nameserver the netboot server uses.
129 swift 1.1 </p>
130    
131     <p>
132 neysx 1.7 An <path>/etc/hosts</path> entry for resolving a hostname will look very similar to the one
133 swift 1.1 that probably exists from when you installed Gentoo on the netboot server.
134     For our example host, sparc-netboot.gentoo.org, we'll assume that it has an IP
135 neysx 1.7 address of 10.0.1.15. So the <path>/etc/hosts</path> entry would look like;
136 swift 1.1 </p>
137    
138     <pre caption="/etc/hosts">
139     10.0.1.15 sparc-netboot.gentoo.org
140     </pre>
141    
142    
143     <note>
144     Depending on the environment, you may need to consult your network
145     administrator to get an appropriate IP address or addresses to netboot
146     the host with.
147     </note>
148    
149     <p>
150     If you use a nameserver, then the DNS server administrator will need to add a
151     record for the hostname, in our example sparc-netboot.gentoo.org, to point to
152     the appropriate IP address.
153     Please consult your DNS server administrator and/or the documentation for the
154     DNS server's DNS software for how to add the entry.
155     </p>
156    
157     <note>
158 neysx 1.7 If both <path>/etc/hosts</path> and the nameserver have an entry for the host to be
159     netbooted, <path>/etc/hosts</path> will be used first (granted the order of
160     <path>/etc/nsswitch.conf</path> has not been changed from the default).
161 swift 1.1 </note>
162    
163     <p>
164     <b>Setting up net-misc/iputils rarpd</b>
165     </p>
166    
167     <p>First, we will need to determine the options to use for rarpd. While there
168     are more options than we'll cover here, these options should get you started
169     As there is currently no init.d script for net-misc/iputils version of rarpd,
170 neysx 1.7 an entry will need to be added to <path>/etc/conf.d/local.start</path> if you want to enable
171 swift 1.1 rarpd servies at boot time. A sample entry is as follows;
172     </p>
173    
174     <pre caption="/etc/conf.d/local.start">
175     /usr/sbin/rarpd -v -e eth0
176     </pre>
177    
178     <p>
179     An explination of the above rarpd options (as taken from the man page):
180     </p>
181    
182     <ul>
183     <li>-v Be verbose</li>
184     <li>
185     -e Do not check for the presence of a boot image, reply if MAC address
186     resolves to a valid IP address using /etc/ethers database and DNS
187     </li>
188     <li>
189     eth0 represents the interface rarpd should bind to
190     </li>
191     </ul>
192    
193     <p>
194     For more options, consult the section 8 man page on rarpd
195     </p>
196    
197     <p>
198     <b>Setting up net-misc/rarpd</b>
199     </p>
200    
201     <p>
202     Firstly, we'll need to install rarpd with the following command:
203     </p>
204    
205     <pre caption="Installing rarpd">
206     # <i>emerge net-misc/rarpd</i>
207     </pre>
208    
209     <p>
210 neysx 1.7 Next, options for rarpd will need to be set in <path>/etc/conf.d/rarpd</path>. For an
211 swift 1.1 equivalent configuration as the one used above for net-misc/iputils rarpd,
212 neysx 1.7 adjust <path>/etc/conf.d/rarpd</path> to look like the following
213 swift 1.1 </p>
214    
215     <pre caption="/etc/conf.d/rarpd">
216     RARPD_OPTS="-v -i eth0"
217     </pre>
218    
219     <p>
220     An explination of the above rarpd options (as taken from the man page);
221     </p>
222    
223     <ul>
224     <li>
225     -v Be verbose. Show requests which the daemon is responding to.
226     </li>
227     <li>
228     -i Bind to the named interface. By default rarpd binds to the default
229     interface for the local system type, if available.
230     </li>
231     </ul>
232    
233     <p>
234     For more options, consult the section 8 man page on rarpd and rarpd --help.
235     </p>
236    
237     </body>
238     </section>
239     <section>
240     <title>The tftpd Daemon</title>
241     <body>
242    
243     <p>
244     Here there are three options for a tftp daemon, net-misc/atftp,
245     net-misc/netkit-tftp and net-misc/tftp-hpa. You only need to install one of
246     the tftp daemons for proper operation.
247     </p>
248    
249     <p>
250     <b>Setting up common tftpd elements</b>
251     </p>
252    
253     <p>
254     Each tftp daemon will need a directory from which to serve files to tftp
255     clients. The directory we will use for this howto will be /tftpboot. This
256 neysx 1.7 will appear as the root (<path>/</path>) directory to the clients when requests are
257 swift 1.1 received. Additionally, we'll setup the system to run the tftp daemon with the
258     user and group nobody.
259     </p>
260    
261     <p>
262     If the directory you have chosen does not currently exist, it will need to be
263     created with the mkdir command. The command for the example /tftpboot is;
264     </p>
265    
266     <pre caption="Creating /tftpboot">
267     # <i>/bin/mkdir /tftpboot</i>
268     </pre>
269    
270     <p>
271 neysx 1.7 Then we will need to change the owner of <path>/tftpboot</path> so that it is owned by user
272 swift 1.1 nobody and group nobody;
273     </p>
274    
275     <pre caption="Changing ownership">
276     # <i>chown nobody:nobody /tftpboot</i>
277     </pre>
278    
279     </body>
280     </section>
281     <section>
282     <title>The atftp Daemon</title>
283     <body>
284    
285     <p>
286     First, install the net-misc/atftp package as follows;
287     </p>
288    
289     <pre caption="Installing atftp">
290     # <i>emerge net-misc/atftp</i>
291     </pre>
292    
293     <p>
294     After the net-misc/atftp package has been installed, it will need to be
295     configured. If tftpd services are desired at boot time, an entry to
296 neysx 1.7 <path>/etc/conf.d/local.start</path> will need to be added as atftp has no init.d, inetd or
297 swift 1.1 xinetd scripts of its own. If you want to use inetd or xinetd for controlling
298     the tftpd service, please see their respective man pages.
299     </p>
300    
301     <p>
302 neysx 1.7 Below is an example entry for atftpd in <path>/etc/conf.d/local.start</path>;
303 swift 1.1 </p>
304    
305     <pre caption="/etc/conf.d/local.start">
306     /usr/sbin/in.tftpd -v --daemon /tftpboot
307     </pre>
308    
309     <p>
310     An explination of the above rarpd options (as taken from the man page);
311     </p>
312    
313     <ul>
314     <li>
315 smithj 1.5 -v Increase or set the logging level. No args will increase by one the
316 swift 1.1 current value. Default is LOG_NOTICE, see syslog(3) for log level. Current
317     value range from 0 (LOG_EMERG) to 7 (LOG_DEBUG)
318     </li>
319     <li>
320     --daemon Run as a daemon. Do not use this option if atftpd is started by
321     inetd.
322     </li>
323     </ul>
324    
325     <p>
326     For more options, consult the section 8 man page on atftpd
327     </p>
328    
329     </body>
330     </section>
331     <section>
332     <title>The netkit-tftp Daemon</title>
333     <body>
334    
335     <p>
336     First, install the net-misc/netkit-tftp package as follows;
337     </p>
338    
339     <pre caption="Installing netkit-tftp">
340     # <i>emerge net-misc/netkit-tftp</i>
341     </pre>
342    
343     <p>
344     Secondly, install sys-apps/xinetd if it is not currently present;
345     After the net-misc/netkit-tftp and sys-apps/xinetd packages have been
346     installed, netkit-tftp will need to be configured. netkit-tftp needs to be
347     run from xinetd, however it does not provide example scripts of its own. A
348     sample xinetd file is provided below;
349     </p>
350    
351     <pre caption="Sample /etc/xinetd.d/tftp file">
352     service tftp
353     {
354     protocol = udp
355     port = 69
356     socket_type = dgram
357     wait = yes
358     user = nobody
359     group = nobody
360     server = /usr/sbin/in.tftpd
361     server_args = /tftpboot
362     only_from = 10.0.1.0
363     disable = no
364     }
365     </pre>
366    
367     <note>
368     This sample xinetd configuration file for tftp uses the line "disable = no",
369     which enables the service by default. This is opposite of the default way
370     packages in Gentoo provide their respective xinetd configuration files, which
371     have disable set to yes.
372     </note>
373    
374     <p>
375     An explination of the above options which can be changed;
376     user user in.tftpd requests are handled as
377     group group in.tftpd requests are handled as
378     server_args root directory for tftp daemon to serve files from
379     only_from tells xinetd what hosts to allow tftp connections from
380     </p>
381    
382     <p>
383     Additional information on xinetd configuration files can be found in the
384     section 5 manpage on xinetd.conf
385     </p>
386    
387     <p>
388     If xinetd is running, you can send it the HUP signal to have it re-read its
389     configuration files;
390     </p>
391    
392     <pre caption="Sending HUP signal to xinetd">
393     # <i>/bin/killall -HUP xinetd</i>
394     </pre>
395    
396     <p>
397     If xinetd is not running, start it with the init.d command;
398     </p>
399    
400     <pre caption="Starting xinetd">
401     # <i>/etc/init.d/xinetd start</i>
402     </pre>
403    
404     <p>
405     For more information, consult the section 8 man page on in.tftpd
406     </p>
407    
408     </body>
409     </section>
410     <section>
411     <title>The tftp-hpa Daemon</title>
412     <body>
413     <p>
414     First, install the tftp-hpa package using the following command;
415     </p>
416    
417     <pre caption="Installing tftp-hpa">
418     # <i>emerge net-misc/tftp-hpa</i>
419     </pre>
420    
421     <p>
422     tftp-hpa comes with an init.d and the accompanying conf.d configuration file.
423 neysx 1.7 Check to make sure that INIITFTPD_PATH and INITFTP_OPTS in <path>/etc/conf.d/in.tftpd</path>
424 swift 1.1 match those below;
425     </p>
426    
427     <pre caption="/etc/conf.d/in.tftpd">
428     INTFTPD_PATH="/tftpboot"
429     INTFTPD_OPTS="-s -v -l ${INTFTPD_PATH}"
430     </pre>
431    
432     <p>
433     The tftp daemon can then be started via the init.d script;
434     </p>
435    
436     <pre caption="Starting in.tftpd">
437     # <i>/etc/init.d/in.tftpd start</i>
438     </pre>
439    
440     <p>
441     For more options, consult the section 8 man page on tftpd.
442     </p>
443    
444     </body>
445     </section>
446     </chapter>
447    
448     <chapter>
449     <title>Preparing a tftpboot image for use by a client</title>
450     <section>
451     <body>
452    
453     <p>
454     Make sure you have an image you want to use for netbooting. For a sparc or
455     sparc64 netboot image, please check your local Gentoo distfiles mirror under
456 neysx 1.7 <path>experimental/sparc/tftpboot</path> for the appropriate image. We'll assume you are
457 swift 1.1 planning to boot a sparc64 host using the
458 neysx 1.7 <path>gentoo-sparc64-1.4_rc4-20040102.tftpboot</path> image.
459 swift 1.1 </p>
460    
461     <p>
462 neysx 1.7 Once you have an image, copy the image into <path>/tftpboot</path>;
463 swift 1.1 </p>
464    
465     <pre caption="Copying the image">
466     # <i>cp gentoo-sparc64-1.4_rc4-20040102.tftpboot /tftpboot</i>
467     </pre>
468    
469     <p>
470     Now, when the netboot client makes a tftp request, it looks for a file that is
471     the hexidecimal number of its current IP address, and on some platforms an
472 neysx 1.7 <path>.ARCH</path> suffix. The hexidecimal number should use <e>capital</e> characters.
473 swift 1.1 </p>
474    
475     <p>
476     A guide on how to convert decimal to hexidecimal is available at
477     <uri>http://www.permadi.com/tutorial/numDecToHex/</uri>
478     </p>
479    
480     <p>
481     And for the lazy/impatient, you can find a decimal to hexidecimal conversion
482     tool at <uri>http://dan.drydog.com/hextemp.html</uri>
483     </p>
484    
485     <note>
486     For each octet in the IP address (the 10 in 10.0.1.15 for instance), you
487     will need to convert it to hexidecimal, rather than converting the IP address asa singular number.
488     </note>
489    
490     <p>So for our example IP address, 10.0.1.15, let's look at its hexidecimal
491     equivalent;
492     </p>
493    
494     <pre caption="Example IP address">
495     decimal 10 0 1 15
496 swift 1.3 hexidecimal 0A 00 01 0F
497 swift 1.1 </pre>
498    
499     <p>
500     So for the example sparc64 netboot client, it would look for a file named
501 swift 1.3 0A00010F when it tftpboots.
502 swift 1.1 </p>
503    
504     <p>
505 swift 1.3 On sparc however, the file would be 0A00010F.SUN4M, 0A00010F.SUN4C or
506     0A00010F.SUN4D depending on what type of sparc system.
507 swift 1.1 </p>
508    
509     <p>
510     Additionally, if you are really really lazy (like me), you can netboot the host
511     to get the filename the client is looking for from the netboot server logs.
512     </p>
513    
514     <p>
515     Make sure that both the rarpd and tftpd daemon you've chosen are currently
516     running, then boot the host as described below in "Netbooting the client".
517     </p>
518    
519     <p>
520     The client will appear to hang after the boot net command is issued.
521     Then on the netboot server, check the system logs for an entry for in.tftpd.
522     </p>
523    
524     <p>
525     An example entry from a netboot server running sysklogd and tftp-hpa looks
526     like;
527     </p>
528    
529     <pre caption="Log entry for netboot server">
530 swift 1.3 Jan 3 22:48:59 stargazer in.tftpd[8368]: RRQ from 10.0.1.15 filename 0A00010F
531 swift 1.1 </pre>
532    
533     <p>
534     The filename is shown above after "filename" in the log entry, which in this
535 swift 1.3 case is 0A00010F.
536 swift 1.1 </p>
537    
538     <p>
539     As a way to keep track of what netboot image you are using, and to allow
540     multiple machines to use the same netboot image, you can use a soft link to
541     create the file with the hexidecimal value. To create this using our sample
542 neysx 1.7 sparc64 host and the <path>gentoo-sparc64-1.4_rc4-20040102.tftpboot</path>, use the
543 swift 1.1 following command;
544     </p>
545    
546     <pre caption="Linking the image files">
547     # <i>/bin/ln -s /tftpboot/gentoo-sparc64-1.4_rc4-20040102.tftpboot \
548 swift 1.3 /tftpboot/0A00010F</i>
549 swift 1.1 </pre>
550    
551     <p>
552     Now everything should be set for netbooting!
553     </p>
554    
555     </body>
556     </section>
557     </chapter>
558    
559     <chapter>
560     <title>Netbooting the client</title>
561    
562     <section>
563     <body>
564    
565     <p>
566     From OpenBoot PROM (OBP) on the SPARC, enter the command;
567     </p>
568    
569     <pre caption="Booting OBP">
570     ok <i>boot net</i>
571     </pre>
572    
573     <p>
574     Other methods for certain machines are:
575     </p>
576    
577     <pre caption="Booting OBP, alternative">
578     ok <i>boot net-tpe</i>
579     </pre>
580    
581     <note>
582     If your system doesn't present you with an OBP at boot time, you will
583     either need to press the Stop and A key, or send a break signal via serial
584     console before the system boots an OS. If your system cannot find an OS,
585     it should either try to boot via the network interface (which is what we want),
586     or leave you at an OBP prompt.
587     </note>
588    
589     <p>
590     This will initiate the networking booting process. A constantly changing
591     string of hexidecimal digits should appear. When the image has finished
592     loading, the kernel will take over and start the OS booting process. In the
593     case of our sparc64 install image, you will be left at a shell prompt from
594     which you can begin the install process.
595     </p>
596    
597     </body>
598     </section>
599     </chapter>
600    
601     <chapter>
602     <title>Troubleshooting</title>
603     <section>
604     <body>
605    
606     <p>
607     <b>Building the prerequisite software</b>
608     </p>
609    
610     <p>
611 smithj 1.6 If the netboot server is a Gentoo/LINUX system and experiences problems
612 neysx 1.7 installing the rarpd and tftpd packages, please search <uri>http://forums.gentoo.org</uri>
613 smithj 1.6 and <uri>http://bugs.gentoo.org</uri> to see if this problem has been
614     encountered by anyone else. If it has not, or the solutions found do not work,
615     then please open a new bug at <uri>http://bugs.gentoo.org</uri>
616 swift 1.1 </p>
617    
618     <p>
619     <b>I've issued the boot net command but it appears to hang.</b>
620     </p>
621    
622     <p>
623 smithj 1.6 This is presumably because the file your system is trying to load from the
624     tftpboot server is not available. On a SPARC system, you would probably see
625     the following;
626 swift 1.1 </p>
627    
628     <pre caption="Booting appears to hang">
629     Rebooting with command: boot
630     Boot device: net File and args:
631     </pre>
632    
633     <p>
634 neysx 1.7 Double check that the file the client needs does exist in <path>/tftpboot</path>. You can
635 swift 1.1 confirm the filename it is requesting by looking in the system logs. Also,
636     once this file exists, the client will try to load it. Sometimes, when
637     the file is missing originally, it will freeze downloading the file once it
638     appears. To resolve this, just get back to an OBP prompt, and issue the
639 smithj 1.6 "boot net" command again. The host should then start downloading the tftpboot
640     image and boot the OS.
641 swift 1.1 </p>
642    
643     <p>
644     <b>I'm trying to netboot, but all I see are "Timeout waiting for
645     ARP/RARP packet" messages.
646     </b>
647     </p>
648    
649     <p>
650     This could be due to a few different problems;
651     </p>
652    
653     <ol>
654     <li>
655 neysx 1.7 Make sure the entry in <path>/etc/ethers</path> exists for the client in question. If
656 swift 1.1 the MAC address is incorrect and/or the netboot server cannot resolve the
657     hostname for the client, it cannot respond with the needed information.
658     </li>
659     <li>
660     Verify that the network hub or switch the netboot server and client are
661     connected to allow RARP traffic to flow freely. If the client's request
662     cannot reach the server, or vice versa, the host will be unable to continue.
663     </li>
664     <li>
665     No one is responding to the RARPD request because no services are listening.
666     Verify that the rarpd service is up and running.
667     </li>
668     <li>
669     The client does not think its NIC has a link to the network hub/switch
670     it is plugged into. Check to see if the NIC and the port on the network
671     hub or switch has a link light. If the link light is on, check
672     to see what the setting of tpe-link-test? is in OBP with the command;
673     <c>printenv tpe-link-test?</c>. You should receive something like
674     <path>tpe-link-test? false true</path>.
675     The first column represents the parameter name, the second column shows the
676     current value for the the parameter, and the third column shows the default
677     value for the parameter. In the example above, we can see that the current
678     value is false, which means that the client is not checking to see if the
679     client and network hub or switch can establish a link before issuing its
680     RARP request. Often times this can cause the problem.
681     </li>
682     </ol>
683    
684     <p>
685     To change the value of tpe-link-test? from an OBP prompt, issue the
686     following command;
687     </p>
688    
689     <pre caption="Changing tpe-link-test value">
690     ok <i>setenv tpe-link-test? true</i>
691     tpe-link-test? = true
692     </pre>
693    
694     <p>
695     This shows the value of tpe-link-test? is now true. Try netbooting the client
696     again.
697     </p>
698    
699     </body>
700     </section>
701     </chapter>
702    
703     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20