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.9 2007/07/26 20:55:48 yoswink Exp $ -->

<guide link="/doc/en/gentoo-sparc-netboot-howto.xml">

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

<author title="SPARC Developer">
  <mail link="weeve@gentoo.org">Jason Wever</mail>
</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>1.2</version>
<date>2005-08-18</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>
Currently, there are two choices for a reverse ARP daemon. They are
net-misc/iputils (installed as part of the system profile) and net-misc/rarpd.
</p>

<note>
Installing net-misc/rarpd will overwrite the rarpd and rarpd manpage from
net-misc/iputils
</note>

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

<p>
No matter which rarpd you choose to use, you will need to setup the
<path>/etc/ethers</path> file. This file indicates which hosts rarpd 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 rarpd 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 net-misc/iputils rarpd</b>
</p>

<p>
First, we will need to determine the options to use for rarpd. While there are
more options than we'll cover here, these options should get you started As
there is currently no init.d script for net-misc/iputils version of rarpd, an
entry will need to be added to <path>/etc/conf.d/local.start</path> if you want
to enable rarpd servies 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 rarpd options (as taken from the man page):
</p>

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

<p>
For more options, consult the section 8 man page on rarpd.
</p>

<p>
<b>Setting up net-misc/rarpd</b>
</p>

<p>
Firstly, we'll need to install rarpd with the following command:
</p>

<pre caption="Installing rarpd">
# <i>emerge net-misc/rarpd</i>
</pre>

<p>
Next, options for rarpd will need to be set in <path>/etc/conf.d/rarpd</path>.
For an equivalent configuration as the one used above for net-misc/iputils
rarpd, adjust <path>/etc/conf.d/rarpd</path> to look like the following
</p>

<pre caption="/etc/conf.d/rarpd">
RARPD_OPTS="-v -i eth0"
</pre>

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

<ul>
  <li>
    <c>-v</c> Be verbose. Show requests which the daemon is responding to
  </li>
  <li>
    <c>-i</c> Bind to the named interface. By default rarpd binds to the
    default interface for the local system type, if available
  </li>
</ul>

<p>
For more options, consult the section 8 man page on rarpd and rarpd --help.
</p>

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

<p>
Here there are three options for a tftp daemon, net-misc/atftp,
net-misc/netkit-tftp and net-misc/tftp-hpa. 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 /tftpboot. 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 nobody.
</p>

<p>
If the directory you have chosen does not currently exist, it will need to be
created with the mkdir command. The command for the example /tftpboot 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 nobody;
</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 net-misc/atftp package as follows;
</p>

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

<p>
After the net-misc/atftp 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 atftp has no
init.d, inetd or xinetd scripts of its own. If you want to use inetd or xinetd
for controlling the tftpd service, please see their respective man pages.
</p>

<p>
Below is an example entry for atftpd 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 rarpd 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 the section 8 man page on atftpd.
</p>

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

<p>
First, install the net-misc/netkit-tftp package as follows;
</p>

<pre caption="Installing netkit-tftp">
# <i>emerge net-misc/netkit-tftp</i>
</pre>

<p>
Secondly, install sys-apps/xinetd if it is not currently present; After the
net-misc/netkit-tftp and sys-apps/xinetd packages have been installed,
netkit-tftp will need to be configured. netkit-tftp needs to be run from
xinetd, however it does not provide example scripts of its own. A sample xinetd
file is provided below;
</p>

<pre caption="Sample /etc/xinetd.d/tftp file">
service tftp
{
    protocol        = udp
    port            = 69
    socket_type     = dgram
    wait            = yes
    user            = nobody
    group           = nobody
    server          = /usr/sbin/in.tftpd
    server_args     = /tftpboot
    only_from       = 10.0.1.0
    disable         = no
}
</pre>

<note>
This sample xinetd configuration file for tftp uses the line "disable = no",
which enables the service by default. This is opposite of the default way
packages in Gentoo provide their respective xinetd configuration files, which
have disable set to yes.
</note>

<p>
An explanation of the above options which can be changed;
user        user in.tftpd requests are handled as
group       group in.tftpd requests are handled as
server_args root directory for tftp daemon to serve files from
only_from   tells xinetd what hosts to allow tftp connections from
</p>

<p>
Additional information on xinetd configuration files can be found in the
section 5 manpage on xinetd.conf
</p>

<p>
If xinetd is running, you can send it the HUP signal to have it re-read its
configuration files;
</p>

<pre caption="Sending HUP signal to xinetd">
# <i>/bin/killall -HUP xinetd</i>
</pre>

<p>
If xinetd is not running, start it with the init.d command;
</p>

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

<p>
For more information, consult the section 8 man page on in.tftpd
</p>

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

<p>
First, install the tftp-hpa package using the following command;
</p>

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

<p>
tftp-hpa comes with an init.d and the accompanying conf.d configuration file.
Check to make sure that INIITFTPD_PATH and INITFTP_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 init.d script;
</p>

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

<p>
For more options, consult the section 8 man page on tftpd.
</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. For a sparc or
sparc64 netboot image, please check your local Gentoo distfiles mirror under
<path>experimental/sparc/tftpboot</path> for the appropriate image. We'll
assume you are planning to boot a sparc64 host using the
<path>gentoo-sparc64-1.4_rc4-20040102.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-1.4_rc4-20040102.tftpboot /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>
A guide on how to convert decimal to hexadecimal is available at
<uri>http://www.permadi.com/tutorial/numDecToHex/</uri>
</p>

<p>
And for the lazy/impatient, you can find a decimal to hexadecimal conversion
tool at <uri>http://dan.drydog.com/hextemp.html</uri>
</p>

<note>
For each octet in the IP address (the 10 in 10.0.1.15 for instance), you will
need to convert it to hexadecimal, rather than converting the IP address asa
singular number.
</note>

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

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

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

<p>
On sparc however, the file would be 0A00010F.SUN4M, 0A00010F.SUN4C or
0A00010F.SUN4D depending on what type of sparc system.
</p>

<p>
Additionally, if 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 rarpd and tftpd daemon you've chosen are currently
running, then boot the host as described below in "Netbooting the client".
</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 in.tftpd.
</p>

<p>
An example entry from a netboot server running sysklogd and tftp-hpa 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 0A00010F.
</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-1.4_rc4-20040102.tftpboot</path>, use
the following command;
</p>

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

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

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

<chapter>
<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
installing the rarpd and tftpd packages, please search
<uri>http://forums.gentoo.org</uri> and <uri>http://bugs.gentoo.org</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 at
<uri>http://bugs.gentoo.org</uri>
</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>