/[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.6 - (show annotations) (download) (as text)
Sun Jun 26 12:23:21 2005 UTC (9 years, 5 months ago) by smithj
Branch: MAIN
Changes since 1.5: +10 -6 lines
File MIME type: application/xml
minor english grammer fix for #97075 (again)

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.5 2005/06/25 23:08:24 smithj Exp $ -->
4
5 <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 <version>1.1</version>
18 <date>2005-06-25</date>
19
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 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 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 level. 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 .ARCH suffix. The hexidecimal number should use <e>capital</e> characters.
473 </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 hexidecimal 0A 00 01 0F
497 </pre>
498
499 <p>
500 So for the example sparc64 netboot client, it would look for a file named
501 0A00010F when it tftpboots.
502 </p>
503
504 <p>
505 On sparc however, the file would be 0A00010F.SUN4M, 0A00010F.SUN4C or
506 0A00010F.SUN4D depending on what type of sparc system.
507 </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 Jan 3 22:48:59 stargazer in.tftpd[8368]: RRQ from 10.0.1.15 filename 0A00010F
531 </pre>
532
533 <p>
534 The filename is shown above after "filename" in the log entry, which in this
535 case is 0A00010F.
536 </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 /tftpboot/0A00010F</i>
549 </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 experiences 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
614 encountered by anyone else. If it has not, or the solutions found do not work,
615 then please open a new bug at <uri>http://bugs.gentoo.org</uri>
616 </p>
617
618 <p>
619 <b>I've issued the boot net command but it appears to hang.</b>
620 </p>
621
622 <p>
623 This is presumably because the file your system is trying to load from the
624 tftpboot server is not available. On a SPARC system, you would probably see
625 the following;
626 </p>
627
628 <pre caption="Booting appears to hang">
629 Rebooting with command: boot
630 Boot device: net File and args:
631 </pre>
632
633 <p>
634 Double check that the file the client needs does exist in /tftpboot. You can
635 confirm the filename it is requesting by looking in the system logs. Also,
636 once this file exists, the client will try to load it. Sometimes, when
637 the file is missing originally, it will freeze downloading the file once it
638 appears. To resolve this, just get back to an OBP prompt, and issue the
639 "boot net" command again. The host should then start downloading the tftpboot
640 image and boot the OS.
641 </p>
642
643 <p>
644 <b>I'm trying to netboot, but all I see are "Timeout waiting for
645 ARP/RARP packet" messages.
646 </b>
647 </p>
648
649 <p>
650 This could be due to a few different problems;
651 </p>
652
653 <ol>
654 <li>
655 Make sure the entry in /etc/ethers exists for the client in question. If
656 the MAC address is incorrect and/or the netboot server cannot resolve the
657 hostname for the client, it cannot respond with the needed information.
658 </li>
659 <li>
660 Verify that the network hub or switch the netboot server and client are
661 connected to allow RARP traffic to flow freely. If the client's request
662 cannot reach the server, or vice versa, the host will be unable to continue.
663 </li>
664 <li>
665 No one is responding to the RARPD request because no services are listening.
666 Verify that the rarpd service is up and running.
667 </li>
668 <li>
669 The client does not think its NIC has a link to the network hub/switch
670 it is plugged into. Check to see if the NIC and the port on the network
671 hub or switch has a link light. If the link light is on, check
672 to see what the setting of tpe-link-test? is in OBP with the command;
673 <c>printenv tpe-link-test?</c>. You should receive something like
674 <path>tpe-link-test? false true</path>.
675 The first column represents the parameter name, the second column shows the
676 current value for the the parameter, and the third column shows the default
677 value for the parameter. In the example above, we can see that the current
678 value is false, which means that the client is not checking to see if the
679 client and network hub or switch can establish a link before issuing its
680 RARP request. Often times this can cause the problem.
681 </li>
682 </ol>
683
684 <p>
685 To change the value of tpe-link-test? from an OBP prompt, issue the
686 following command;
687 </p>
688
689 <pre caption="Changing tpe-link-test value">
690 ok <i>setenv tpe-link-test? true</i>
691 tpe-link-test? = true
692 </pre>
693
694 <p>
695 This shows the value of tpe-link-test? is now true. Try netbooting the client
696 again.
697 </p>
698
699 </body>
700 </section>
701 </chapter>
702
703 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20