/[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.8 - (show annotations) (download) (as text)
Thu Aug 18 14:27:28 2005 UTC (8 years, 10 months ago) by neysx
Branch: MAIN
Changes since 1.7: +170 -166 lines
File MIME type: application/xml
Improved coding style  **No content change**

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

  ViewVC Help
Powered by ViewVC 1.1.20