/[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.15 - (show annotations) (download) (as text)
Mon Dec 9 10:52:11 2013 UTC (10 months, 2 weeks ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.14: +2 -2 lines
File MIME type: application/xml
Moved to https://wiki.gentoo.org/wiki/Sparc/Netboot

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.14 2012/07/08 23:09:11 nightmorph Exp $ -->
4
5 <guide disclaimer="obsolete" redirect="https://wiki.gentoo.org/wiki/Sparc/Netboot">
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>3</version>
25 <date>2012-07-08</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 two options for a TFTP daemon, <c>net-ftp/atftp</c> and
202 <c>net-ftp/tftp-hpa</c>. You only need to install one of the TFTP daemons for
203 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 tftp-hpa Daemon</title>
293 <body>
294
295 <p>
296 First, install the <c>tftp-hpa</c> package:
297 </p>
298
299 <pre caption="Installing tftp-hpa">
300 # <i>emerge tftp-hpa</i>
301 </pre>
302
303 <p>
304 <c>tftp-hpa</c> comes with an <path>init.d</path> and the accompanying
305 <path>conf.d</path> configuration file. Check to make sure that INTFTPD_PATH
306 and INTFTP_OPTS in <path>/etc/conf.d/in.tftpd</path> match those below:
307 </p>
308
309 <pre caption="/etc/conf.d/in.tftpd">
310 INTFTPD_PATH="/tftpboot"
311 INTFTPD_OPTS="-s -v -l ${INTFTPD_PATH}"
312 </pre>
313
314 <p>
315 The TFTP daemon can then be started via the <path>init.d</path> script:
316 </p>
317
318 <pre caption="Starting in.tftpd">
319 # <i>/etc/init.d/in.tftpd start</i>
320 </pre>
321
322 <p>
323 For more options, consult <c>man 8 tftpd</c>.
324 </p>
325
326 </body>
327 </section>
328 </chapter>
329
330 <chapter>
331 <title>Preparing a tftpboot image for use by a client</title>
332 <section>
333 <body>
334
335 <p>
336 Make sure you have an image you want to use for netbooting. Please check your
337 <uri link="/main/en/mirrors.xml">local</uri> Gentoo <uri
338 link="http://distfiles.gentoo.org/experimental/sparc/tftpboot/sparc64/">distfiles
339 mirror</uri> for the appropriate image. We'll assume you are planning to boot
340 using the <path>gentoo-sparc64-20100128.tftpboot</path> image.
341 </p>
342
343 <p>
344 Once you have an image, copy the image into <path>/tftpboot</path>:
345 </p>
346
347 <pre caption="Copying the image">
348 # <i>cp gentoo-sparc64-20100128.tftpboot /tftpboot</i>
349 # <i>chmod 644 /tftpboot/gentoo-sparc64-20100128.tftpboot</i>
350 </pre>
351
352 <p>
353 Now, when the netboot client makes a TFTP request, it looks for a file that is
354 the hexadecimal number of its current IP address, and on some platforms an
355 <path>.ARCH</path> suffix. The hexadecimal number should use <e>capital</e>
356 characters.
357 </p>
358
359 <p>
360 So for our example IP address, 10.0.1.15, let's look at its hexadecimal
361 equivalent:
362 </p>
363
364 <pre caption="Convert to hexadecimal">
365 # <i>printf "%.2X%.2X%.2X%.2X\n" 10 0 1 15</i>
366 </pre>
367
368 <pre caption="Example IP address">
369 decimal 10 0 1 15
370 hexadecimal 0A 00 01 0F
371 </pre>
372
373 <p>
374 So for the example netboot client, it would look for a file named
375 <path>0A00010F</path> when it tftpboots.
376 </p>
377
378 <p>
379 Iif you are really, really lazy (like me), you can netboot the host to get the
380 filename the client is looking for from the netboot server logs.
381 </p>
382
383 <p>
384 Make sure that both the <c>rarpd</c> and TFTP daemon you've chosen are currently
385 running, then boot the host as described below in <uri
386 link="#netbootingclient">Netbooting the client</uri>.
387 </p>
388
389 <p>
390 The client will appear to hang after the boot net command is issued. Then on
391 the netboot server, check the system logs for an entry for <c>in.tftpd</c>.
392 </p>
393
394 <p>
395 An example entry from a netboot server running <c>sysklogd</c> and
396 <c>tftp-hpa</c> looks like:
397 </p>
398
399 <pre caption="Log entry for netboot server">
400 Jan 3 22:48:59 stargazer in.tftpd[8368]: RRQ from 10.0.1.15 filename 0A00010F
401 </pre>
402
403 <p>
404 The filename is shown above after "filename" in the log entry, which in this
405 case is <path>0A00010F</path>.
406 </p>
407
408 <p>
409 As a way to keep track of what netboot image you are using, and to allow
410 multiple machines to use the same netboot image, you can use a soft link to
411 create the file with the hexadecimal value. To create this using our sample
412 sparc64 host and the <path>gentoo-sparc64-20100128.tftpboot</path>, use
413 the following command:
414 </p>
415
416 <pre caption="Linking the image files">
417 # <i>/bin/ln -s /tftpboot/gentoo-sparc64-20100128.tftpboot \
418 /tftpboot/0A00010F</i>
419 </pre>
420
421 <p>
422 Now everything should be set for netbooting!
423 </p>
424
425 </body>
426 </section>
427 </chapter>
428
429 <chapter id="netbootingclient">
430 <title>Netbooting the client</title>
431 <section>
432 <body>
433
434 <p>
435 From OpenBoot PROM (OBP) on the SPARC, enter the command;
436 </p>
437
438 <pre caption="Booting OBP">
439 ok <i>boot net</i>
440 </pre>
441
442 <p>
443 Other methods for certain machines are:
444 </p>
445
446 <pre caption="Booting OBP, alternative">
447 ok <i>boot net-tpe</i>
448 </pre>
449
450 <note>
451 If your system doesn't present you with an OBP at boot time, you will either
452 need to press the Stop and A key, or send a break signal via serial console
453 before the system boots an OS. If your system cannot find an OS, it should
454 either try to boot via the network interface (which is what we want), or leave
455 you at an OBP prompt.
456 </note>
457
458 <p>
459 This will initiate the networking booting process. A constantly changing string
460 of hexadecimal digits should appear. When the image has finished loading, the
461 kernel will take over and start the OS booting process. In the case of our
462 sparc64 install image, you will be left at a shell prompt from which you can
463 begin the install process.
464 </p>
465
466 </body>
467 </section>
468 </chapter>
469
470 <chapter>
471 <title>Troubleshooting</title>
472 <section>
473 <body>
474
475 <p>
476 <b>Building the prerequisite software</b>
477 </p>
478
479 <p>
480 If the netboot server is a Gentoo Linux system and experiences problems after
481 installing the rarpd and tftpd packages, please search the <uri
482 link="http://forums.gentoo.org">Gentoo Forums</uri> and <uri
483 link="http://bugs.gentoo.org">Gentoo Bugzilla</uri> to see if this problem has
484 been encountered by anyone else. If it has not, or the solutions found do not
485 work, then please open a new bug.
486 </p>
487
488 <p>
489 <b>I've issued the boot net command but it appears to hang.</b>
490 </p>
491
492 <p>
493 This is presumably because the file your system is trying to load from the
494 tftpboot server is not available. On a SPARC system, you would probably see the
495 following:
496 </p>
497
498 <pre caption="Booting appears to hang">
499 Rebooting with command: boot
500 Boot device: net File and args:
501 </pre>
502
503 <p>
504 Double check that the file the client needs does exist in
505 <path>/tftpboot</path>. You can confirm the filename it is requesting by
506 looking in the system logs. Also, once this file exists, the client will try to
507 load it. Sometimes, when the file is missing originally, it will freeze
508 downloading the file once it appears. To resolve this, just get back to an OBP
509 prompt, and issue the "boot net" command again. The host should then start
510 downloading the tftpboot image and boot the OS.
511 </p>
512
513 <p>
514 <b>I'm trying to netboot, but all I see are "Timeout waiting for ARP/RARP
515 packet" messages.</b>
516 </p>
517
518 <p>
519 This could be due to a few different problems;
520 </p>
521
522 <ol>
523 <li>
524 Make sure the entry in <path>/etc/ethers</path> exists for the client in
525 question. If the MAC address is incorrect and/or the netboot server cannot
526 resolve the hostname for the client, it cannot respond with the needed
527 information.
528 </li>
529 <li>
530 Verify that the network hub or switch the netboot server and client are
531 connected to allow RARP traffic to flow freely. If the client's request
532 cannot reach the server, or vice versa, the host will be unable to
533 continue.
534 </li>
535 <li>
536 No one is responding to the RARPD request because no services are
537 listening. Verify that the rarpd service is up and running.
538 </li>
539 <li>
540 The client does not think its NIC has a link to the network hub/switch it
541 is plugged into. Check to see if the NIC and the port on the network hub or
542 switch has a link light. If the link light is on, check to see what the
543 setting of tpe-link-test? is in OBP with the command; <c>printenv
544 tpe-link-test?</c>. You should receive something like <path>tpe-link-test?
545 false true</path>. The first column represents the parameter name, the
546 second column shows the current value for the the parameter, and the third
547 column shows the default value for the parameter. In the example above, we
548 can see that the current value is false, which means that the client is not
549 checking to see if the client and network hub or switch can establish a
550 link before issuing its RARP request. Often times this can cause the
551 problem.
552 </li>
553 </ol>
554
555 <p>
556 To change the value of tpe-link-test? from an OBP prompt, issue the following
557 command:
558 </p>
559
560 <pre caption="Changing tpe-link-test value">
561 ok <i>setenv tpe-link-test? true</i>
562 tpe-link-test? = true
563 </pre>
564
565 <p>
566 This shows the value of tpe-link-test? is now true. Try netbooting the client
567 again.
568 </p>
569
570 </body>
571 </section>
572 </chapter>
573 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20