/[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.2 - (show annotations) (download) (as text)
Thu Apr 15 04:48:43 2004 UTC (10 years, 7 months ago) by klasikahl
Branch: MAIN
Changes since 1.1: +1 -1 lines
File MIME type: application/xml
Bug 47861

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 Installing 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