/[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.12 - (show annotations) (download) (as text)
Wed Mar 3 01:37:41 2010 UTC (4 years, 9 months ago) by nightmorph
Branch: MAIN
Changes since 1.11: +126 -112 lines
File MIME type: application/xml
HUGE cleanup for the sparc netboot doc. a ridiculous number of changes big and small. ugh. bug 296744

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

  ViewVC Help
Powered by ViewVC 1.1.20