/[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.15 - (hide annotations) (download) (as text)
Mon Dec 9 10:52:11 2013 UTC (10 months, 1 week ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.14: +2 -2 lines
File MIME type: application/xml
Moved to https://wiki.gentoo.org/wiki/Sparc/Netboot

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

  ViewVC Help
Powered by ViewVC 1.1.20