/[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.13 - (show annotations) (download) (as text)
Tue Oct 5 21:54:55 2010 UTC (4 years, 2 months ago) by nightmorph
Branch: MAIN
Changes since 1.12: +22 -70 lines
File MIME type: application/xml
update package category moves, removals, etc. from an email sent to me

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

  ViewVC Help
Powered by ViewVC 1.1.20