/[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.11 - (show annotations) (download) (as text)
Mon Dec 14 21:35:05 2009 UTC (4 years, 11 months ago) by nightmorph
Branch: MAIN
Changes since 1.10: +10 -24 lines
File MIME type: application/xml
Update sparc netboot howto with hexadecimal conversion notes, 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.10 2008/05/20 18:46:15 swift 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
12 <abstract>
13 Guide for setting up a netboot server for use with the Gentoo/SPARC netboot
14 installation images.
15 </abstract>
16
17 <!-- The content of this document is licensed under the CC-BY-SA license -->
18 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
19 <license/>
20
21 <version>1.3</version>
22 <date>2009-12-14</date>
23
24 <chapter>
25 <title>Introduction</title>
26 <section>
27 <body>
28
29 <note>
30 This howto is currently very SPARC-centric and expecting that you will be
31 setting up your netboot server on an existing Gentoo Linux machine.
32 </note>
33
34 <p>
35 This document will describe how to setup a network booting environment for a
36 Sun Microsystems SPARC or UltraSPARC based computer. The document assumes that
37 you have an existing Gentoo Linux computer available to act as the netboot
38 server.
39 </p>
40
41 <p>
42 Both the netboot server and netboot client will need to be on the same network
43 subnet, as the ARP protocol is typically not forwarded across different network
44 subnets.
45 </p>
46
47 <p>
48 A generic overview of what happens during the netboot process is as follows;
49 </p>
50
51 <ol>
52 <li>
53 Client machine sends out a reverse ARP (RARP) request to get an IP address
54 </li>
55 <li>A server machine returns a response to the client with the IP address</li>
56 <li>
57 The client then attempts to download a boot image from the RARP server
58 using the tftp protocol
59 </li>
60 <li>Once the image is downloaded, the netboot client then boots the image</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 <p>
79 Currently, there are two choices for a reverse ARP daemon. They are
80 net-misc/iputils (installed as part of the system profile) and net-misc/rarpd.
81 </p>
82
83 <note>
84 Installing net-misc/rarpd will overwrite the rarpd and rarpd manpage from
85 net-misc/iputils
86 </note>
87
88 <p>
89 <b>Setting up common rarpd elements</b>: <path>/etc/ethers</path>
90 </p>
91
92 <p>
93 No matter which rarpd you choose to use, you will need to setup the
94 <path>/etc/ethers</path> file. This file indicates which hosts rarpd should
95 respond to when a request is seen, and what address to reply with.
96 </p>
97
98 <p>
99 The format of <path>/etc/ethers</path> is the MAC address of the NIC the
100 machine will be netbooting and its hostname. Whitespace delimits the MAC
101 address from the hostname, and each entry should have its own line. The
102 following example is for a host named sparc-netboot.gentoo.org:
103 </p>
104
105 <pre caption="Example /etc/ethers">
106 08:00:20:77:1f:3e sparc-netboot.gentoo.org
107 </pre>
108
109 <note>
110 If a given hexadecimal number in the MAC address starts or is 0, you can chose
111 to omit the first 0 (i.e. 08:00:20:77:1f:3e becomes 8:0:20:77:1f:3e).
112 </note>
113
114 <p>
115 If you desire to add additional hosts to <path>/etc/ethers</path>, you do not
116 need to restart the rarpd services as the file is checked each time a request
117 is received.
118 </p>
119
120 <p>
121 <b>Resolving hostnames</b>: <path>/etc/hosts</path>
122 </p>
123
124 <p>
125 Since each entry in <path>/etc/ethers</path> has a hostname, the netboot server
126 needs to be able to resolve the hostname into its IP address. This can be done
127 two ways, <path>/etc/hosts</path> or the nameserver the netboot server uses.
128 </p>
129
130 <p>
131 An <path>/etc/hosts</path> entry for resolving a hostname will look very
132 similar to the one that probably exists from when you installed Gentoo on the
133 netboot server. For our example host, sparc-netboot.gentoo.org, we'll assume
134 that it has an IP address of 10.0.1.15. So the <path>/etc/hosts</path> entry
135 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 the host
146 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. Please consult your DNS server administrator and/or
153 the documentation for the DNS server's DNS software for how to add the entry.
154 </p>
155
156 <note>
157 If both <path>/etc/hosts</path> and the nameserver have an entry for the host
158 to be netbooted, <path>/etc/hosts</path> will be used first (granted the order
159 of <path>/etc/nsswitch.conf</path> has not been changed from the default).
160 </note>
161
162 <p>
163 <b>Setting up net-misc/iputils rarpd</b>
164 </p>
165
166 <p>
167 First, we will need to determine the options to use for rarpd. While there are
168 more options than we'll cover here, these options should get you started As
169 there is currently no init.d script for net-misc/iputils version of rarpd, an
170 entry will need to be added to <path>/etc/conf.d/local.start</path> if you want
171 to enable 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 explanation 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>eth0 represents the interface rarpd should bind to</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 <path>/etc/conf.d/rarpd</path>.
209 For an equivalent configuration as the one used above for net-misc/iputils
210 rarpd, adjust <path>/etc/conf.d/rarpd</path> 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 explanation of the above rarpd options (as taken from the man page);
219 </p>
220
221 <ul>
222 <li>
223 <c>-v</c> Be verbose. Show requests which the daemon is responding to
224 </li>
225 <li>
226 <c>-i</c> Bind to the named interface. By default rarpd binds to the
227 default 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 the
244 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 will
254 appear as the root (<path>/</path>) 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 <path>/tftpboot</path> so that it is
270 owned by user 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 <path>/etc/conf.d/local.start</path> will need to be added as atftp has no
295 init.d, inetd or xinetd scripts of its own. If you want to use inetd or xinetd
296 for controlling the tftpd service, please see their respective man pages.
297 </p>
298
299 <p>
300 Below is an example entry for atftpd in <path>/etc/conf.d/local.start</path>;
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 explanation of the above rarpd options (as taken from the man page);
309 </p>
310
311 <ul>
312 <li>
313 <c>-v</c> Increase or set the logging level. No args will increase by one
314 the current value. Default is LOG_NOTICE, see syslog(3) for log level.
315 Current value range from 0 (LOG_EMERG) to 7 (LOG_DEBUG)
316 </li>
317 <li>
318 <c>--daemon</c> Run as a daemon. Do not use this option if atftpd is
319 started by 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; After the
343 net-misc/netkit-tftp and sys-apps/xinetd packages have been installed,
344 netkit-tftp will need to be configured. netkit-tftp needs to be run from
345 xinetd, however it does not provide example scripts of its own. A sample xinetd
346 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 explanation 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
412 <p>
413 First, install the tftp-hpa package using the following command;
414 </p>
415
416 <pre caption="Installing tftp-hpa">
417 # <i>emerge net-misc/tftp-hpa</i>
418 </pre>
419
420 <p>
421 tftp-hpa comes with an init.d and the accompanying conf.d configuration file.
422 Check to make sure that INIITFTPD_PATH and INITFTP_OPTS in
423 <path>/etc/conf.d/in.tftpd</path> match those below;
424 </p>
425
426 <pre caption="/etc/conf.d/in.tftpd">
427 INTFTPD_PATH="/tftpboot"
428 INTFTPD_OPTS="-s -v -l ${INTFTPD_PATH}"
429 </pre>
430
431 <p>
432 The tftp daemon can then be started via the init.d script;
433 </p>
434
435 <pre caption="Starting in.tftpd">
436 # <i>/etc/init.d/in.tftpd start</i>
437 </pre>
438
439 <p>
440 For more options, consult the section 8 man page on tftpd.
441 </p>
442
443 </body>
444 </section>
445 </chapter>
446
447 <chapter>
448 <title>Preparing a tftpboot image for use by a client</title>
449 <section>
450 <body>
451
452 <p>
453 Make sure you have an image you want to use for netbooting. For a sparc or
454 sparc64 netboot image, please check your local Gentoo distfiles mirror under
455 <path>experimental/sparc/tftpboot</path> for the appropriate image. We'll
456 assume you are planning to boot a sparc64 host using the
457 <path>gentoo-sparc64-1.4_rc4-20040102.tftpboot</path> image.
458 </p>
459
460 <p>
461 Once you have an image, copy the image into <path>/tftpboot</path>;
462 </p>
463
464 <pre caption="Copying the image">
465 # <i>cp gentoo-sparc64-1.4_rc4-20040102.tftpboot /tftpboot</i>
466 </pre>
467
468 <p>
469 Now, when the netboot client makes a tftp request, it looks for a file that is
470 the hexadecimal number of its current IP address, and on some platforms an
471 <path>.ARCH</path> suffix. The hexadecimal number should use <e>capital</e>
472 characters.
473 </p>
474
475 <p>
476 So for our example IP address, 10.0.1.15, let's look at its hexadecimal
477 equivalent:
478 </p>
479
480 <pre caption="Convert to hexadecimal">
481 # <i>printf "%.2x%.2x%.2x%.2x\n" 10 0 1 15</i>
482 </pre>
483
484 <pre caption="Example IP address">
485 decimal 10 0 1 15
486 hexadecimal 0A 00 01 0F
487 </pre>
488
489 <p>
490 So for the example sparc64 netboot client, it would look for a file named
491 0A00010F when it tftpboots.
492 </p>
493
494 <p>
495 On sparc however, the file would be 0A00010F.SUN4M, 0A00010F.SUN4C or
496 0A00010F.SUN4D depending on what type of sparc system.
497 </p>
498
499 <p>
500 Additionally, if you are really really lazy (like me), you can netboot the host
501 to get the filename the client is looking for from the netboot server logs.
502 </p>
503
504 <p>
505 Make sure that both the rarpd and tftpd daemon you've chosen are currently
506 running, then boot the host as described below in "Netbooting the client".
507 </p>
508
509 <p>
510 The client will appear to hang after the boot net command is issued. Then on
511 the netboot server, check the system logs for an entry for in.tftpd.
512 </p>
513
514 <p>
515 An example entry from a netboot server running sysklogd and tftp-hpa looks
516 like;
517 </p>
518
519 <pre caption="Log entry for netboot server">
520 Jan 3 22:48:59 stargazer in.tftpd[8368]: RRQ from 10.0.1.15 filename 0A00010F
521 </pre>
522
523 <p>
524 The filename is shown above after "filename" in the log entry, which in this
525 case is 0A00010F.
526 </p>
527
528 <p>
529 As a way to keep track of what netboot image you are using, and to allow
530 multiple machines to use the same netboot image, you can use a soft link to
531 create the file with the hexadecimal value. To create this using our sample
532 sparc64 host and the <path>gentoo-sparc64-1.4_rc4-20040102.tftpboot</path>, use
533 the following command;
534 </p>
535
536 <pre caption="Linking the image files">
537 # <i>/bin/ln -s /tftpboot/gentoo-sparc64-1.4_rc4-20040102.tftpboot \
538 /tftpboot/0A00010F</i>
539 </pre>
540
541 <p>
542 Now everything should be set for netbooting!
543 </p>
544
545 </body>
546 </section>
547 </chapter>
548
549 <chapter>
550 <title>Netbooting the client</title>
551
552 <section>
553 <body>
554
555 <p>
556 From OpenBoot PROM (OBP) on the SPARC, enter the command;
557 </p>
558
559 <pre caption="Booting OBP">
560 ok <i>boot net</i>
561 </pre>
562
563 <p>
564 Other methods for certain machines are:
565 </p>
566
567 <pre caption="Booting OBP, alternative">
568 ok <i>boot net-tpe</i>
569 </pre>
570
571 <note>
572 If your system doesn't present you with an OBP at boot time, you will either
573 need to press the Stop and A key, or send a break signal via serial console
574 before the system boots an OS. If your system cannot find an OS, it should
575 either try to boot via the network interface (which is what we want), or leave
576 you at an OBP prompt.
577 </note>
578
579 <p>
580 This will initiate the networking booting process. A constantly changing string
581 of hexadecimal digits should appear. When the image has finished loading, the
582 kernel will take over and start the OS booting process. In the case of our
583 sparc64 install image, you will be left at a shell prompt from which you can
584 begin the install process.
585 </p>
586
587 </body>
588 </section>
589 </chapter>
590
591 <chapter>
592 <title>Troubleshooting</title>
593 <section>
594 <body>
595
596 <p>
597 <b>Building the prerequisite software</b>
598 </p>
599
600 <p>
601 If the netboot server is a Gentoo/LINUX system and experiences problems
602 installing the rarpd and tftpd packages, please search
603 <uri>http://forums.gentoo.org</uri> and <uri>http://bugs.gentoo.org</uri> to
604 see if this problem has been encountered by anyone else. If it has not, or the
605 solutions found do not work, then please open a new bug at
606 <uri>http://bugs.gentoo.org</uri>
607 </p>
608
609 <p>
610 <b>I've issued the boot net command but it appears to hang.</b>
611 </p>
612
613 <p>
614 This is presumably because the file your system is trying to load from the
615 tftpboot server is not available. On a SPARC system, you would probably see the
616 following;
617 </p>
618
619 <pre caption="Booting appears to hang">
620 Rebooting with command: boot
621 Boot device: net File and args:
622 </pre>
623
624 <p>
625 Double check that the file the client needs does exist in
626 <path>/tftpboot</path>. You can confirm the filename it is requesting by
627 looking in the system logs. Also, once this file exists, the client will try to
628 load it. Sometimes, when the file is missing originally, it will freeze
629 downloading the file once it appears. To resolve this, just get back to an OBP
630 prompt, and issue the "boot net" command again. The host should then start
631 downloading the tftpboot image and boot the OS.
632 </p>
633
634 <p>
635 <b>I'm trying to netboot, but all I see are "Timeout waiting for ARP/RARP
636 packet" messages.</b>
637 </p>
638
639 <p>
640 This could be due to a few different problems;
641 </p>
642
643 <ol>
644 <li>
645 Make sure the entry in <path>/etc/ethers</path> exists for the client in
646 question. If the MAC address is incorrect and/or the netboot server cannot
647 resolve the hostname for the client, it cannot respond with the needed
648 information.
649 </li>
650 <li>
651 Verify that the network hub or switch the netboot server and client are
652 connected to allow RARP traffic to flow freely. If the client's request
653 cannot reach the server, or vice versa, the host will be unable to
654 continue.
655 </li>
656 <li>
657 No one is responding to the RARPD request because no services are
658 listening. Verify that the rarpd service is up and running.
659 </li>
660 <li>
661 The client does not think its NIC has a link to the network hub/switch it
662 is plugged into. Check to see if the NIC and the port on the network hub or
663 switch has a link light. If the link light is on, check to see what the
664 setting of tpe-link-test? is in OBP with the command; <c>printenv
665 tpe-link-test?</c>. You should receive something like <path>tpe-link-test?
666 false true</path>. The first column represents the parameter name, the
667 second column shows the current value for the the parameter, and the third
668 column shows the default value for the parameter. In the example above, we
669 can see that the current value is false, which means that the client is not
670 checking to see if the client and network hub or switch can establish a
671 link before issuing its RARP request. Often times this can cause the
672 problem.
673 </li>
674 </ol>
675
676 <p>
677 To change the value of tpe-link-test? from an OBP prompt, issue the following
678 command;
679 </p>
680
681 <pre caption="Changing tpe-link-test value">
682 ok <i>setenv tpe-link-test? true</i>
683 tpe-link-test? = true
684 </pre>
685
686 <p>
687 This shows the value of tpe-link-test? is now true. Try netbooting the client
688 again.
689 </p>
690
691 </body>
692 </section>
693 </chapter>
694 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20