Gentoo Wiki


Please format this article according to the guidelines and Wikification suggestions, then remove this notice {{Wikify}} from the article



Gentoo for Xbox is a complete Gentoo distribution tailored to the Xbox's unique architecture. Gentoo for Xbox is based on code from

This HOWTO will not try to re-create the complete x86 Gentoo Handbook, but will highlight where Gentoo x86 and Gentoo for Xbox differ.

Known Bugs

The xbox-linux 2.6 kernel still has no working FATX driver. Don't use it if you want to keep your FATX partition!

Note: As of 2.6.11 a new FatX driver has been written but it is extremely slow and buggy - data loss/corruption will occur.

System Requirements

To use Gentoo for Xbox, you must have a modified Xbox. You may also want a usb keyboard and mouse (the Xbox controllers use a standard USB 1.1 interface with the addition of one wire to support lightguns. An Xbox-->USB adapter can easily be made), or you can also use ssh for administering the Xbox. Your modified Xbox should have a Cromwell BIOS version 2.31 or later installed. [See for the latest Cromwell BIOS, and details on flashing Cromwell over your Xbox BIOS]


Installing Gentoo for Xbox is as simple as the standard Gentoo install using a LiveCD. There are few, but important, places where the installation differs.

The LiveCD

First, you'll need to download the Gentoo for Xbox LiveCD, which can be found at your local Gentoo mirror site in the /experimental/x86/xbox/livecd/ directory. Download the latest version of it, decompress it, and burn it to your selected media. (DVD-R seems to work the best on picky Xbox DVD drives)...

Booting the LiveCD with Cromwell

When you boot your modified Xbox, the Cromwell BIOS controlls the boot process. Cromwell is loosely based on GRUB. Once Cromwell is loaded you will be presented with a "Menu" of boot options. The options have varied somewhat with each version of Cromwell, but you should see 4 icons. Select the DVD icon to boot from the optical drive.

(If Cromwell recognizes a bootable hard drive, there will be an option to boot from /dev/hda. If /dev/hda is bootable, Cromwell will default to booting from that device after a short timeout.)

There is an issue with the cromwell 2.40 bios (all boxes ?), cromwell 2.40 return that it can't find the linuxboot.cfg and the livecd doesn't boot, if you got this issue, upgrade your bios to cromwell 2.40-r2, more info at "xbox livecd fails to boot, linuxboot.cfg not found" on Gentoo Forums. Another option is to try burning the LiveCD files to a DVD-R. Carlton may have a fix for this.

Booting the LiveCD without Cromwell

If you don't yet have Cromwell, the LiveCD will still boot if you at least have a modchip with one of the various "customised" BIOS images or if your TSOP flash has already been re-flashed with one of these. Understand that the legality of these BIOS images is questionable in most places and it is recommended that you reflash the BIOS with Cromwell as soon as possible. You can do this from the LiveCD using raincoat - upload the Cromwell 2.40-r2 image using SCP (Secure Copy) to the Xbox, making sure that you create a .BIN file of the appropriate size. For example, whilst Cromwell is only 256KB a Duo X2 modchip flash requires a BIOS size of 512KB. You can either pad the 256KB file out to 512KB (there are many tools to do this), or in Windows you can just type copy /b cromwell.bin+cromwell.bin cromwell512.bin Don't make the mistake of padding out a 256KB file when your modchip doesn't need it, and don't try to shrink a 1MB file down to 512KB! As always RTFM regarding your particular modchip. If you will be re-flashing the onboard TSOP, note that the onboard TSOP flash on the 1.1+ version Xbox is a 256KB flash, whilst on the 1.0 it was 1MB.

Note that you need Cromwell if you want to be able to boot Linux directly from a Natively formatted hard disk.

Follow the Handbook

Once the LiveCD has been booted you are in the standard Gentoo LiveCD environment. Installation from here on out follows the x86 Handbook, with a few differences. To highlight the differences I'm going to re-create the Quick Install Reference, and make changes and additions where needed. For more details on a particular step, see the x86 Gentoo Handbook.

This following is based on the Gentoo x86 Quick Install Reference.

Quick Install Reference

The installation ISOs are on the Gentoo Mirrors as noted above.

Boot from the Xbox LiveCD. You'll eventually receive a prompt.

Many Xbox users do not have a keyboard/mouse, and don't plan on getting one. In order to access a console, sshd is configured on the LiveCD. The Xbox will boot using DHCP to obtain a network address, and start sshd.

To Login: use the username root and the password xbox. Please remember to change this to something more secure.

Beginning Settings

Code: Code Listing 1.1: Beginning settings
# passwd      (Change your password now to be more secure during the install)
# date  (Make sure your time and date are correct. If wrong, set it with date MMDDhhmmCCYY)

Disk Setup with Native FS

This section assumes that you want to completely erase the FATX partition (along with all the MS utils) and run a linux only system. If you want to dual boot, see the section below about installing a loopback root FS as a large file on FATX. Alternatively, you can avoid using the hard drive completely and boot across the network from a NFS file server.

  # fdisk /dev/hda (Partition your drive)
  # cfdisk /dev/hda (Partition your drive, easier to read than fdisk /dev/hda)

The recommended setup is a 64 meg boot volume with ext2, a 128 meg swap partition, and the rest for your root partition using ReiserFS. The current LiveCD does not support ReiserFS, so you'd better stick to EXT2, EXT3. Cromwell can boot off ext2/ext3/reiserfs boot partitions.
Note: This apperantly is outdated

If you REALLY want reiserfs, it is possible to boot off a Xebian LiveCD instead of the Xbox LiveCD. When configuring your kernel be sure to add reiserfs support, and emerge the reiserfsprogs. Reiserfs support may be added to the Xbox LiveCD in the future.

Initialise your partitions using mke2fs (Ext2), mke2fs -j (Ext3), mkreiserfs (ReiserFS), mkfs.xfs (XFS), mkfs.jfs (JFS) and mkswap (swap partition). For instance: mke2fs -j /dev/hda3.

You must also mark the boot partition as bootable using fdisk. If you do not do this, it will not be listed in the Cromwell boot menu and you will not be able to boot from it.

Disk Setup with FATX

# mount /dev/hda50 /mnt/fatx (Mount the FATX partition)
# dd if=/dev/zero of=/mnt/fatx/linuxroot bs=1M count=1024 (Make a large file - in this case 1GB)
# mke2fs -j /mnt/fatx/linuxroot (assuming you want to use ext3)
# mount -oloop /mnt/fatx/linuxroot /mnt/gentoo

You can now chroot /mnt/gentoo /bin/bash as in a normal Gentoo install.

To actually boot using this file as your root device you'll need to create an initial RAM disk (initrd).

Make sure your kernel config supports initrd (CONFIG_BLK_DEV_INITRD) and CONFIG_BLK_DEV_RAM_COUNT is 1 or more. Emerge genkernel. Make sure /usr/src/linux points to the correct kernel source directory, and run 'genkernel initrd'. Genkernel will automatically build an initrd image and save it to /boot/initramfs-genkernel-x86-2.6.x.

Alternative to disk setup - network root

This is covered in the Diskless Nodes with Gentoo howto.

Preparing for Installation, Stages

Continue by mounting the partitions and extracting the appropriate stage file. The Xbox LiveCD does not contain a stage file. You will need to download a pentium3 stage file from a Gentoo mirror. Since the xBox Live CD is old the latest stage might not work. Try a 2006 stage instead.

# swapon /dev/hdax               (Activate the swap partition)
# mount /dev/hdax /mnt/gentoo    (Mount the root partition)
# mkdir /mnt/gentoo/boot         (Create the boot mountpoint)
# mount /dev/hdax /mnt/gentoo/boot  (Mount the boot partition)
# cd /mnt/gentoo                 (Go to the mountpoint)

# links            (or download the latest tarball...)

# tar xvjpf stage<your stage>.tar.bz2                (    ... and extract)

(Select a mirror)

# mirrorselect -i -o >> /mnt/gentoo/etc/make.conf

(Copy over nameserver information)

# cp -L /etc/resolv.conf /mnt/gentoo/etc/resolv.conf
# mount -t proc none /mnt/gentoo/proc      (Mount the proc filesystem)
# chroot /mnt/gentoo /bin/bash              (Chroot into the new environment)
# env-update; source /etc/profile           (Load the necessary variables)

(Network-only, non-GRP: update Portage)

# emerge --sync         (update package database)
# emerge portage       (update portage to the latest)

Using the Xbox Profile

To do BEFORE emerge!

Now that we have an updated Portage, we need to update the Profile to use the new Cascaded profiles, and to switch it from Pentium3 to Xbox.

# cd /etc
# rm make.profile
# ln -s ../usr/portage/profiles/default-linux/x86/xbox make.profile

Installing the Base System

Now we install Gentoo:

See Safe Cflags#Celeron (Coppermine) first.

Code: Code Listing 1.3: Installing Gentoo
     (Change USE, CFLAGS and CXXFLAGS. Stage1 users can also change CHOST to i686)
     (These work well for Gentoo for XBOX: 
     CFLAGS="-march=pentium3 -O2 -pipe -fomit-frame-pointer")

# nano -w /etc/make.conf
# cd /usr/portage; scripts/      (Stage1 only: bootstrap system)
(Stage1, Stage2 only: install base system)
# mkdir /etc/portage                   (Limit the number of Locales used by glibc)
# echo "sys-libs/glibc userlocales" >> /etc/portage/package.use
# nano -w /etc/locale.gen            (Enter the locales you want to build)
# emerge -C pam-login; emerge -1 shadow (you need to remove pam-login because it has been merged back into the shadow package)
# emerge system (won't work if you haven't run the previous command!)

if you find any problem with glibc packet, try to select the earliest version of gcc using gcc-config command.

fstab and timezones

Next we set up the necessary information:

Code: Code Listing 1.4: Setting up Configration Files
     (Set timezone information)
# ln -sf /usr/share/zoneinfo/<path to time zone file> /etc/localtime
# nano -w /etc/fstab     (Edit fstab file)

Use the following as a template (don't copy verbatim) for /etc/fstab:

File: /etc/fstab
# <fs>          <mountpoint>    <type>          <opts>                  <dump/pass>
/dev/hdax       /boot           ext2            noauto,noatime          1 2
/dev/hdax       none            swap            sw                      0 0
/dev/hdax       /               reiserfs        noatime                 0 1
/dev/cdroms/cdrom0 /mnt/cdrom   auto            noauto,user             0 0
none            /proc           proc            defaults                0 0
none            /dev/shm        tmpfs           nodev,nosuid,noexec     0 0

Choosing and Installing a Kernel

If you want to use a 2.6.x series kernel, you need to add it to the package.use file:

Code: Code Listing 1.5a: Enable the 2.6.x series kernel for Xbox
# echo "sys-kernel/xbox-sources ~x86" >> /etc/portage/package.keywords

Continue by installing the Linux kernel:

Code: Code Listing 1.6: Installing the Kernel
NOTE: If the method below gives you problems, do the following:

1) cd /usr/portage/sys-kernel

2) ebuild xbox-sources-2.4.29.ebuild merge

3) thats it

The above steps merges the kernel without using emerge xbox-sources. My problem was gentoo kept emergeing
Kernel 2.6 and I didn't want it do to many many problems. This installs 2.4.29 xbox kernel through its ebuild file.

- or -
(for a 2.6.x series kernel)
# emerge xbox-sources
               (for a 2.4.x series kernel)
# emerge xbox-sources-2.4.x
     ((1) manually build your kernel)
# cd /usr/src/linux
# cp kernel.config .config    (kernel.config contains a correct config for the Xbox)
# make oldconfig              (tell make to use the .config as the default answers)
# make menuconfig              (make any changes you want.)
     (   (2) Include VM fs, /proc fs, /dev fs,  /dev fs auto mount at boot)
     (   (3) Compile your kernel)
           (for a 2.4 kernel)
# make dep && make clean bzImage modules modules_install
           (for a 2.6 kernel)
# make && make modules_install
     (   (4) Copy over the kernel)
# cp arch/i386/boot/bzImage /boot; cp /boot
# echo "forcedeth" >> /etc/modules.autoload.d/kernel-2.x (the nVidia NFORCE network card needs the forcedeth module)

Installing Other Tools

Now install other tools you might want:

Code: Code Listing 1.7: Install important system tools
     (Install system logger; choice: sysklogd, metalog, msyslog, syslog-ng)
# emerge syslog-ng

     (Have the systemlogger automatically started at boot)
# rc-update add syslog-ng default

     (Install cron daemon; choice: vixie-cron, dcron, fcron)
# emerge vixie-cron

     (Have the cron daemon automatically started at boot)
# rc-update add vixie-cron default

     (Optional with udev: install hotplug to load USB drivers on the fly)
# emerge hotplug
     (Needed by net.lo if you use udev)
# emerge net-tools

     (Optional: have hotplug automatically started at boot)
# rc-update add hotplug default

     (Non-ext2,ext3 users only; choice: reiserfsprogs, xfsprogs, jfsutils)
# emerge reiserfsprogs

     (Optional: install DHCP client)
# emerge dhcpcd

     (Domain name init script)
# rc-update add domainname default

# emerge devfsd (for 2.4 kernels, not needed for 2.6)
     (Needed for devfs and not installed by default)

If you need specialised kernel ebuilds, now is a good time to install them:

Finalize Settings

Finalise the settings for your Gentoo system:

Code: Code Listing 1.9: Finalise the Configuration Settings

#etc-update (merge config files downloaded by portage)

# passwd                     (Set root password)
                             (Create a user)
# useradd your_user -m -G users,wheel,audio -s /bin/bash
# passwd your_user            (Set password for that user)
                               (Set the system hostname)
# echo mymachine > /etc/conf.d/hostname
                               (Set the system domainname)
# echo > /etc/dnsdomainname
                               (Set the hostsfile, ex:" localhost mymachine")
# nano -w /etc/hosts
                               (Configure basic system settings; follow comments)
# nano -w /etc/rc.conf
Code: Code Listing 1.10: Set up Networking
              (Setup networking; dhcp-users should set iface_eth0="dhcp")
# nano -w /etc/conf.d/net
              (List modules to be loaded at startup)
# nano -w /etc/modules.autoload.d/kernel-<version>
              (Non-PCMCIA only: start networking automatically at boot)
# rc-update add net.eth0 default
              (Only if you have multiple network interfaces:)
                 (1) Create initscripts for each interface)
# ln -s /etc/init.d/net.eth0 /etc/init.d/net.ethx
                 (2) Automatically start at boot if no PCMCIA)
# rc-update add net.ethx default
                 (PCMCIA only: verify /etc/conf.d/pcmcia and load PCMCIA at boot)
# rc-update add pcmcia boot
                 (enable SSH so you can get back in after reboot)
# rc-update add sshd default

The BootLoader

Now install a bootloader.

Cromwell is the Xbox bootloader.

# emerge sys-boot/cromwell
# emerge sys-boot/cromwell-bin (Alternative for prebuilt binaries)

This boot loader needs to be installed somewhere. Your choices are:

Now we need to create a boot configuration file so Cromwell will know what kernel to load.

Code: Code Listing 1.11: Configure linuxboot.cfg
# nano -w /boot/linuxboot.cfg
kernel boot/bzImage
append root=/dev/hda1 splash=silent kbd-reset video=xbox:640x480,nohwcursor devfs=mount acpi=hw

This installs a configuration file for Cromwell in /dev/hda1. If you're booting Cromwell from FATX, install the configuration file in the same directory as your Cromwell binary.

Note that 'root=/dev/hdaX' should match where your final root partition will be mounted. If you configured your disks so that you have the kernel image on /dev/hda1, swap on /dev/hda2 and the root on /dev/hda3, then root=/dev/hda3.

System is done, Reboot

Now unmount all partitions and reboot into your new system:

Code: Code Listing 1.13: Finishing off and installing GUI
     (Exiting the chroot)
# exit; cd /
     (Unmounting partitions)
# umount /mnt/gentoo/boot /mnt/gentoo/proc /mnt/gentoo
     (Reboot; Remove the universal CD from the tray)
# reboot

Post Install

Installing and Configuring Xorg

emerge xorg-x11. With the xbox profile selected you should see a message saying that the xbox patch has been applied. The install includes an example configuration for the Xbox. Probing the hardware with X -configure will probably crash the Xbox. Get a configuration file from Xbox Linux.

Getting Xbox Hardware to Work

The joypad/stick will appear as a USB HID device to linux, and should work as a normal joystick visible at /dev/js0.

The remote control works fine with Freevo and MythTV. Just set LIRC_DEVICES="xboxusb" in /etc/make.conf, and then emerge lirc. If you're using the Xbox profile (which you should be) the correct config file will also be installed. Lirc-0.8.0 should work with the latest kernels.

You can monitor the system temperature and control the fan speed using the fanctl daemon. The suite of tools which fanctl is part of also allows you to control the system LED lights and software-eject the DVD tray. Note that these tools are not part of the Portage tree.

If you are having trouble connecting USB mass storage devices to your Xbox, run your kernel make menuconfig again and make sure the SCSI system and USB support are set as built into the kernel rather than modules. Obviously you will need to compile the kernel again using make && make modules_install and then copy the new kernel file to the boot partition. This is not really a fix for a problem as such, just a suggestion to save you the hassle of loading the modules manually.

Installing Alsa

You can either install alsa as part of the 2.6 xbox-sources kernel, or 'emerge alsa-drivers'. The alsa driver can't autodetect the Xbox hardware, so force it with {{{1}}}. You can add snd-intel8x0 xbox=1 to /etc/modules.autoload.d/kernel-2.x to load the module on boot.

Xbox Specific Utilities

There are a number of utilities available for emerging:

app-cdr/extract-xisoExtract and create optimised ISO images
app-cdr/xbisoExtract ISO images
app-cdr/xdvdfs-toolsTools for manipulating ISO images
sys-boot/raincoatFlash the xbox boot chip


See also

Where to Find Help

Alternative ebuilds

Retrieved from ""

Last modified: Mon, 08 Sep 2008 11:06:00 +0000 Hits: 80,666