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

<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<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/1.0 -->
<license/>

<version>1.0</version>
<date>April 11 2004</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>
nstalling 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 MAC address of the NIC the machine 
will be netbooting from and the 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 hexidecimal 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 /etc/ethers, 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 /etc/ethers has a hostname, the netboot server needs to
be able to resolve the hostname into its IP address.  This can be done two
ways, /etc/hosts or the nameserver the netboot server uses.
</p>

<p>
An /etc/hosts 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 /etc/hosts 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 /etc/hosts and the nameserver have an entry for the host to be
netbooted, /etc/hosts will be used first (granted the order of
/etc/nsswitch.conf 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 /etc/conf.d/local.start 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 explination 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 /etc/conf.d/rarpd.  For an
equivalent configuration as the one used above for net-misc/iputils rarpd,
adjust /etc/conf.d/rarpd to look like the following
</p>

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

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

<ul>
  <li>
    -v Be verbose.  Show requests which the daemon is responding to.
  </li>
  <li>
    -i 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 (/) 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 /tftpboot 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
/etc/conf.d/local.start 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 /etc/conf.d/local.start;
</p>

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

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

<ul>
  <li>
    -v Increase or set the logging leve.  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>
    --daemon 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 explination 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 /etc/conf.d/in.tftpd
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
experimental/sparc/tftpboot for the appropriate image.  We'll assume you are
planning to boot a sparc64 host using the
gentoo-sparc64-1.4_rc4-20040102.tftpboot image.
</p>

<p>
Once you have an image, copy the image into /tftpboot;
</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 hexidecimal number of its current IP address, and on some platforms an
.ARCH suffix.
</p>

<p>
A guide on how to convert decimal to hexidecimal is available at
<uri>http://www.permadi.com/tutorial/numDecToHex/</uri>
</p>

<p>
And for the lazy/impatient, you can find a decimal to hexidecimal 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 hexidecimal, 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 hexidecimal
equivalent;
</p>

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