/[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.4 - (hide annotations) (download) (as text)
Wed Sep 22 21:57:14 2004 UTC (10 years, 2 months ago) by neysx
Branch: MAIN
Changes since 1.3: +2 -0 lines
File MIME type: application/xml
Added $Header$ CVS Keyword -- No Content Change --

1 swift 1.1 <?xml version='1.0' encoding="UTF-8"?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 neysx 1.4 <!-- $Header$ -->
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     <!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
15     <license/>
16    
17 swift 1.3 <version>1.1</version>
18     <date>September 22, 2004</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     If you desire to add additional hosts to /etc/ethers, you do not need to
117     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     Since each entry in /etc/ethers has a hostname, the netboot server needs to
127     be able to resolve the hostname into its IP address. This can be done two
128     ways, /etc/hosts or the nameserver the netboot server uses.
129     </p>
130    
131     <p>
132     An /etc/hosts entry for resolving a hostname will look very similar to the one
133     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     address of 10.0.1.15. So the /etc/hosts entry would look like;
136     </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     If both /etc/hosts and the nameserver have an entry for the host to be
159     netbooted, /etc/hosts will be used first (granted the order of
160     /etc/nsswitch.conf has not been changed from the default).
161     </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     an entry will need to be added to /etc/conf.d/local.start if you want to enable
171     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     Next, options for rarpd will need to be set in /etc/conf.d/rarpd. For an
211     equivalent configuration as the one used above for net-misc/iputils rarpd,
212     adjust /etc/conf.d/rarpd to look like the following
213     </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     will appear as the root (/) directory to the clients when requests are
257     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     Then we will need to change the owner of /tftpboot so that it is owned by user
272     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     /etc/conf.d/local.start will need to be added as atftp has no init.d, inetd or
297     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     Below is an example entry for atftpd in /etc/conf.d/local.start;
303     </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     -v Increase or set the logging leve. No args will increase by one the
316     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     Check to make sure that INIITFTPD_PATH and INITFTP_OPTS in /etc/conf.d/in.tftpd
424     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     experimental/sparc/tftpboot for the appropriate image. We'll assume you are
457     planning to boot a sparc64 host using the
458     gentoo-sparc64-1.4_rc4-20040102.tftpboot image.
459     </p>
460    
461     <p>
462     Once you have an image, copy the image into /tftpboot;
463     </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 swift 1.3 .ARCH 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     sparc64 host and the gentoo-sparc64-1.4_rc4-20040102.tftpboot, use the
543     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     If the netboot server is a Gentoo/LINUX system and experience problems
612     installing the rarpd and tftpd packages, please search http://forums.gentoo.org
613     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
614     please open a new bug at <uri>http://bugs.gentoo.org</uri>
615     </p>
616    
617     <p>
618     <b>I've issued the boot net command but it appears to hang.</b>
619     </p>
620    
621     <p>
622     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;
623     </p>
624    
625     <pre caption="Booting appears to hang">
626     Rebooting with command: boot
627     Boot device: net File and args:
628     </pre>
629    
630     <p>
631     Double check that the file the client needs does exist in /tftpboot. You can
632     confirm the filename it is requesting by looking in the system logs. Also,
633     once this file exists, the client will try to load it. Sometimes, when
634     the file is missing originally, it will freeze downloading the file once it
635     appears. To resolve this, just get back to an OBP prompt, and issue the
636     "boot net" command again. The host should then start downloading the tftpboot image and boot the OS.
637     </p>
638    
639     <p>
640     <b>I'm trying to netboot, but all I see are "Timeout waiting for
641     ARP/RARP packet" messages.
642     </b>
643     </p>
644    
645     <p>
646     This could be due to a few different problems;
647     </p>
648    
649     <ol>
650     <li>
651     Make sure the entry in /etc/ethers exists for the client in question. If
652     the MAC address is incorrect and/or the netboot server cannot resolve the
653     hostname for the client, it cannot respond with the needed information.
654     </li>
655     <li>
656     Verify that the network hub or switch the netboot server and client are
657     connected to allow RARP traffic to flow freely. If the client's request
658     cannot reach the server, or vice versa, the host will be unable to continue.
659     </li>
660     <li>
661     No one is responding to the RARPD request because no services are listening.
662     Verify that the rarpd service is up and running.
663     </li>
664     <li>
665     The client does not think its NIC has a link to the network hub/switch
666     it is plugged into. Check to see if the NIC and the port on the network
667     hub or switch has a link light. If the link light is on, check
668     to see what the setting of tpe-link-test? is in OBP with the command;
669     <c>printenv tpe-link-test?</c>. You should receive something like
670     <path>tpe-link-test? false true</path>.
671     The first column represents the parameter name, the second column shows the
672     current value for the the parameter, and the third column shows the default
673     value for the parameter. In the example above, we can see that the current
674     value is false, which means that the client is not checking to see if the
675     client and network hub or switch can establish a link before issuing its
676     RARP request. Often times this can cause the problem.
677     </li>
678     </ol>
679    
680     <p>
681     To change the value of tpe-link-test? from an OBP prompt, issue the
682     following command;
683     </p>
684    
685     <pre caption="Changing tpe-link-test value">
686     ok <i>setenv tpe-link-test? true</i>
687     tpe-link-test? = true
688     </pre>
689    
690     <p>
691     This shows the value of tpe-link-test? is now true. Try netbooting the client
692     again.
693     </p>
694    
695     </body>
696     </section>
697     </chapter>
698    
699     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20