en/handbook/hb-install-mips-bootloader.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

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

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-mips-bootloader.xml,v 1.10 2005/02/14 14:59:19 swift Exp $ -->

<sections>

<version>1.7</version>
<date>2005-03-30</date>

<section id="sgi">
<title>Silicon Graphics Machines -- Setting Up Arcboot</title>
<subsection>
<title>Installing arcboot</title>
<body>

<p>
Previously in this guide, we showed you how to make a kernel, then copy it to
the volume header using <c>dvhtool</c>.  There were two main flaws with this
system:
</p>

<ul>
  <li>This is not supported on all SGI systems</li>
  <li>It requires a significantly larger volume header</li>
</ul>

<p>
In order to boot the machine, a bootloader, <c>arcboot</c> was developed for
this purpose.  Instead of putting the kernel directly into the volume header, we
leave it in <path>/boot</path> (which resides on a EXT2/3 partition), and tell
<c>arcboot</c> (which sits in the volume header in place of the kernel) where to
find it.  So our first step, is to emerge some tools that we'll use later...
</p>

<pre caption="Installing the required tools">
# <i>emerge dvhtool arcboot</i>
</pre>

<p>
That should have installed two tools, <c>arcboot</c> which sits in the volume
header and loads kernels for us, and <c>dvhtool</c> which helps us put
<c>arcboot</c> into the volume header.
</p>
<p>
The magic binary we want, hides in <path>/usr/lib/arcboot</path> -- on IP22
systems (Indy, Indigo 2, Challenge S), it'll be called
<path>arcboot.ip22</path>.  Other systems should be similar.  We
first copy this file into the volume header.
</p>

<pre caption="Installing arcboot into the volume header">
# <i>dvhtool --unix-to-vh /usr/lib/arcboot/arcboot.ip?? arcboot</i>
</pre>

<p>
We then verify the presence of the file in the volume header. 
</p>

<pre caption="Checking if arcboot made it okay">
# <i>dvhtool --print-volume-directory</i>
----- directory entries -----
Entry #0, name "linux", start 4, bytes 3262570
Entry #1, name "newlinux", start 6377, bytes 7619627
Entry #3, name "arcboot", start 21260, bytes 51448
#
</pre>

<note>
You'll notice that in my case, I've got two old kernels sitting around there,
<path>linux</path> and <path>newlinux</path>.  This is a hangover from before we
started using <c>arcboot</c>.  Their presence doesn't matter -- just so long as
<c>arcboot</c> is present, everything is fine.
</note>

</body>
</subsection>

<subsection>
<title>Configuring arcboot</title>

<body>

<p>
If you've ever set up the Linux Loader (<c>lilo</c>) before, you'll find that
<c>arcboot</c> employs a similar syntax in its configuration file.  Bear in mind
though; <c>arcboot</c> expects to find its configuration file existing on an
EXT2/3 partition as <path>/etc/arcboot.conf</path>.  The easiest way around this
is to make sure <path>/boot</path> is an EXT2/3 partition and that there's a
file called <path>arcboot.conf</path> inside the <path>/boot/etc</path>
directory.  An example config can be found in
<path>/etc/arcboot.conf.sample</path>
</p>

<pre caption="Putting arcboot.conf in its place">
<comment>(Create the /boot/etc directory)</comment>
# <i>mkdir /boot/etc</i>

<comment>(Put our configuration into the target directory)</comment>
# <i>cp /etc/arcboot.conf.sample /boot/etc/arcboot.conf</i>

<comment>(Create a symlink back to /etc)</comment>
# <i>ln -s /boot/etc/arcboot.conf /etc/arcboot.conf</i>

<comment>(... and a symlink in /boot pointing to itself)</comment>
# <i>(cd /boot; ln -s . boot)</i>
</pre>

<p>
You can then edit <path>/etc/arcboot.conf</path> to your own preference.
Personally, I prefer to set up two kernel images: <path>new</path>, a freshly built
image that may or may not work; and <path>working</path>, a proven trustworthy 
kernel image.  My <path>arcboot.conf</path> looks a bit like this.
</p>

<pre caption="Example arcboot.conf">
<comment># arcboot.conf</comment>
<comment>#</comment>
<comment># copyright 2002 Guido Guenther &lt;agx@sigxcpu.org&gt;</comment>
<comment>#</comment>
label=working
        image=/vmlinux
        append="root=/dev/sda3"

<comment># backup version</comment>
label=new
        image=/vmlinux-new
        append="root=/dev/sda3"
</pre>

<p>
Once that is set up, there's then just some little tweaks that you need to do
within the SGI PROM to make this magic work.  This is covered in, not the next
section (that's for Cobalt servers) but the following section
<uri link="#reboot">Rebooting the System</uri>.
</p>

</body>
</subsection>
</section>

<section id="cobalt">
<title>Cobalt MicroServers -- Setting Up CoLo</title>
<subsection>
<title>Installing CoLo</title>
<body>

<p>
On Cobalt servers, these machines have a much less capable firmware installed on
chip.  The Cobalt BOOTROM is primitive, by comparison to the SGI PROM, and has a
number of serious limitations.
</p>

<ul>
  <li>
    There's a 675kB limit on kernels.  The current size of Linux 2.4 makes it
    damn near impossible to make a kernel this size.  Linux 2.6 is totally out
    of the question.
  </li>
  <li>
    64-bit kernels are not supported by the stock firmware (although these are
    highly experimental on Cobalt machines at this time)
  </li>
  <li>
    The shell is basic at best
  </li>
</ul>

<p>
To overcome these limitations, an alternative firmware, called
<uri link="http://www.colonel-panic.org/cobalt-mips/">CoLo</uri> (Cobalt
Loader) was developed.  This is a BOOTROM image that can either be flashed into
the chip inside the Cobalt server, or loaded from the existing firmware.
</p>

<note>
This guide will take you through setting up CoLo so that it is loaded by the
stock firmware.  This is the only truly safe, and recommended way to set up CoLo.
</note>

<warn>
You may, if you wish, flash it into the server, and totally
replace the original firmware -- however, you are entirely on your own in that
endeavour.  Should anything go wrong, you will need to physically remove the
BOOTROM and reprogram it yourself with the stock firmware.  If you are not
sure how to do this -- then <e>DO NOT</e> flash your machine.  We take no
responsibility for whatever happens if you ignore this advice.
</warn>

<p>
Okay, with the warnings over now, we'll get on with installing CoLo.  First,
start by emerging the package.
</p>

<pre caption="Emerging colo">
# <i>emerge colo</i>
</pre>

<p>
With that installed (I hope you read those messages ;-) you should be able to
look inside the <path>/usr/lib/colo</path> directory to find two files,
<path>colo-chain.elf</path>: the "kernel" for the stock firmware to load, and
<path>colo-rom-image.bin</path>: a ROM image for flashing into the BOOTROM.  We
start by mounting /boot and dumping a compressed copy of
<path>colo-chain.elf</path> in <path>/boot</path> where the system expects it.
</p>

<pre caption="Putting CoLo in its place">
# <i>gzip -9vc /usr/lib/colo/colo-chain.elf &gt; /boot/vmlinux.gz</i>
</pre>

</body>
</subsection>

<subsection>
<title>Configuring CoLo</title>

<body>

<p>
Now, when the system first boots up, it'll load CoLo which will spit up a menu
on the back LCD.  The first option (and default that is assumed after roughly 5
seconds) is to boot to the hard disk.  The system would then attempt to mount
the first Linux partition it finds, and run the script
<path>default.colo</path>.  The syntax is fully documented in the CoLo
documentation (have a peek at
<path>/usr/share/doc/colo-X.YY/README.shell.gz</path> -- where X.YY is the
version installed), and is very simple.
</p>

<note>
Just a tip: when installing kernels, I usually create two kernel images,
<path>kernel.gz.working</path> -- a known working kernel, and
<path>kernel.gz.new</path> -- a kernel that's just been compiled. You can either
use symlinks to point to the curent "new" and "working" kernels, or just rename
the kernel images.
</note>

<pre caption="A basic default.colo">
<comment>#:CoLo:#</comment>
mount hda1
load /kernel.gz.working
execute root=/dev/hda3 ro console=ttyS0,115200
</pre>

<note>
CoLo will refuse to load a script that does not begin with the <c>#:CoLo:#</c>
line.  Think of it as the equivalent of saying <c>#!/bin/sh</c> in shell
scripts.
</note>

<p>
It is also possible to ask a question, such as which kernel &amp; configuration
you'd like to boot, with a default timeout.  This is the configuration I use on
my Cobalt server:
</p>

<impo>
Please note that you need to be using CoLo v1.12 or v1.13 to use the <c>menu</c>
command. The following example won't work with v1.11.
</impo>

<impo>
The <c>menu</c> command was replaced by the <c>select</c> command in CoLo v1.14.
If you've installed a later version by hand, have a look at
<path>menu.colo</path> in the <path>examples</path> subdirectory of the CoLo
distribution.
</impo>

<pre caption="Menu-based configuration">
<comment>#:CoLo:#</comment>

lcd "Mounting hda1"
mount hda1
menu "Which Kernel?" 50 Working working New new
lcd "Loading Linux" {menu-option}
load /kernel.gz.{menu-option}
lcd "Booting..."
execute root=/dev/hda5 ro console=ttyS0,115200
boot
</pre>

<p>
The above script asks the user which kernel he/she would like to boot (either
New or Working), then loads <path>vmlinux.gz.new</path> or
<path>vmlinux.gz.working</path> depending on the selection.  If a selection is
not made within 5 seconds (50/10ths of a second) it boots the first option.
</p>
</body>

</subsection>
</section>

<section>
<title>Setting up for Serial Console</title>

<subsection>
<body>

<p>
Okay, the Linux installation as it stands now, would boot fine, but assumes
you're going to be logged in at a physical terminal.  On Cobalt machines, this
is particularly bad -- there's no such thing as a physical terminal.
</p>

<note>
Those who do have the luxury of a supported framebuffer may skip this section if
they wish.
</note>

<p>
First, pull up an editor and hack away at <path>/etc/inittab</path>.  Further
down in the file, you'll see something like this:
</p>

<pre caption="inittab Configuration">
<comment># SERIAL CONSOLE</comment>
<comment>#c0:12345:respawn:/sbin/agetty 9600 ttyS0 vt102</comment>

<comment># TERMINALS</comment>
c1:12345:respawn:/sbin/agetty 38400 tty1 linux
c2:12345:respawn:/sbin/agetty 38400 tty2 linux
c3:12345:respawn:/sbin/agetty 38400 tty3 linux
c4:12345:respawn:/sbin/agetty 38400 tty4 linux
c5:12345:respawn:/sbin/agetty 38400 tty5 linux
c6:12345:respawn:/sbin/agetty 38400 tty6 linux

<comment># What to do at the "Three Finger Salute".</comment>
ca:12345:ctrlaltdel:/sbin/shutdown -r now
</pre>

<p>
First, uncomment the <c>c0</c> line.  By default, it's set to use a terminal
baud rate of 9600 bps.  On Cobalt servers, you may want to change this to 115200
to match the baud rate decided by the BOOT ROM.  This is how that section looks
on my machine.  On a headless machine (e.g. Cobalt servers), I'll also recommend
commenting out the local terminal lines (<c>c1</c> through to <c>c6</c>)
as these have a habit of misbehaving when they can't open
<path>/dev/ttyX</path>.
</p>

<pre caption="Example snippet from inittab">
<comment># SERIAL CONSOLE</comment>
c0:12345:respawn:/sbin/agetty 115200 ttyS0 vt102

<comment># TERMINALS -- These are useless on a headless qube</comment>
<comment>#c1:12345:respawn:/sbin/agetty 38400 tty1 linux</comment>
<comment>#c2:12345:respawn:/sbin/agetty 38400 tty2 linux</comment>
<comment>#c3:12345:respawn:/sbin/agetty 38400 tty3 linux</comment>
<comment>#c4:12345:respawn:/sbin/agetty 38400 tty4 linux</comment>
<comment>#c5:12345:respawn:/sbin/agetty 38400 tty5 linux</comment>
<comment>#c6:12345:respawn:/sbin/agetty 38400 tty6 linux</comment>
</pre>

<p>
Now, lastly... we have to tell the system, that the local serial port can be
trusted as a secure terminal.  The file we need to poke at is
<path>/etc/securetty</path>.  It contains a list of terminals that the system
trusts.  We simply stick in two more lines, permitting the serial line to be
used for <c>root</c> logins.
</p>

<pre caption="Enabling root logins on serial console">
<comment>(/dev/ttyS0 -- the traditional name for the first serial port)</comment>
# <i>echo 'ttyS0' >> /etc/securetty</i>

<comment>(Lately, Linux also calls this /dev/tts/0 -- so we add this
too)</comment>
# <i>echo 'tts/0' >> /etc/securetty</i>
</pre>

</body>
</subsection>
</section>

<section id="reboot">
<title>Rebooting the System</title>
<subsection>
<body>

<p>
Exit the chrooted environment and unmount all mounted partitions. Then type in 
that one magical command you have been waiting for: <c>reboot</c>.
</p>

<pre caption="Exiting the chroot, unmounting all partitions and rebooting">
# <i>exit</i>
cdimage ~# <i>cd</i>
cdimage ~# <i>umount /mnt/gentoo/boot /mnt/gentoo/proc /mnt/gentoo</i>
cdimage ~# <i>reboot</i>
</pre>

<note>
<e>Cobalt Users:</e> The rest of this section covers the setting up of the SGI
PROM so that it boots <c>arcboot</c> off disk and loads Linux.  This is not
applicable to the setup of Cobalt servers.  In fact, all your work is done --
there is no configuration needed for the first boot up, you can skip to the next
section: <uri link="?part=1&amp;chap=11">Finalising your Gentoo
Installation</uri>
</note>

</body>
</subsection>
</section>
<section>
<title>Tweaking the SGI PROM</title>
<subsection>
<body>

<p>
When you are rebooted, go to the <e>System Maintenance Menu</e> and select 
<e>Enter Command Monitor</e> (<c>5</c>). If you want to test your new Gentoo 
installation, you can just run <c>boot -f &lt;kernel name&gt;</c>. To have your 
system permanently boot into the Gentoo installation, you need to set some 
variables in the SGI PROM: 
</p>

<pre caption="Configuring the PROM to Boot Gentoo">
1) Start System
2) Install System Software
3) Run Diagnostics
4) Recover System
5) Enter Command Monitor

Option? <i>5</i>
Command Monitor.  Type "exit" to return to the menu.

<comment>(&lt;root device&gt; = Gentoo's root partition, e.g. /dev/sda3)</comment>
&gt;&gt; <i>setenv OSLoadPartition &lt;root device&gt;</i>

<comment>(To list the available kernels, type "ls")</comment>
&gt;&gt; <i>setenv OSLoader &lt;kernel name&gt;</i>
&gt;&gt; <i>setenv OSLoadFilename &lt;kernel name&gt;</i>

<comment>(Declare the kernel parameters you want to pass)</comment>
&gt;&gt; <i>setenv OSLoadOptions &lt;kernel parameters&gt;</i>

<comment>(Provide the location of the Volume Header)</comment>
&gt;&gt; <i>setenv SystemPartition scsi(0)disk(1)rdisk(0)partition(8)</i>

<comment>(Automatically boot Gentoo)</comment>
&gt;&gt; <i>setenv AutoLoad Yes</i>

<comment>(Set the timezone)</comment>
&gt;&gt; <i>setenv TimeZone EST5EDT</i>

<comment>(Use the serial console - graphic adapter users should have "g" instead of "d1" (one))</comment>
&gt;&gt; <i>setenv console d1</i>
</pre>

<p>
Now you're ready to enjoy Gentoo! Boot in your Gentoo installation and finish 
up with <uri link="?part=1&amp;chap=11">Finalizing your Gentoo 
Installation</uri>.
</p>

</body>
</subsection>
</section>
</sections>
1	swift	1.1	<?xml version='1.0' encoding='UTF-8'?>
2			<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
4			<!-- The content of this document is licensed under the CC-BY-SA license -->
5			<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
6
7	swift	1.11	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-install-mips-bootloader.xml,v 1.10 2005/02/14 14:59:19 swift Exp $ -->
8	swift	1.1
9			<sections>
10	swift	1.6
11	swift	1.11	<version>1.7</version>
12			<date>2005-03-30</date>
13	swift	1.6
14	swift	1.10	<section id="sgi">
15			<title>Silicon Graphics Machines -- Setting Up Arcboot</title>
16	swift	1.1	<subsection>
17	swift	1.10	<title>Installing arcboot</title>
18	swift	1.1	<body>
19
20			<p>
21	swift	1.10	Previously in this guide, we showed you how to make a kernel, then copy it to
22			the volume header using <c>dvhtool</c>. There were two main flaws with this
23			system:
24	swift	1.1	</p>
25
26	swift	1.10	<ul>
27			<li>This is not supported on all SGI systems</li>
28			<li>It requires a significantly larger volume header</li>
29			</ul>
30
31	swift	1.1	<p>
32	swift	1.10	In order to boot the machine, a bootloader, <c>arcboot</c> was developed for
33			this purpose. Instead of putting the kernel directly into the volume header, we
34			leave it in <path>/boot</path> (which resides on a EXT2/3 partition), and tell
35			<c>arcboot</c> (which sits in the volume header in place of the kernel) where to
36			find it. So our first step, is to emerge some tools that we'll use later...
37	swift	1.1	</p>
38
39	swift	1.10	<pre caption="Installing the required tools">
40			# <i>emerge dvhtool arcboot</i>
41	swift	1.1	</pre>
42
43			<p>
44	swift	1.10	That should have installed two tools, <c>arcboot</c> which sits in the volume
45			header and loads kernels for us, and <c>dvhtool</c> which helps us put
46			<c>arcboot</c> into the volume header.
47			</p>
48			<p>
49			The magic binary we want, hides in <path>/usr/lib/arcboot</path> -- on IP22
50			systems (Indy, Indigo 2, Challenge S), it'll be called
51			<path>arcboot.ip22</path>. Other systems should be similar. We
52			first copy this file into the volume header.
53	swift	1.1	</p>
54
55	swift	1.10	<pre caption="Installing arcboot into the volume header">
56			# <i>dvhtool --unix-to-vh /usr/lib/arcboot/arcboot.ip?? arcboot</i>
57	swift	1.1	</pre>
58
59			<p>
60	swift	1.10	We then verify the presence of the file in the volume header.
61	swift	1.1	</p>
62
63	swift	1.10	<pre caption="Checking if arcboot made it okay">
64	swift	1.1	# <i>dvhtool --print-volume-directory</i>
65	swift	1.10	----- directory entries -----
66			Entry #0, name "linux", start 4, bytes 3262570
67			Entry #1, name "newlinux", start 6377, bytes 7619627
68			Entry #3, name "arcboot", start 21260, bytes 51448
69			#
70			</pre>
71
72			<note>
73			You'll notice that in my case, I've got two old kernels sitting around there,
74			<path>linux</path> and <path>newlinux</path>. This is a hangover from before we
75			started using <c>arcboot</c>. Their presence doesn't matter -- just so long as
76			<c>arcboot</c> is present, everything is fine.
77			</note>
78
79			</body>
80			</subsection>
81
82			<subsection>
83			<title>Configuring arcboot</title>
84
85			<body>
86
87			<p>
88			If you've ever set up the Linux Loader (<c>lilo</c>) before, you'll find that
89			<c>arcboot</c> employs a similar syntax in its configuration file. Bear in mind
90			though; <c>arcboot</c> expects to find its configuration file existing on an
91			EXT2/3 partition as <path>/etc/arcboot.conf</path>. The easiest way around this
92			is to make sure <path>/boot</path> is an EXT2/3 partition and that there's a
93			file called <path>arcboot.conf</path> inside the <path>/boot/etc</path>
94			directory. An example config can be found in
95			<path>/etc/arcboot.conf.sample</path>
96			</p>
97
98			<pre caption="Putting arcboot.conf in its place">
99			<comment>(Create the /boot/etc directory)</comment>
100			# <i>mkdir /boot/etc</i>
101
102			<comment>(Put our configuration into the target directory)</comment>
103			# <i>cp /etc/arcboot.conf.sample /boot/etc/arcboot.conf</i>
104
105			<comment>(Create a symlink back to /etc)</comment>
106			# <i>ln -s /boot/etc/arcboot.conf /etc/arcboot.conf</i>
107
108			<comment>(... and a symlink in /boot pointing to itself)</comment>
109			# <i>(cd /boot; ln -s . boot)</i>
110			</pre>
111
112			<p>
113			You can then edit <path>/etc/arcboot.conf</path> to your own preference.
114			Personally, I prefer to set up two kernel images: <path>new</path>, a freshly built
115			image that may or may not work; and <path>working</path>, a proven trustworthy
116			kernel image. My <path>arcboot.conf</path> looks a bit like this.
117			</p>
118
119			<pre caption="Example arcboot.conf">
120			<comment># arcboot.conf</comment>
121			<comment>#</comment>
122			<comment># copyright 2002 Guido Guenther <agx@sigxcpu.org></comment>
123			<comment>#</comment>
124			label=working
125			image=/vmlinux
126			append="root=/dev/sda3"
127
128			<comment># backup version</comment>
129			label=new
130			image=/vmlinux-new
131			append="root=/dev/sda3"
132			</pre>
133
134			<p>
135			Once that is set up, there's then just some little tweaks that you need to do
136			within the SGI PROM to make this magic work. This is covered in, not the next
137			section (that's for Cobalt servers) but the following section
138			<uri link="#reboot">Rebooting the System</uri>.
139			</p>
140
141			</body>
142			</subsection>
143			</section>
144
145			<section id="cobalt">
146			<title>Cobalt MicroServers -- Setting Up CoLo</title>
147			<subsection>
148			<title>Installing CoLo</title>
149			<body>
150
151			<p>
152			On Cobalt servers, these machines have a much less capable firmware installed on
153			chip. The Cobalt BOOTROM is primitive, by comparison to the SGI PROM, and has a
154			number of serious limitations.
155			</p>
156
157			<ul>
158			<li>
159			There's a 675kB limit on kernels. The current size of Linux 2.4 makes it
160			damn near impossible to make a kernel this size. Linux 2.6 is totally out
161			of the question.
162			</li>
163			<li>
164			64-bit kernels are not supported by the stock firmware (although these are
165			highly experimental on Cobalt machines at this time)
166			</li>
167			<li>
168			The shell is basic at best
169			</li>
170			</ul>
171
172			<p>
173			To overcome these limitations, an alternative firmware, called
174			<uri link="http://www.colonel-panic.org/cobalt-mips/">CoLo</uri> (Cobalt
175			Loader) was developed. This is a BOOTROM image that can either be flashed into
176			the chip inside the Cobalt server, or loaded from the existing firmware.
177			</p>
178
179			<note>
180			This guide will take you through setting up CoLo so that it is loaded by the
181			stock firmware. This is the only truly safe, and recommended way to set up CoLo.
182			</note>
183
184			<warn>
185			You may, if you wish, flash it into the server, and totally
186			replace the original firmware -- however, you are entirely on your own in that
187			endeavour. Should anything go wrong, you will need to physically remove the
188			BOOTROM and reprogram it yourself with the stock firmware. If you are not
189			sure how to do this -- then <e>DO NOT</e> flash your machine. We take no
190			responsibility for whatever happens if you ignore this advice.
191			</warn>
192
193			<p>
194			Okay, with the warnings over now, we'll get on with installing CoLo. First,
195			start by emerging the package.
196			</p>
197
198			<pre caption="Emerging colo">
199			# <i>emerge colo</i>
200			</pre>
201
202			<p>
203			With that installed (I hope you read those messages ;-) you should be able to
204			look inside the <path>/usr/lib/colo</path> directory to find two files,
205			<path>colo-chain.elf</path>: the "kernel" for the stock firmware to load, and
206			<path>colo-rom-image.bin</path>: a ROM image for flashing into the BOOTROM. We
207			start by mounting /boot and dumping a compressed copy of
208			<path>colo-chain.elf</path> in <path>/boot</path> where the system expects it.
209			</p>
210
211			<pre caption="Putting CoLo in its place">
212			# <i>gzip -9vc /usr/lib/colo/colo-chain.elf > /boot/vmlinux.gz</i>
213			</pre>
214
215			</body>
216			</subsection>
217
218			<subsection>
219			<title>Configuring CoLo</title>
220
221			<body>
222
223			<p>
224			Now, when the system first boots up, it'll load CoLo which will spit up a menu
225			on the back LCD. The first option (and default that is assumed after roughly 5
226			seconds) is to boot to the hard disk. The system would then attempt to mount
227			the first Linux partition it finds, and run the script
228			<path>default.colo</path>. The syntax is fully documented in the CoLo
229			documentation (have a peek at
230			<path>/usr/share/doc/colo-X.YY/README.shell.gz</path> -- where X.YY is the
231			version installed), and is very simple.
232			</p>
233
234	swift	1.11	<note>
235			Just a tip: when installing kernels, I usually create two kernel images,
236			<path>kernel.gz.working</path> -- a known working kernel, and
237			<path>kernel.gz.new</path> -- a kernel that's just been compiled. You can either
238			use symlinks to point to the curent "new" and "working" kernels, or just rename
239			the kernel images.
240			</note>
241
242	swift	1.10	<pre caption="A basic default.colo">
243			<comment>#:CoLo:#</comment>
244			mount hda1
245	swift	1.11	load /kernel.gz.working
246	swift	1.10	execute root=/dev/hda3 ro console=ttyS0,115200
247			</pre>
248
249			<note>
250			CoLo will refuse to load a script that does not begin with the <c>#:CoLo:#</c>
251			line. Think of it as the equivalent of saying <c>#!/bin/sh</c> in shell
252			scripts.
253			</note>
254
255			<p>
256			It is also possible to ask a question, such as which kernel & configuration
257			you'd like to boot, with a default timeout. This is the configuration I use on
258			my Cobalt server:
259			</p>
260
261	swift	1.11	<impo>
262			Please note that you need to be using CoLo v1.12 or v1.13 to use the <c>menu</c>
263			command. The following example won't work with v1.11.
264			</impo>
265
266			<impo>
267			The <c>menu</c> command was replaced by the <c>select</c> command in CoLo v1.14.
268			If you've installed a later version by hand, have a look at
269			<path>menu.colo</path> in the <path>examples</path> subdirectory of the CoLo
270			distribution.
271			</impo>
272
273	swift	1.10	<pre caption="Menu-based configuration">
274			<comment>#:CoLo:#</comment>
275
276			lcd "Mounting hda1"
277			mount hda1
278			menu "Which Kernel?" 50 Working working New new
279			lcd "Loading Linux" {menu-option}
280	swift	1.11	load /kernel.gz.{menu-option}
281	swift	1.10	lcd "Booting..."
282			execute root=/dev/hda5 ro console=ttyS0,115200
283			boot
284			</pre>
285
286			<p>
287			The above script asks the user which kernel he/she would like to boot (either
288			New or Working), then loads <path>vmlinux.gz.new</path> or
289			<path>vmlinux.gz.working</path> depending on the selection. If a selection is
290			not made within 5 seconds (50/10ths of a second) it boots the first option.
291			</p>
292			</body>
293
294			</subsection>
295			</section>
296
297			<section>
298			<title>Setting up for Serial Console</title>
299
300			<subsection>
301			<body>
302
303			<p>
304			Okay, the Linux installation as it stands now, would boot fine, but assumes
305			you're going to be logged in at a physical terminal. On Cobalt machines, this
306			is particularly bad -- there's no such thing as a physical terminal.
307			</p>
308
309			<note>
310			Those who do have the luxury of a supported framebuffer may skip this section if
311			they wish.
312			</note>
313
314			<p>
315			First, pull up an editor and hack away at <path>/etc/inittab</path>. Further
316			down in the file, you'll see something like this:
317			</p>
318
319			<pre caption="inittab Configuration">
320			<comment># SERIAL CONSOLE</comment>
321			<comment>#c0:12345:respawn:/sbin/agetty 9600 ttyS0 vt102</comment>
322
323			<comment># TERMINALS</comment>
324			c1:12345:respawn:/sbin/agetty 38400 tty1 linux
325			c2:12345:respawn:/sbin/agetty 38400 tty2 linux
326			c3:12345:respawn:/sbin/agetty 38400 tty3 linux
327			c4:12345:respawn:/sbin/agetty 38400 tty4 linux
328			c5:12345:respawn:/sbin/agetty 38400 tty5 linux
329			c6:12345:respawn:/sbin/agetty 38400 tty6 linux
330
331			<comment># What to do at the "Three Finger Salute".</comment>
332			ca:12345:ctrlaltdel:/sbin/shutdown -r now
333	swift	1.1	</pre>
334
335			<p>
336	swift	1.10	First, uncomment the <c>c0</c> line. By default, it's set to use a terminal
337			baud rate of 9600 bps. On Cobalt servers, you may want to change this to 115200
338			to match the baud rate decided by the BOOT ROM. This is how that section looks
339			on my machine. On a headless machine (e.g. Cobalt servers), I'll also recommend
340			commenting out the local terminal lines (<c>c1</c> through to <c>c6</c>)
341			as these have a habit of misbehaving when they can't open
342			<path>/dev/ttyX</path>.
343	swift	1.1	</p>
344
345	swift	1.10	<pre caption="Example snippet from inittab">
346			<comment># SERIAL CONSOLE</comment>
347			c0:12345:respawn:/sbin/agetty 115200 ttyS0 vt102
348
349			<comment># TERMINALS -- These are useless on a headless qube</comment>
350			<comment>#c1:12345:respawn:/sbin/agetty 38400 tty1 linux</comment>
351			<comment>#c2:12345:respawn:/sbin/agetty 38400 tty2 linux</comment>
352			<comment>#c3:12345:respawn:/sbin/agetty 38400 tty3 linux</comment>
353			<comment>#c4:12345:respawn:/sbin/agetty 38400 tty4 linux</comment>
354			<comment>#c5:12345:respawn:/sbin/agetty 38400 tty5 linux</comment>
355			<comment>#c6:12345:respawn:/sbin/agetty 38400 tty6 linux</comment>
356			</pre>
357
358	swift	1.1	<p>
359	swift	1.10	Now, lastly... we have to tell the system, that the local serial port can be
360			trusted as a secure terminal. The file we need to poke at is
361			<path>/etc/securetty</path>. It contains a list of terminals that the system
362			trusts. We simply stick in two more lines, permitting the serial line to be
363			used for <c>root</c> logins.
364	swift	1.2	</p>
365
366	swift	1.10	<pre caption="Enabling root logins on serial console">
367			<comment>(/dev/ttyS0 -- the traditional name for the first serial port)</comment>
368			# <i>echo 'ttyS0' >> /etc/securetty</i>
369
370			<comment>(Lately, Linux also calls this /dev/tts/0 -- so we add this
371			too)</comment>
372			# <i>echo 'tts/0' >> /etc/securetty</i>
373			</pre>
374
375	swift	1.2	</body>
376			</subsection>
377			</section>
378	swift	1.10
379	cam	1.3	<section id="reboot">
380	swift	1.2	<title>Rebooting the System</title>
381			<subsection>
382			<body>
383
384			<p>
385			Exit the chrooted environment and unmount all mounted partitions. Then type in
386			that one magical command you have been waiting for: <c>reboot</c>.
387			</p>
388
389			<pre caption="Exiting the chroot, unmounting all partitions and rebooting">
390			# <i>exit</i>
391	swift	1.4	cdimage ~# <i>cd</i>
392	swift	1.2	cdimage ~# <i>umount /mnt/gentoo/boot /mnt/gentoo/proc /mnt/gentoo</i>
393			cdimage ~# <i>reboot</i>
394			</pre>
395
396	swift	1.10	<note>
397			<e>Cobalt Users:</e> The rest of this section covers the setting up of the SGI
398			PROM so that it boots <c>arcboot</c> off disk and loads Linux. This is not
399			applicable to the setup of Cobalt servers. In fact, all your work is done --
400			there is no configuration needed for the first boot up, you can skip to the next
401			section: <uri link="?part=1&chap=11">Finalising your Gentoo
402			Installation</uri>
403			</note>
404
405	swift	1.2	</body>
406			</subsection>
407			</section>
408			<section>
409	swift	1.10	<title>Tweaking the SGI PROM</title>
410	swift	1.2	<subsection>
411			<body>
412
413			<p>
414			When you are rebooted, go to the <e>System Maintenance Menu</e> and select
415			<e>Enter Command Monitor</e> (<c>5</c>). If you want to test your new Gentoo
416			installation, you can just run <c>boot -f <kernel name></c>. To have your
417			system permanently boot into the Gentoo installation, you need to set some
418	swift	1.10	variables in the SGI PROM:
419	swift	1.2	</p>
420
421			<pre caption="Configuring the PROM to Boot Gentoo">
422			1) Start System
423			2) Install System Software
424			3) Run Diagnostics
425			4) Recover System
426			5) Enter Command Monitor
427
428			Option? <i>5</i>
429			Command Monitor. Type "exit" to return to the menu.
430
431			<comment>(<root device> = Gentoo's root partition, e.g. /dev/sda3)</comment>
432			>> <i>setenv OSLoadPartition <root device></i>
433
434			<comment>(To list the available kernels, type "ls")</comment>
435			>> <i>setenv OSLoader <kernel name></i>
436			>> <i>setenv OSLoadFilename <kernel name></i>
437
438			<comment>(Declare the kernel parameters you want to pass)</comment>
439			>> <i>setenv OSLoadOptions <kernel parameters></i>
440
441			<comment>(Provide the location of the Volume Header)</comment>
442			>> <i>setenv SystemPartition scsi(0)disk(1)rdisk(0)partition(8)</i>
443
444			<comment>(Automatically boot Gentoo)</comment>
445			>> <i>setenv AutoLoad Yes</i>
446
447			<comment>(Set the timezone)</comment>
448			>> <i>setenv TimeZone EST5EDT</i>
449
450			<comment>(Use the serial console - graphic adapter users should have "g" instead of "d1" (one))</comment>
451			>> <i>setenv console d1</i>
452			</pre>
453
454			<p>
455			Now you're ready to enjoy Gentoo! Boot in your Gentoo installation and finish
456			up with <uri link="?part=1&chap=11">Finalizing your Gentoo
457			Installation</uri>.
458	swift	1.1	</p>
459
460			</body>
461			</subsection>
462			</section>
463			</sections>