1.  Hardware Requirements

Introduction

Before we start, we first list what hardware requirements you need to successfully install Gentoo on your box.

Hardware Requirements

You should also check the MIPS Hardware Requirements document available from our website.

1.  Installation Notes

A note about Processor Architectures

On many architectures, the processor has gone through several generations, each newer generation builds on the foundation of the previous one. MIPS is no exception. There are several generations of CPU covered under the MIPS architecture. In order to choose your netboot image stage tarball and CFLAGS appropriately, you need to be aware of which family your system's CPU belongs in. These families are referred to as the Instruction Set Architecture.

Also, another important concept to grasp is the concept of endianness. Endianness refers to the way that a CPU reads words from main memory. A word can be read as either big endian (most significant byte first), or little endian (least significant byte first). Intel x86 machines are generally Little endian, whilst Apple and Sparc machines are Big Endian. On MIPS, they can be either. To separate them apart, we append el to the architecture name to denote little endian.

For those willing to learn more about ISAs, the following websites may be of assistance.

• Linux/MIPS Website: MIPS ISA
• Linux/MIPS Website: Endianness
• Linux/MIPS Website: Processors
• Wikipedia: Instruction Set

The Stage3 Tarball

A stage3 tarball is an archive containing a minimal Gentoo environment, suitable to continue the Gentoo installation using the instructions in this manual. Previously, the Gentoo Handbook described the installation using one of three stage tarballs. While Gentoo still offers stage1 and stage2 tarballs, the official installation method uses the stage3 tarball. If you are interested in performing a Gentoo installation using a stage1 or stage2 tarball, please read the Gentoo FAQ on How do I Install Gentoo Using a Stage1 or Stage2 Tarball?

1.  Netbooting Overview

In this section, we'll cover what you need in order to successfully network boot a Silicon Graphics workstation or Cobalt Server appliance. This is just a brief guide, it is not intended to be thorough, for more information, it is recommended that you read the Diskless HOWTO.

What You Need: Depending on the machine, there is a certain amount of hardware that you'll need in order to successfully netboot and install Linux.

• In General:
  • DHCP/BOAMD Alchemy series, 4kc, 4km, many others... There are a few revisions in the MIPS32 ISA.OTP server (ISC DHCPd recommended)
  • Patience -- and lots of it
• For Silicon Graphics workstations:
  • TFTP server (tftp-hpa recommended)
  • If you want/need to use serial console:
    • MiniDIN8 --> RS-232 serial cable (only needed for IP22 and IP28 systems)
    • Null-modem cable
    • VT100 or ANSI compatible terminal capable of 9600 baud
• For Cobalt Servers (NOT the original Qube):
  • NFS server
  • Null-modem cable
  • VT100 or ANSI compatible terminal capable of 115200 baud

Setting up TFTP and DHCP -- a brief guide

Okay, so you've got your bits and pieces together, now to set everything up. As mentioned earlier -- this is not a complete guide, this is a bare-bones config that will just get things rolling. You can either use this when starting a setup from scratch, or use the suggestions to amend your existing setup to support netbooting.

It is worth noting that the servers used need not be running Gentoo Linux, you could quite reasonably use FreeBSD or any Unix-like platform. However, this guide will assume you are running Gentoo Linux. You also may run TFTP/NFS on a separate machine to the DHCP server if desired.

First Step -- configuring DHCP. In order for the ISC DHCP daemon to respond to BOOTP requests (as required by the SGI & Cobalt BOOTROM) you need to first enable dynamic BOOTP on the address range in use; then set up an entry for each client with pointers to the boot image.

# emerge dhcp

Once installed you need to create the /etc/dhcp/dhcpd.conf. Here's a bare-bones config to get you started.

# Tell dhcpd to disable dynamic DNS.
# dhcpd will refuse to start without this.
ddns-update-style none;

# Create a subnet:
subnet 192.168.10.0 netmask 255.255.255.0 {
  # Address pool for our booting clients. Don't forget the 'dynamic-bootp' bit!
  pool {
    range dynamic-bootp 192.168.10.1 192.168.10.254;
  }

  # DNS servers and default gateway -- substitute as appropriate
  option domain-name-servers 203.1.72.96, 202.47.56.17;
  option routers 192.168.10.1;

  # Tell the DHCP server it's authoritative for this subnet.
  authoritative;

  # Allow BOOTP to be used on this subnet.
  allow bootp;
}

With that setup, one can then add any number of clients within the subnet clause. We will cover what you need to put in later in this guide.

Next Step -- Setting up TFTP server. It is recommended that you use tftp-hpa as it is the only TFTP daemon known to work correctly. Proceed by installing it as shown below.

# emerge net-ftp/tftp-hpa

This will create /tftproot for you to store the netboot images. You may move this elsewhere if you wish. For the purposes of this guide, it is assumed that you have left it in the default location.

1.  Netbooting on SGI Workstations

Downloading a Netboot image

Depending on the system you're installing for, there are several possible images available for download. These are all labelled according to the system type and CPU they are compiled for. The machine types are as follows:

Also in the filename, r4k refers to R4000-series processors, r5k for R5000, rm5k for the RM5200 and r10k for R10000. You will find the images available on the Gentoo mirrors.

DHCP Configuration for an SGI Client

Once you have downloaded the file, place the decompressed image file in your /tftproot directory. (Use bzip2 -d to decompress) Then edit your /etc/dhcp/dhcpd.conf and add the entry for your SGI client.

subnet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx {
  # ... usual stuff here ...

  # SGI Workstation... change 'sgi' to your SGI machine's hostname.
  host sgi {
  
    # MAC Address of SGI Machine. Normally this is written on the back
    # or base of the machine.
    hardware ethernet 08:00:69:08:db:77;

    # TFTP Server to download from (by default, same as DHCP server)
    next-server 192.168.10.1;

    # IP address to give to the SGI machine
    fixed-address 192.168.10.3;

    # Filename for the PROM to download and boot
    filename "/gentoo-r4k.img";
  }
}

Kernel Options

We're almost done, but there's a couple of little tweaks still to be done. Pull up a console with root privileges, and enter the following commands.

(Disable "Path Maximum Transfer Unit", otherwise SGI Prom won't find the kernel)
# echo 1 > /proc/sys/net/ipv4/ip_no_pmtu_disc

(Set the port range usable by the SGI PROM)
# echo "2048 32767" > /proc/sys/net/ipv4/ip_local_port_range

This should be sufficient to allow the Linux server to play nice with SGI's PROM.

Start Your Daemons...

At this point, you should be ready to start the daemons. Enter the following:

# /etc/init.d/dhcp start
# /etc/init.d/in.tftpd start

If nothing went wrong in that last step you should be all set to power on the workstation and proceed with the guide. If the DHCP server isn't firing up for whatever reason, try running 'dhcpd' on the command line and see what it tells you -- if all is well, it should just fork into the background, otherwise you'll see 'exiting.' just below its complaint.

An easy way to verify if the tftp daemon is running is to type the following command -- if you see something like the output mentioned below -- everything is fine.

# netstat -al | grep ^udp
udp        0      0 *:bootpc                *:*
udp        0      0 *:631                   *:*
udp        0      0 *:xdmcp                 *:*
udp        0      0 *:tftp                  *:* <-- (look for this line)

Netbooting the SGI machine

Okay, everything is set, DHCP is running as is TFTP. Now it is time to fire up the SGI machine. Power the unit on -- when you see "Running power-on diagnostics" on the screen, either click "Stop For Maintenance" or press ESCAPE. You'll be presented with a menu like the following. Enter the commands as shown below.

        Running power-on diagnostics

System Maintenance Menu

1) Start System
2) Install System Software
3) Run Diagnostics
4) Recover System
5) Enter Command Monitor

Option? 5
Command Monitor. Type "exit" to return to the menu.
>> bootp(): root=/dev/ram0

From this point, the machine should start downloading the image, then, roughly 20 seconds later, start booting Linux. If all is well, you should be dropped at the Busybox ash shell as shown below, where you can move on to (Configuring Your Network).

init started:  BusyBox v1.00-pre10 (2004.04.27-02:55+0000) multi-call binary

Gentoo Linux; http://www.gentoo.org/
 Copyright 2001-2004 Gentoo Technologies, Inc.; Distributed under the GPL

 Gentoo/MIPS Netboot for Silicon Graphics Machines
 Build Date: April 26th, 2004

 * To configure networking, do the following:

 * For Static IP:
 * /bin/net-setup <IP Address> <Gateway Address> [telnet]

 * For Dynamic IP:
 * /bin/net-setup dhcp [telnet]

 * If you would like a telnetd daemon loaded as well, pass "telnet"
 * As the final argument to /bin/net-setup.

Please press Enter to activate this console.

Troubleshooting.

If the machine is being stubborn and refusing to download its image, it can be one of two things, (1) you've made a blunder somewhere, or (2) it needs a little gentle persuasion. (No, put that sledge hammer down!) Here's a list of things you can check:

• dhcpd is giving the SGI Machine an IP Address. You should see some messages about a BOOTP request in the system logs. tcpdump is also useful here.
• Permissions are set properly in your tftp folder (typically /tftproot -- should be world readable)
• Check system logs to see what the tftp server is reporting (errors perhaps)

If you've checked everything on the server, and you're getting timeouts, etc on the SGI machine, try typing this into the console.

>> resetenv
>> unsetenv netaddr
>> unsetenv dlserver
>> init
>> bootp(): root=/dev/ram0

1.  Alternative Method: Gentoo/MIPS SGI LiveCD

Overview

On Silicon Graphics machines, it is possible to boot from a CD in order to install operating systems. (This is how one installs IRIX for instance) Recently, images for such bootable CDs to install Gentoo have been made possible. These CDs are designed to work in the same way.

At the moment the Gentoo/MIPS Live CD will only work on the SGI Indy, Indigo 2 and O2 workstations equipped with R4000 and R5000-series CPUs, however other platforms may be possible in future.

You can find the Live CD images for download on your favourite Gentoo Mirror under the experimental/mips/livecd directory.

Burning a Live CD

An important thing to note, the SGI PROM does not understand the ISO9660 format, nor does it know anything about the El Torito boot standard. These CD images are constructed as a SGI disklabel with the boot image in the volume header like a hard drive. Therefore, care must be taken when burning the CD image.

Below is an example command that assumes 24x burning speed on an IDE burner. If you have a SCSI burner for instance, you may want to adjust the dev statement as appropriate. Likewise with the speed option - if you strike troubles, you might want to try dropping the speed.

# bzip2 -d mips-livecd-prototype-rc2-20041027.img.bz2
# cdrecord -vv -pad speed=24 dev=ATAPI:0,0,0 -tao mips-livecd-prototype-rc2-20041027.img

1.  Netbooting on Cobalt Servers

Overview of the netboot procedure

Unlike the SGI machines, Cobalt servers use NFS to transfer their kernel for booting. You boot the machine by holding down the left & right arrow buttons whilst powering the unit on. The machine will then attempt to obtain an IP number via BOOTP, mount the /nfsroot directory from the server via NFS, then try to download and boot the file vmlinux_raq-2800.gz (depending on the model) which it assumes to be a standard ELF binary.

Downloading a Netboot image

Inside http://dev.gentoo.org/~redhatter/mips/cobalt/netboots/ you'll find the necessary boot images for getting a Cobalt up and running. The files you need will have the name nfsroot-KERNEL-COLO-DATE-cobalt.tar -- select the most recent one and unpack it to / as shown below:

# tar -C / -xvf nfsroot-2.6.13.4-1.19-20051122-cobalt.tar

NFS Server configuration

Since this machine uses NFS to download its image, you need to export /nfsroot on your server. If you have not already done so, you'll need to install the net-fs/nfs-utils package.

# emerge net-fs/nfs-utils

Once that is done, place the following in your /etc/exports file. You may set tighter restrictions if you wish.

/nfsroot      *(ro,sync)

Now, once that is done, you may start the NFS server:

# /etc/init.d/nfs start

If the NFS server was already running at the time, you can tell it to take another look at its exports file using exportfs.

# exportfs -av

DHCP Configuration for a Cobalt machine

Now, the DHCP side of things is relatively straightforward. Add the following to your /etc/dhcp/dhcpd.conf file.

subnet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx {
  # ... usual stuff here ...

  # Configuration for a Cobalt Server
  # Set the hostname here:
  host qube {
    # Path to the nfsroot directory.
    # This is mainly for when using the TFTP boot option on CoLo
    # You shouldn't need to change this.
    option root-path "/nfsroot";

    # Cobalt server's ethernet MAC address
    hardware ethernet 00:10:e0:00:86:3d;

    # Server to download image from
    next-server 192.168.10.1;

    # IP address of cobalt server
    fixed-address 192.168.10.2;

    # Location of the default.colo file relative to /nfsroot
    # You shouldn't need to change this.
    filename "default.colo";
  }
}

Start Your Daemons...

At this point, you should be ready to start the daemons. Enter the following:

# /etc/init.d/dhcp start
# /etc/init.d/nfs start

If nothing went wrong in that last step you should be all set to power on the workstation and proceed with the guide. If the DHCP server isn't firing up for whatever reason, try running 'dhcpd' on the command line and see what it tells you -- if all is well, it should just fork into the background, otherwise you'll see 'exiting.' just below its complaint.

Netbooting the Cobalt machine

Okay, everything is set, DHCP is running as is NFS. Now it is time to fire up the Cobalt machine. Hook up your null modem cable, and set the serial terminal to use 115200 baud, 8 bits, no parity, 1 stop bit, VT100 emulation. Once that is done, hold down the left & right arrow buttons whilst powering the unit on.

If all is well, the back panel should display "Net Booting", you should see some network activity, closely followed by CoLo kicking in. On the rear panel, scroll down the menu until you see "Network (NFS)" then press ENTER. You should notice the machine starts booting on the serial console.

elf: 80080000 <-- 00001000 6586368t + 192624t
elf: entry 80328040
net: interface down
CPU revision is: 000028a0
FPU revision is: 000028a0
Primary instruction cache 32kB, physically tagged, 2-way, linesize 32 bytes.
Primary data cache 32kB 2-way, linesize 32 bytes.
Linux version 2.4.26-mipscvs-20040415 (root@khazad-dum) (gcc version 3.3.3...
Determined physical RAM map:
 memory: 08000000 @ 00000000 (usable)
Initial ramdisk at: 0x80392000 (3366912 bytes)
On node 0 totalpages: 32768
zone(0): 32768 pages.
zone(1): 0 pages.
zone(2): 0 pages.
Kernel command line: console=ttyS0,115200 root=/dev/ram0
Calibrating delay loop... 249.85 BogoMIPS
Memory: 122512k/131072k available (2708k kernel code, 8560k reserved, 3424k dat)

If all is well, you should be dropped at the Busybox ash shell as shown below, where you can go onto (Configuring Your Network).

VFS: Mounted root (ext2 filesystem) readonly.
Freeing unused kernel memory: 280k freed
init started:  BusyBox v1.00-pre10 (2004.04.27-02:55+0000) multi-call binary

Gentoo Linux; http://www.gentoo.org/
 Copyright 2001-2004 Gentoo Technologies, Inc.; Distributed under the GPL

 Gentoo/MIPS Netboot for Cobalt Microserver Machines
 Build Date: April 26th, 2004

 * To configure networking, do the following:

 * For Static IP:
 * /bin/net-setup <IP Address> <Gateway Address> [telnet]

 * For Dynamic IP:
 * /bin/net-setup dhcp [telnet]

 * If you would like a telnetd daemon loaded as well, pass "telnet"
 * As the final argument to /bin/net-setup.

Please press Enter to activate this console.

Troubleshooting.

If the machine is being stubborn and refusing to download its image, it can be one of two things, (1) you've made a blunder somewhere, or (2) it needs a little gentle persuasion. (No, put that sledge hammer down!) Here's a list of things you can check:

• dhcpd is giving the Cobalt Machine an IP Address. You should see some messages about a BOOTP request in the system logs. tcpdump is also useful here.
• Permissions are set properly in your /nfsroot folder. (should be world readable)
• Make sure the NFS server is running and exporting the /nfsroot directory. Check this using exportfs -v on the server.