/[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.1 - (hide annotations) (download) (as text)
Sun Apr 11 16:17:07 2004 UTC (10 years, 6 months ago) by swift
Branch: MAIN
File MIME type: application/xml
#37231 - Add SPARC Netboot document

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

  ViewVC Help
Powered by ViewVC 1.1.20