doc/en/gentoo-sparc-netboot-howto.xml

<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-sparc-netboot-howto.xml,v 1.13 2010/10/05 21:54:55 nightmorph Exp $ -->

<guide>
<title>Gentoo Linux based Netboot HOWTO</title>

<author title="SPARC Developer">
  <mail link="weeve"/>
</author>
<author title="Editor">
  <mail link="nightmorph"/>
</author>

<abstract>
Guide for setting up a netboot server for use with the Gentoo/SPARC netboot
installation images.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>3</version>
<date>2012-07-08</date>

<chapter>
<title>Introduction</title>
<section>
<body>

<note>
This howto is currently very SPARC-centric and expecting that you will be
setting up your netboot server on an existing Gentoo Linux machine.
</note>

<p>
This document will describe how to setup a network booting environment for a
Sun Microsystems SPARC or UltraSPARC based computer. The document assumes that
you have an existing Gentoo Linux computer available to act as the netboot
server.
</p>

<p>
Both the netboot server and netboot client will need to be on the same network
subnet, as the ARP protocol is typically not forwarded across different network
subnets.
</p>

<p>
A generic overview of what happens during the netboot process is as follows;
</p>

<ol>
  <li>
    Client machine sends out a reverse ARP (RARP) request to get an IP address
  </li>
  <li>A server machine returns a response to the client with the IP address</li>
  <li>
    The client then attempts to download a boot image from the RARP server
    using the TFTP protocol
  </li>
  <li>Once the image is downloaded, the netboot client then boots the image</li>
</ol>

<p>
Based on this overview, we will need to install software for a reverse ARP
daemon and a TFTP daemon.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Software Installation And Configuration</title>
<section>
<title>The Reverse ARP Daemon</title>
<body>

<p>
A reverse ARP daemon is already installed on your system; it's part of the
<c>net-misc/iputils</c> package
</p>

<p>
<b>Setting up common rarpd elements</b>: <path>/etc/ethers</path>
</p>

<p>
You will need to setup the <path>/etc/ethers</path> file. This file indicates
which hosts <c>rarpd</c> should respond to when a request is seen, and what
address to reply with.
</p>

<p>
The format of <path>/etc/ethers</path> is the MAC address of the NIC the
machine will be netbooting and its hostname. Whitespace delimits the MAC
address from the hostname, and each entry should have its own line. The
following example is for a host named sparc-netboot.gentoo.org:
</p>

<pre caption="Example /etc/ethers">
08:00:20:77:1f:3e  sparc-netboot.gentoo.org
</pre>

<note>
If a given hexadecimal number in the MAC address starts or is 0, you can chose
to omit the first 0 (i.e. 08:00:20:77:1f:3e becomes 8:0:20:77:1f:3e).
</note>

<p>
If you desire to add additional hosts to <path>/etc/ethers</path>, you do not
need to restart the <c>rarpd</c> services as the file is checked each time a
request is received.
</p>

<p>
<b>Resolving hostnames</b>: <path>/etc/hosts</path>
</p>

<p>
Since each entry in <path>/etc/ethers</path> has a hostname, the netboot server
needs to be able to resolve the hostname into its IP address. This can be done
two ways, <path>/etc/hosts</path> or the nameserver the netboot server uses.
</p>

<p>
An <path>/etc/hosts</path> entry for resolving a hostname will look very
similar to the one that probably exists from when you installed Gentoo on the
netboot server. For our example host, sparc-netboot.gentoo.org, we'll assume
that it has an IP address of 10.0.1.15. So the <path>/etc/hosts</path> entry
would look like;
</p>

<pre caption="/etc/hosts">
10.0.1.15  sparc-netboot.gentoo.org
</pre>


<note>
Depending on the environment, you may need to consult your network
administrator to get an appropriate IP address or addresses to netboot the host
with.
</note>

<p>
If you use a nameserver, then the DNS server administrator will need to add a
record for the hostname, in our example sparc-netboot.gentoo.org, to point to
the appropriate IP address. Please consult your DNS server administrator and/or
the documentation for the DNS server's DNS software for how to add the entry.
</p>

<note>
If both <path>/etc/hosts</path> and the nameserver have an entry for the host
to be netbooted, <path>/etc/hosts</path> will be used first (granted the order
of <path>/etc/nsswitch.conf</path> has not been changed from the default).
</note>

<p>
<b>Setting up rarpd</b>
</p>

<p>
First, we will need to determine the options to use for <c>rarpd</c>. While
there are more options than we'll cover here, these options should get you
started As there is currently no <path>init.d</path> script for <c>rarpd</c>, an
entry will need to be added to <path>/etc/conf.d/local.start</path> if you want
to enable <c>rarpd</c> services at boot time. A sample entry is as follows:
</p>

<pre caption="/etc/conf.d/local.start">
/usr/sbin/rarpd -v -e eth0
</pre>

<p>
An explanation of the above <c>rarpd</c> options (as taken from the man page):
</p>

<ul>
  <li><c>-v</c> Be verbose</li>
  <li>
    <c>-e</c> Do not check for the presence of a boot image, reply if MAC
    address resolves to a valid IP address using <path>/etc/ethers</path>
    database and DNS
  </li>
  <li>eth0 represents the interface <c>rarpd</c> should bind to</li>
</ul>

<p>
For more options, consult <c>man 8 rarpd</c>.
</p>

</body>
</section>
<section>
<title>The tftpd Daemon</title>
<body>

<p>
Here there are two options for a TFTP daemon, <c>net-ftp/atftp</c> and
<c>net-ftp/tftp-hpa</c>. You only need to install one of the TFTP daemons for
proper operation.
</p>

<p>
<b>Setting up common tftpd elements</b>
</p>

<p>
Each TFTP daemon will need a directory from which to serve files to tftp
clients. The directory we will use for this howto will be
<path>/tftpboot</path>. This will appear as the root (<path>/</path>) directory
to the clients when requests are received. Additionally, we'll setup the system
to run the TFTP daemon with the user and group <c>nobody</c>.
</p>

<p>
If the directory you have chosen does not currently exist, it will need to be
created with the <c>mkdir</c> command. The command for the example
<path>/tftpboot</path> is:
</p>

<pre caption="Creating /tftpboot">
# <i>/bin/mkdir /tftpboot</i>
</pre>

<p>
Then we will need to change the owner of <path>/tftpboot</path> so that it is
owned by user nobody and group <c>nobody</c>:
</p>

<pre caption="Changing ownership">
# <i>chown nobody:nobody /tftpboot</i>
</pre>

</body>
</section>
<section>
<title>The atftp Daemon</title>
<body>

<p>
First, install the <c>atftp</c> package as follows;
</p>

<pre caption="Installing atftp">
# <i>emerge atftp</i>
</pre>

<p>
After the <c>atftp</c> package has been installed, it will need to be
configured. If tftpd services are desired at boot time, an entry to
<path>/etc/conf.d/local.start</path> will need to be added as <c>atftp</c> has
no <path>init.d</path>, <c>inetd</c> or <c>xinetd</c> scripts of its own. If you
want to use <c>inetd</c> or <c>xinetd</c> for controlling the tftpd service,
please see their respective man pages.
</p>

<p>
Below is an example entry for <c>atftpd</c> in
<path>/etc/conf.d/local.start</path>.
</p>

<pre caption="/etc/conf.d/local.start">
/usr/sbin/in.tftpd -v --daemon /tftpboot
</pre>

<p>
An explanation of the above options (as taken from the man page);
</p>

<ul>
  <li>
    <c>-v</c> Increase or set the logging level. No args will increase by one
    the current value. Default is LOG_NOTICE, see syslog(3) for log level.
    Current value range from 0 (LOG_EMERG) to 7 (LOG_DEBUG)
  </li>
  <li>
    <c>--daemon</c> Run as a daemon. Do not use this option if atftpd is
    started by inetd.
  </li>
</ul>

<p>
For more options, consult <c>man 8 atftpd</c>.
</p>

</body>
</section>
<section>
<title>The tftp-hpa Daemon</title>
<body>

<p>
First, install the <c>tftp-hpa</c> package:
</p>

<pre caption="Installing tftp-hpa">
# <i>emerge tftp-hpa</i>
</pre>

<p>
<c>tftp-hpa</c> comes with an <path>init.d</path> and the accompanying
<path>conf.d</path> configuration file. Check to make sure that INTFTPD_PATH
and INTFTP_OPTS in <path>/etc/conf.d/in.tftpd</path> match those below:
</p>

<pre caption="/etc/conf.d/in.tftpd">
INTFTPD_PATH="/tftpboot"
INTFTPD_OPTS="-s -v -l ${INTFTPD_PATH}"
</pre>

<p>
The TFTP daemon can then be started via the <path>init.d</path> script:
</p>

<pre caption="Starting in.tftpd">
# <i>/etc/init.d/in.tftpd start</i>
</pre>

<p>
For more options, consult <c>man 8 tftpd</c>.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Preparing a tftpboot image for use by a client</title>
<section>
<body>

<p>
Make sure you have an image you want to use for netbooting. Please check your
<uri link="/main/en/mirrors.xml">local</uri> Gentoo <uri
link="http://distfiles.gentoo.org/experimental/sparc/tftpboot/sparc64/">distfiles
mirror</uri> for the appropriate image. We'll assume you are planning to boot
using the <path>gentoo-sparc64-20100128.tftpboot</path> image.
</p>

<p>
Once you have an image, copy the image into <path>/tftpboot</path>:
</p>

<pre caption="Copying the image">
# <i>cp gentoo-sparc64-20100128.tftpboot /tftpboot</i>
# <i>chmod 644 /tftpboot/gentoo-sparc64-20100128.tftpboot</i>
</pre>

<p>
Now, when the netboot client makes a TFTP request, it looks for a file that is
the hexadecimal number of its current IP address, and on some platforms an
<path>.ARCH</path> suffix. The hexadecimal number should use <e>capital</e>
characters.
</p>

<p>
So for our example IP address, 10.0.1.15, let's look at its hexadecimal
equivalent:
</p>

<pre caption="Convert to hexadecimal">
# <i>printf "%.2X%.2X%.2X%.2X\n" 10 0 1 15</i>
</pre>

<pre caption="Example IP address">
decimal       10  0   1   15
hexadecimal   0A  00  01  0F
</pre>

<p>
So for the example netboot client, it would look for a file named
<path>0A00010F</path> when it tftpboots.
</p>

<p>
Iif you are really, really lazy (like me), you can netboot the host to get the
filename the client is looking for from the netboot server logs.
</p>

<p>
Make sure that both the <c>rarpd</c> and TFTP daemon you've chosen are currently
running, then boot the host as described below in <uri
link="#netbootingclient">Netbooting the client</uri>.
</p>

<p>
The client will appear to hang after the boot net command is issued. Then on
the netboot server, check the system logs for an entry for <c>in.tftpd</c>.
</p>

<p>
An example entry from a netboot server running <c>sysklogd</c> and
<c>tftp-hpa</c> looks like:
</p>

<pre caption="Log entry for netboot server">
Jan  3 22:48:59 stargazer in.tftpd[8368]: RRQ from 10.0.1.15 filename 0A00010F
</pre>

<p>
The filename is shown above after "filename" in the log entry, which in this
case is <path>0A00010F</path>.
</p>

<p>
As a way to keep track of what netboot image you are using, and to allow
multiple machines to use the same netboot image, you can use a soft link to
create the file with the hexadecimal value. To create this using our sample
sparc64 host and the <path>gentoo-sparc64-20100128.tftpboot</path>, use
the following command:
</p>

<pre caption="Linking the image files">
# <i>/bin/ln -s /tftpboot/gentoo-sparc64-20100128.tftpboot \
/tftpboot/0A00010F</i>
</pre>

<p>
Now everything should be set for netbooting!
</p>

</body>
</section>
</chapter>

<chapter id="netbootingclient">
<title>Netbooting the client</title>
<section>
<body>

<p>
From OpenBoot PROM (OBP) on the SPARC, enter the command;
</p>

<pre caption="Booting OBP">
ok <i>boot net</i>
</pre>

<p>
Other methods for certain machines are:
</p>

<pre caption="Booting OBP, alternative">
ok <i>boot net-tpe</i>
</pre>

<note>
If your system doesn't present you with an OBP at boot time, you will either
need to press the Stop and A key, or send a break signal via serial console
before the system boots an OS. If your system cannot find an OS, it should
either try to boot via the network interface (which is what we want), or leave
you at an OBP prompt.
</note>

<p>
This will initiate the networking booting process. A constantly changing string
of hexadecimal digits should appear. When the image has finished loading, the
kernel will take over and start the OS booting process. In the case of our
sparc64 install image, you will be left at a shell prompt from which you can
begin the install process.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Troubleshooting</title>
<section>
<body>

<p>
<b>Building the prerequisite software</b>
</p>

<p>
If the netboot server is a Gentoo Linux system and experiences problems after
installing the rarpd and tftpd packages, please search the <uri
link="http://forums.gentoo.org">Gentoo Forums</uri> and <uri
link="http://bugs.gentoo.org">Gentoo Bugzilla</uri> to see if this problem has
been encountered by anyone else. If it has not, or the solutions found do not
work, then please open a new bug.
</p>

<p>
<b>I've issued the boot net command but it appears to hang.</b>
</p>

<p>
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:
</p>

<pre caption="Booting appears to hang">
Rebooting with command: boot
Boot device: net  File and args:
</pre>

<p>
Double check that the file the client needs does exist in
<path>/tftpboot</path>. You can confirm the filename it is requesting by
looking in the system logs. Also, once this file exists, the client will try to
load it. Sometimes, when the file is missing originally, it will freeze
downloading the file once it appears. To resolve this, just get back to an OBP
prompt, and issue the "boot net" command again. The host should then start
downloading the tftpboot image and boot the OS.
</p>

<p>
<b>I'm trying to netboot, but all I see are "Timeout waiting for ARP/RARP
packet" messages.</b>
</p>

<p>
This could be due to a few different problems;
</p>

<ol>
  <li>
    Make sure the entry in <path>/etc/ethers</path> exists for the client in
    question. If the MAC address is incorrect and/or the netboot server cannot
    resolve the hostname for the client, it cannot respond with the needed
    information.
  </li>
  <li>
    Verify that the network hub or switch the netboot server and client are
    connected to allow RARP traffic to flow freely. If the client's request
    cannot reach the server, or vice versa, the host will be unable to
    continue.
  </li>
  <li>
    No one is responding to the RARPD request because no services are
    listening. Verify that the rarpd service is up and running.
  </li>
  <li>
    The client does not think its NIC has a link to the network hub/switch it
    is plugged into. Check to see if the NIC and the port on the network hub or
    switch has a link light. If the link light is on, check to see what the
    setting of tpe-link-test? is in OBP with the command; <c>printenv
    tpe-link-test?</c>. You should receive something like <path>tpe-link-test?
    false true</path>. The first column represents the parameter name, the
    second column shows the current value for the the parameter, and the third
    column shows the default value for the parameter. In the example above, we
    can see that the current value is false, which means that the client is not
    checking to see if the client and network hub or switch can establish a
    link before issuing its RARP request. Often times this can cause the
    problem.
  </li>
</ol>

<p>
To change the value of tpe-link-test? from an OBP prompt, issue the following
command:
</p>

<pre caption="Changing tpe-link-test value">
ok <i>setenv tpe-link-test? true</i>
tpe-link-test? =      true
</pre>

<p>
This shows the value of tpe-link-test? is now true. Try netbooting the client
again.
</p>

</body>
</section>
</chapter>
</guide>
1	swift	1.1	<?xml version='1.0' encoding="UTF-8"?>
2			<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3	nightmorph	1.14	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-sparc-netboot-howto.xml,v 1.13 2010/10/05 21:54:55 nightmorph Exp $ -->
4	neysx	1.8
5	nightmorph	1.11	<guide>
6	swift	1.1	<title>Gentoo Linux based Netboot HOWTO</title>
7	neysx	1.8
8	swift	1.1	<author title="SPARC Developer">
9	nightmorph	1.11	<mail link="weeve"/>
10	swift	1.1	</author>
11	nightmorph	1.12	<author title="Editor">
12			<mail link="nightmorph"/>
13			</author>
14	neysx	1.8
15	swift	1.1	<abstract>
16	neysx	1.8	Guide for setting up a netboot server for use with the Gentoo/SPARC netboot
17			installation images.
18	swift	1.1	</abstract>
19	neysx	1.8
20	swift	1.1	<!-- The content of this document is licensed under the CC-BY-SA license -->
21	neysx	1.7	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
22	swift	1.1	<license/>
23
24	nightmorph	1.14	<version>3</version>
25			<date>2012-07-08</date>
26	swift	1.1
27			<chapter>
28			<title>Introduction</title>
29			<section>
30			<body>
31
32			<note>
33	neysx	1.8	This howto is currently very SPARC-centric and expecting that you will be
34	swift	1.1	setting up your netboot server on an existing Gentoo Linux machine.
35			</note>
36
37			<p>
38	neysx	1.8	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	swift	1.1	you have an existing Gentoo Linux computer available to act as the netboot
41			server.
42			</p>
43
44			<p>
45	neysx	1.8	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	swift	1.1	</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	neysx	1.8	Client machine sends out a reverse ARP (RARP) request to get an IP address
57	swift	1.1	</li>
58	neysx	1.8	<li>A server machine returns a response to the client with the IP address</li>
59	swift	1.1	<li>
60	neysx	1.8	The client then attempts to download a boot image from the RARP server
61	nightmorph	1.12	using the TFTP protocol
62	swift	1.1	</li>
63	neysx	1.8	<li>Once the image is downloaded, the netboot client then boots the image</li>
64	swift	1.1	</ol>
65
66			<p>
67			Based on this overview, we will need to install software for a reverse ARP
68	nightmorph	1.12	daemon and a TFTP daemon.
69	swift	1.1	</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	nightmorph	1.13	A reverse ARP daemon is already installed on your system; it's part of the
83			<c>net-misc/iputils</c> package
84	swift	1.1	</p>
85
86			<p>
87			<b>Setting up common rarpd elements</b>: <path>/etc/ethers</path>
88			</p>
89
90			<p>
91	nightmorph	1.13	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	swift	1.1	</p>
95
96			<p>
97	swift	1.10	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	yoswink	1.9	following example is for a host named sparc-netboot.gentoo.org:
101	swift	1.1	</p>
102
103			<pre caption="Example /etc/ethers">
104	neysx	1.8	08:00:20:77:1f:3e sparc-netboot.gentoo.org
105	swift	1.1	</pre>
106
107			<note>
108	neysx	1.8	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	swift	1.1	</note>
111
112			<p>
113	neysx	1.8	If you desire to add additional hosts to <path>/etc/ethers</path>, you do not
114	nightmorph	1.12	need to restart the <c>rarpd</c> services as the file is checked each time a
115			request is received.
116	swift	1.1	</p>
117
118			<p>
119			<b>Resolving hostnames</b>: <path>/etc/hosts</path>
120			</p>
121
122			<p>
123	neysx	1.8	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	swift	1.1	</p>
127
128			<p>
129	neysx	1.8	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	swift	1.1	</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	neysx	1.8	administrator to get an appropriate IP address or addresses to netboot the host
144			with.
145	swift	1.1	</note>
146
147			<p>
148	neysx	1.8	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	swift	1.1	</p>
153
154			<note>
155	neysx	1.8	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	swift	1.1	</note>
159
160			<p>
161	nightmorph	1.13	<b>Setting up rarpd</b>
162	swift	1.1	</p>
163
164	neysx	1.8	<p>
165	nightmorph	1.12	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	nightmorph	1.13	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	swift	1.1	</p>
171
172			<pre caption="/etc/conf.d/local.start">
173			/usr/sbin/rarpd -v -e eth0
174			</pre>
175
176			<p>
177	nightmorph	1.12	An explanation of the above <c>rarpd</c> options (as taken from the man page):
178	swift	1.1	</p>
179
180			<ul>
181	nightmorph	1.12	<li><c>-v</c> Be verbose</li>
182	swift	1.1	<li>
183	nightmorph	1.12	<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	swift	1.1	</li>
187	nightmorph	1.12	<li>eth0 represents the interface <c>rarpd</c> should bind to</li>
188	swift	1.1	</ul>
189
190			<p>
191	nightmorph	1.12	For more options, consult <c>man 8 rarpd</c>.
192	swift	1.1	</p>
193
194			</body>
195			</section>
196			<section>
197			<title>The tftpd Daemon</title>
198			<body>
199
200			<p>
201	nightmorph	1.14	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	swift	1.1	</p>
205
206			<p>
207			<b>Setting up common tftpd elements</b>
208			</p>
209
210			<p>
211	nightmorph	1.12	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	swift	1.1	</p>
217
218			<p>
219			If the directory you have chosen does not currently exist, it will need to be
220	nightmorph	1.12	created with the <c>mkdir</c> command. The command for the example
221			<path>/tftpboot</path> is:
222	swift	1.1	</p>
223
224			<pre caption="Creating /tftpboot">
225			# <i>/bin/mkdir /tftpboot</i>
226			</pre>
227
228			<p>
229	neysx	1.8	Then we will need to change the owner of <path>/tftpboot</path> so that it is
230	nightmorph	1.12	owned by user nobody and group <c>nobody</c>:
231	swift	1.1	</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	nightmorph	1.13	First, install the <c>atftp</c> package as follows;
245	swift	1.1	</p>
246
247			<pre caption="Installing atftp">
248	nightmorph	1.13	# <i>emerge atftp</i>
249	swift	1.1	</pre>
250
251			<p>
252	nightmorph	1.13	After the <c>atftp</c> package has been installed, it will need to be
253	neysx	1.8	configured. If tftpd services are desired at boot time, an entry to
254	nightmorph	1.12	<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	swift	1.1	</p>
259
260			<p>
261	nightmorph	1.12	Below is an example entry for <c>atftpd</c> in
262			<path>/etc/conf.d/local.start</path>.
263	swift	1.1	</p>
264
265			<pre caption="/etc/conf.d/local.start">
266			/usr/sbin/in.tftpd -v --daemon /tftpboot
267			</pre>
268
269			<p>
270	nightmorph	1.13	An explanation of the above options (as taken from the man page);
271	swift	1.1	</p>
272
273			<ul>
274			<li>
275	neysx	1.8	<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	swift	1.1	</li>
279			<li>
280	neysx	1.8	<c>--daemon</c> Run as a daemon. Do not use this option if atftpd is
281			started by inetd.
282	swift	1.1	</li>
283			</ul>
284
285			<p>
286	nightmorph	1.12	For more options, consult <c>man 8 atftpd</c>.
287	swift	1.1	</p>
288
289			</body>
290			</section>
291			<section>
292			<title>The tftp-hpa Daemon</title>
293			<body>
294	neysx	1.8
295	swift	1.1	<p>
296	nightmorph	1.12	First, install the <c>tftp-hpa</c> package:
297	swift	1.1	</p>
298
299			<pre caption="Installing tftp-hpa">
300	nightmorph	1.13	# <i>emerge tftp-hpa</i>
301	swift	1.1	</pre>
302
303			<p>
304	nightmorph	1.12	<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	swift	1.1	</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	nightmorph	1.12	The TFTP daemon can then be started via the <path>init.d</path> script:
316	swift	1.1	</p>
317
318			<pre caption="Starting in.tftpd">
319			# <i>/etc/init.d/in.tftpd start</i>
320			</pre>
321
322			<p>
323	nightmorph	1.12	For more options, consult <c>man 8 tftpd</c>.
324	swift	1.1	</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	nightmorph	1.12	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	swift	1.1	</p>
342
343			<p>
344	nightmorph	1.12	Once you have an image, copy the image into <path>/tftpboot</path>:
345	swift	1.1	</p>
346
347			<pre caption="Copying the image">
348	nightmorph	1.12	# <i>cp gentoo-sparc64-20100128.tftpboot /tftpboot</i>
349			# <i>chmod 644 /tftpboot/gentoo-sparc64-20100128.tftpboot</i>
350	swift	1.1	</pre>
351
352			<p>
353	nightmorph	1.12	Now, when the netboot client makes a TFTP request, it looks for a file that is
354	neysx	1.8	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	swift	1.1	</p>
358
359			<p>
360	nightmorph	1.11	So for our example IP address, 10.0.1.15, let's look at its hexadecimal
361			equivalent:
362	swift	1.1	</p>
363
364	nightmorph	1.11	<pre caption="Convert to hexadecimal">
365	nightmorph	1.12	# <i>printf "%.2X%.2X%.2X%.2X\n" 10 0 1 15</i>
366	nightmorph	1.11	</pre>
367	swift	1.1
368			<pre caption="Example IP address">
369			decimal 10 0 1 15
370	neysx	1.8	hexadecimal 0A 00 01 0F
371	swift	1.1	</pre>
372
373			<p>
374	nightmorph	1.12	So for the example netboot client, it would look for a file named
375			<path>0A00010F</path> when it tftpboots.
376	swift	1.1	</p>
377
378			<p>
379	nightmorph	1.12	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	swift	1.1	</p>
382
383			<p>
384	nightmorph	1.12	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	swift	1.1	</p>
388
389			<p>
390	neysx	1.8	The client will appear to hang after the boot net command is issued. Then on
391	nightmorph	1.12	the netboot server, check the system logs for an entry for <c>in.tftpd</c>.
392	swift	1.1	</p>
393
394			<p>
395	nightmorph	1.12	An example entry from a netboot server running <c>sysklogd</c> and
396			<c>tftp-hpa</c> looks like:
397	swift	1.1	</p>
398
399			<pre caption="Log entry for netboot server">
400	swift	1.3	Jan 3 22:48:59 stargazer in.tftpd[8368]: RRQ from 10.0.1.15 filename 0A00010F
401	swift	1.1	</pre>
402
403			<p>
404			The filename is shown above after "filename" in the log entry, which in this
405	nightmorph	1.12	case is <path>0A00010F</path>.
406	swift	1.1	</p>
407
408			<p>
409			As a way to keep track of what netboot image you are using, and to allow
410	neysx	1.8	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	nightmorph	1.12	sparc64 host and the <path>gentoo-sparc64-20100128.tftpboot</path>, use
413			the following command:
414	swift	1.1	</p>
415
416			<pre caption="Linking the image files">
417	nightmorph	1.12	# <i>/bin/ln -s /tftpboot/gentoo-sparc64-20100128.tftpboot \
418	swift	1.3	/tftpboot/0A00010F</i>
419	swift	1.1	</pre>
420
421			<p>
422			Now everything should be set for netbooting!
423			</p>
424
425			</body>
426			</section>
427			</chapter>
428
429	nightmorph	1.12	<chapter id="netbootingclient">
430	swift	1.1	<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	neysx	1.8	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	swift	1.1	</note>
457
458			<p>
459	neysx	1.8	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	swift	1.1	</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	nightmorph	1.12	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	swift	1.1	</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	smithj	1.6	This is presumably because the file your system is trying to load from the
494	neysx	1.8	tftpboot server is not available. On a SPARC system, you would probably see the
495	nightmorph	1.12	following:
496	swift	1.1	</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	neysx	1.8	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	swift	1.1	</p>
512
513			<p>
514	neysx	1.8	<b>I'm trying to netboot, but all I see are "Timeout waiting for ARP/RARP
515			packet" messages.</b>
516	swift	1.1	</p>
517
518			<p>
519			This could be due to a few different problems;
520			</p>
521
522			<ol>
523			<li>
524	neysx	1.8	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	swift	1.1	</li>
529			<li>
530			Verify that the network hub or switch the netboot server and client are
531	neysx	1.8	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	swift	1.1	</li>
553			</ol>
554
555			<p>
556	neysx	1.8	To change the value of tpe-link-test? from an OBP prompt, issue the following
557	nightmorph	1.12	command:
558	swift	1.1	</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	neysx	1.8	This shows the value of tpe-link-test? is now true. Try netbooting the client
567	swift	1.1	again.
568			</p>
569
570			</body>
571			</section>
572			</chapter>
573			</guide>