Archive:HOW-TO:Install Gentoo and XBMC on Apple TV 1

From Official Kodi Wiki
Jump to: navigation, search

This page or section has not been updated in a long time, no longer applies, refers to features that have been replaced/removed, and/or may not be reliable.

This page is only kept for historical reasons, or in case someone wants to try updating it.

See also: HOW-TO:Install XBMC on Apple TV 1 (Linux)

Updated for the stable 10.0 stable build

These instructions will help you on your way to getting Gentoo installed on your Apple TV. This guide is for a total ATV overhaul -- which is to say replacing the OSX-lite ATV OS with Gentoo. As such it has the possibility of totally toasting your pretty silver box. These steps do NOT require you to crack open your ATV and slave up its disk to an existing pc. This is of course an option, but IMHO, totally unnecessary.

Most of this guide was stolen right off I give full praise and credit to these guys. atv-bootloader is a truly awesome little bit of work. This guide assumes you are comfortable with a Gentoo command-line installation and kernel configuration, telnet/ssh connections, network basics, partition/disk schemes, etc. If terms like "dd", "mbr", "efi" and "parted" don't mean anything to you, you should probably close this document and go grab a Ubuntu ISO. Not that I don't love Ubuntu :-)

You will also need an existing linux machine (or, yes, OSX would work too). This Linux machine will be used to build the initial ATV-Bootloader USB stick, as well as telnet into your atv during the process. I used a Gentoo box, and thus these instructions will be geared in that direction. Keep in mind some part may deviate, depending on your distro.

Your ATV and linux machine will need to be on the same LAN with dhcp setup (should be a no brainer)

1 Create an AppleTV Patchstick

(not to be confused with the atv-bootloader stick)

Head on over to and download whatever flavor of the patchstick tool suites your OS. Extract it to a directory and run it. It will download a new version of the ATV firmware for you, put it in a juicer and pop out a nice little .img file for you to put on a USB drive. It will also produce you your very own boot.efi file. Hold on to this file, it will be important later.

2 Create an ATV-Bootloader USB Stick

All the linux commands I've listed here should be run as root, unless otherwise noted

On your linux machine, get your distros copy of GNU Parted. On Gentoo, the package is called parted, so;

emerge -v parted

You will also need HFS+ tools. Portage has got a package called sys-fs/hfsplusutils, but I found it to suck. Your best bet is to grab the tar off the atv-bootloader site, do the following as your root;

cd ~	
tar -xzf hfs_support-1.0.tar.gz
cd hfs_support/

You'll now have your own copies of various hfsp utilities you will need moving forward. Get an empty usb drive of at least 512mb and plug it into your Linux machine, lets assume it gets assigned to device node /dev/sdb The following commands zero out the device then create and format the usb partitions:

dd if=/dev/zero of=/dev/sdb bs=4096 count=1M
partprobe /dev/sdb
parted -s /dev/sdb mklabel gpt
parted -s /dev/sdb mkpart primary HFS 40s 69671s
parted -s /dev/sdb set 1 atvrecv on
partprobe /dev/sdb
mkfs.hfsplus -v Recovery /dev/sdb1
cd ~
mkdir atvbootloader
mount /dev/sdb1 atvbootloader/

Now download and copy over the atv-bootloader files;

tar -xzf recovery-0.6.tar.gz
cp -arp recovery/* atvbootloader/

That disk is now set up, so copy over that handy boot.efi that the Patchstick util found for you. If you created the patchstick on windows you'll need to copy the boot.efi file over to your linux machine, then copy it to the bootloader stick. You can use PSCP, ftp, or another flash disk, whatever you want. Just make sure it ends up on your atv-bootloader disk:

cp -ap boot.efi atvbootloader/

Now edit the boot.plist file from the recovery software to drop you to a command prompt. I'm a vi-guy, but you can use nano or whatever you want:

vi atvbootloader/penboot/

Change one of the last lines in that file to read:

<string>atv-boot=none video=vsesafb</string>

Save and quit vi (:wq [enter]), unmount your usb atv-bootloader.

You've now got an awesome little usb drive that will boot your appletv to a live linux installation. W00t.

3 Backup your internal ATV Hard Drive

Boot your AppleTV to your new atv-bootloader usb drive. You may need to hold down the remote's [-] and [Menu] buttons at boot to force it to scan for usb devices.

atv-bootloader should load up after a minute or so and drop you at a login prompt.

You can login with root/root and do everything locally with a USB keyboard if you wish, but using telnet is much easier.

Gentoo does not 'ship' with telnet tools, so emerge them:

emerge -v netkit-telnetd

Then connect to your atv (this does not have to be done as root on your client machine):

telnet [your ATV's IP]

Again, root/root for passwords.

Figure out which of the device nodes represents your LOCAL disk on the ATV. I've had it map as both sda and sdb on occasions, so I can't definitively tell you which is will be. I assume that your local disk has detected as /dev/sda for the balance of this guide.

At this point, you have two options: Lazy and Correct.

The Lazy (and slow) way to take a backup of your ATV is to plug in an external hard disk (lets assume its partition is /dev/sdc1) and run

mkdir /mnt/backup/
mount /dev/sdc1 /mnt/backup/
dd if=/dev/sda | gzip > /mnt/backup/atv-backup.dd.img.gz

That will take a complete bit-for-bit backup of your disk. It will pipe it through gzip, so you will get good compression if most of your disk is empty, but if you have your local disk full of media, make sure your target external drive is at LEAST the size of your ATV's internal drive.

The far more 'correct' way to do an ATV backup is detailed on the atv-bootloader site. Its best to just follow the official guide on this page, as I have zero customization to add:

When you are done with the Backup section of that page, come back here and continue on...

4 Partition your internal ATV Hard Drive

Now that everything is backed up, you can create the new partition structure for your Linux installation. This may seem confusing, but it is sort of straight forward when you understand what is going on under the hood. On your local ATV disk you are essentially creating a partition structure to support two separate OS installations; One for a local copy of the atv-bootloader to live in, the other for your Gentoo installation. When your ATV boots, its EFI needs to talk to the atv-bootloader kernel/os. After this pow-wow is done, atv-bootloader hands the machine off to your Gentoo installation. Makes sense, right? Good.

Again, make sure /dev/sda is your local ATV hard drive.

Zero out /dev/sda so its guid changes...

dd if=/dev/zero of=/dev/sda bs=4096 count=1M

create initial gpt structures

parted -s /dev/sda mklabel gpt

We need to find out how large our disk is, run this:

parted -s /dev/sda print

This should spit out something like below:

Model: ATA WDC WD1600BEVE-4 (scsi)
Disk /dev/sda: 160GB

Here it tells me my local disk (/dev/sda) is 160GB, hurrah for me. This makes 160GB the end of our disk, remember this.

You're now going to create the three partitions required for the atv-bootloader.

parted -s /dev/sda mkpart primary fat32 40s 25M
parted -s /dev/sda set 1 boot on
parted -s /dev/sda mkpart primary HFS 25M 50M
parted -s /dev/sda set 2 atvrecv on
parted -s /dev/sda mkpart primary HFS 50M 75M

At this point you've created the partitions nessesary for installing the local copy of the atv-bootloader. The next could partitions you make will be for Gentoo and can be whatever sizes you like, though I recommend at least 1gig of swap.

I've made my root partition about 16GB and swap 1000MB, create those now:

parted -s /dev/sda mkpart primary ext3 75M 16GB
parted -s /dev/sda mkpart primary linux-swap 16GB 17GB

You'll notice that yes, this leaves a ton of my disk unused. I stream everything, so this doesn't bother me. You can always format the remain space and mount it up as a storage partition:

parted -s /dev/sda mkpart primary ext3 17GB 160GB

Sync up your partition tables

partprobe /dev/sda

Get everything formatted:

mkfs.msdos -F 32 -n EFI /dev/sda1
mkfs.hfsplus -v Recovery /dev/sda2
mkfs.hfsplus -v OSBoot /dev/sda3
mkfs.ext3  -b 4096 -L Linux /dev/sda4
mkswap /dev/sda5

Time to see if we got everything correct:

parted -s /dev/sda print

This should spit out something very similar to this:

Model: ATA WDC WD1600BEVE-4 (scsi)
Disk /dev/sda: 160GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Number  Start   End    Size    File system     Name     Flags
1      20.5kB  25.0MB  25.0MB  fat32           primary  boot
2      25.0MB  50.0MB  25.0MB  hfs+            primary  atvrecv
3      50.0MB  75.0MB  25.0MB  hfs+            primary
4      75.0MB  16.0GB  15.9GB  ext3            primary
5      16.0GB  17.0GB  1000MB  linux-swap(v1)  primary

Ensure the 'Flags' section is the same as above and that your first three partitions (at least) match mine.

That concludes all the partition setup that is needed. The next step is to install a LOCAL copy of the atv-bootloader magic on to the ATV's hard disk (remember, up until now we've been opperating in the live environment)

5 Install the atv-bootloader onto the internal disk

This should all look somewhat familiar as we did close to the same procedure earlier when creating the initial ATV-bootloader USB stick. This installation will be the OS the ATV actually boots to initially. Once it succeeds, then it hands things over to Gentoo.

Pull the atv-bootloader recovery files off of the repo:

cd ~
tar -xzf recovery-0.6.tar.gz

Create a mount points for the recovery stuff and mount everything up:

mkdir /mnt/osboot
mkdir /mnt/recovery
fsck.hfsplus /dev/sda2
mount /dev/sda2 /mnt/recovery
fsck.hfsplus /dev/sda3
mount /dev/sda3 /mnt/osboot

Copy the atv-bootloader files over

cp -arp recovery/* /mnt/osboot/
cp -arp recovery/* /mnt/recovery/

Copy over the boot.efi file which should still be on the atv-bootloader USB flash disk:

mkdir /mnt/bootloader
mount /dev/sdb1 /mnt/bootloader
cp -ap /mnt/bootloader/boot.efi /mnt/osboot
cp -ap /mnt/bootloader/boot.efi /mnt/recovery

Unmount everything:

cd ~
umount -a

Wham Bam! You now have an AppleTV with the atv-bootloader installed on it. At this point you can continue on to installing Gentoo from within the usb-live environment. OR, you can reboot, pop out your atv-bootloader live usb stick and let the ATV boot from its internal copy of atv-bootloader. I'd recomend rebooting and using the now-onboard copy of atv-bootloader. This prevents any more device node confusion as well as double checking that your partition/boot structure is set up correctly.

When you reboot, you should get dumped to the familiar atv-bootloader login prompt. root/root to log in, or shoot in via telnet from your existing linux machine. If you did not get sent to a login prompt, something went screwy somewhere. Boot back to the atv-bootloader live stick and double check all the partitions and files to make sure everything got created and copied where it is supposed it be.

If it booted correctly, you can move on to.....

6 Installing Gentoo

At this point there are a few directions you can go for the install env.

You pop in a Gentoo live-usb stick and kexec over to the liveusb kernel. Or you can simply build your Gentoo installation within the existing atv-bootloader env. I recommend the latter as it is less work, and all the tools you need are available in this live-usb. I may gloss over some of the more basic Gentoo setup aspects here, so I recomend you head over to and give the handbook a quick look over to get the general refresher on whats going on. The atv-bootloader is solid and should detect and set up all the basics (network, etc).

6.1 Basic Gentoo Environment

All read up? Awesome! Away we go.

atv-bootloader should detect your local disk as /dev/sda, so go ahead and create your mount point:

mkdir /mnt/Gentoo

You've already partitioned/formatted everything so you can go ahead and mount up your Gentoo root partition:

mount /dev/sda4 /mnt/Gentoo
mkswap /dev/sda5
swapon /dev/sda5

Hop into your install directory:

cd /mnt/Gentoo

I don't know about anybody else, but for whatever reason DNS does not work for me from the atv-bootloader env. Maybe I'm crazy. Who knows. All this means is that when you need to grab a source somewhere, you need to do it via IP. has a list of all current Gentoo mirrors. Pick your favorite and the lookup its IP address. Write it on your forearm for future reference.

Check the date:


If it isn't right, fix it with: (Month, Day, hour, minute and Year)

date MMDDhhmmYYYY 

Grab the Gentoo installation stage3:


Note: Download the three files named "stage3-i686-########" there should be a tar.bz2, a .CONTENTS and a .DIGESTS. Download ALL THREE.

Get the latest Gentoo Portage tree and its hash... you can use wget here since the latest portage tree is uniformly named across mirrors:


Check the hashes of your two files

md5sum -c stage3-i686-########.tar.bz2.DIGESTS 

It should spit back verification like this:

stage3-i686-20100921.tar.bz2: OK
stage3-i686-20100921.tar.bz2.CONTENTS: OK

Check your portage tar:

md5sum -c portage-latest.tar.bz2.md5sum 

Which should come back with:

portage-latest.tar.bz2: OK

Note: During my install I could not, for the life of me get a solid copy of the current stage3. It just wouldn't verify against its hash. After hours of pulling from diff mirriors, I made the executive decsion to try and procede anyway. It turned out fine. If you have the same problem, you may be able to safely use what you've downloaded. However, it is ALWAYS SAFER to use a stage3 and portage tree that have checked out against their respective hashes.

Ehem...back to the show:

Extract your Stage3: (make sure you are in /mnt/Gentoo)

tar -xvjpf stage3-i686*.tar.bz2

It will take a minute, when it is done, extract portage and make an overlay directory:

tar -xvjf /mnt/Gentoo/portage-latest.tar.bz2 -C /mnt/Gentoo/usr
mkdir /usr/local/portage

This will take a longer minute. Get a juice box.

Copy your broken resolve.conf into Gentoo:

cp -L /etc/resolv.conf /mnt/Gentoo/etc/

Mount up the dev and proc systems.

mount -t proc none /mnt/Gentoo/proc
mount -o bind /dev /mnt/Gentoo/dev

Funny story: It seems that, for reasons unknown, binding /dev doesn't like to work for most people, myself included. It barks back with:

mount: mounting /dev on /mnt/Gentoo/dev failed: Invalid argument

Thankfully, because the stage3 contains basically every device node you could ever need, you -shouldn't- need this for a successful installation.

6.2 Chroot in and Edit Environment

With /proc and (hopefully) /dev successfully mounted, chroot into and update your new env:

chroot /mnt/Gentoo /bin/bash
source /etc/profile
export PS1="(atvchroot) $PS1"

Set your root password:


Remember it!

6.2.1 Make.conf and USE Flags

You need to setup your make.conf. I've attached one below that I know works. Feel free to modify the use flags I've specified, but do so at the risk of nothing working :-)

Xett's make.conf:

CFLAGS="-O2 -march=pentium-m -pipe -fomit-frame-pointer"
USE="X -gnome -kde -qt3 -qt4 -gtk -gtk2 -ipv6 cifs xvid opengl xv threads java jpeg png nsplugin bzip2 ffmpeg ftp gif lame matroska mplayer quicktime usb vim-syntax dts ssl screensaver alsa mmx sse sse2 mp3 mad dbus branding -cups audio video x264"
INPUT_DEVICES="keyboard mouse evdev"
VIDEO_CARDS="vesa nvidia"
LIRC_DEVICES="macmini devinput"
#This is the IP for the site, in case DNS STILL can't figure itself out

Save the above config to /etc/make.conf

Several things to note in here:

  1. my -march flag is set for pentium-m. If you are on GCC v4.2 or later, you can use -march=native instead.
  2. PORTAGE_NICENESS is set to give emerges low-priority. Though I still wouldn't recomend trying to watch movies and remerge your world :-)
  3. ACCEPT_KEYWORDS is set for ~x86, which is the 'unstable' branch. I always use this, as it allows you access across the board to the latest builds of most packages.
  4. My USE flags: The ones I use assume you aren't going to try and run KDE or Gnome. Don't. RAM is limmited on the ATV and these WMs will kill you.
  5. LIRC_DEVICES are specified here to get the AppleTV's remote working. More on Lirc later.
  6. Be sure to change your GENTOO_MIRROR to match the IP of whatever your fastest one is. Mine is the MTU mirror.

If (AND ONLY IF) you are an svn-build user, you need to set a few more flags for xbmc specifically, so do that with these commands:

echo "=media-tv/xbmc-9999" >> /etc/portage/package.unmask
echo "=media-tv/xbmc-9999 **" >> /etc/portage/package.keywords
   #If you want remote/webserver support:	
echo "media-tv/xbmc webserver" >> /etc/portage/package.use

Big -caution- time. Using the 9999 branch of the xbmc package will pull directly from svn. This is awesome in the sense that it builds the latest svn version. But its bad in the sense that these versions are sometimes unstable. You are probably better off using a stable beta. To go this rout, omit all three of the commands above and proceed on through the guide.

6.2.2 System config and Update

I'm ommiting the setup of your networking and several other "key" parts of a Gentoo install. Because Gentoo is launched via kexec during a real boot, most of it is undeeded. However, there are a few things that need tweaking. Additionally, your whole package structure needs updated. Lets do it;

Upade your Locale:

nano /etc/locale.gen

Un-comment wherever you are. Me, being in the N.E. US, uncommented these two:

en_US ISO-8859-1
en_US.UTF-8 UTF-8

Timezone: Figure out what timezone fits you from the output of this list:

ls /usr/share/zoneinfo

Then copy over whatever one you use. For me:

cp /usr/share/zoneinfo/America/New_York /etc/localtime

Time to sync up portage with the live tree:

emerge --sync

If it ends the sync with something about there being an update to portage, do it:

emerge -v portage

Next, pull down a few useful packages:

emerge -v gentoolkit pciutils dhcpcd

When it is done, you have a few options. You can leave your install as it is, unupdated, and move on to installing and configuring a kernel. Or you can update everything now and save yourself the time later on. Updating everything now also ensures you have a clean, valid installation free of the glitchy package-dependency issues that can be a problem in Gentoo.

If you wish to update, do so with these:

emerge -uvDN system


emerge -uvDN world

The etc-update commands issued after each large emerge are needed to merge in the /etc/ config updates that come with various packages. Because this is a fresh installation, you may be ok going with the evil "-5" answer. However, if you are going to run etc-update, you should read up on it in the Gentoo handbook so you know what you are doing.

Since we are going from an old version of the stable tree to the newest version of the unstable tree, there will be a TON to update. This will take literally, hours. You may also have collisions/blocks. Most blocks are caused by much older versions of apps blocking newer ones. It is usually safe to first pull the source of the new package:

emerge -f package-that-is-being-blocked

Un-merge the blocking package:

emerge -C package-that-is-blocking

Then retry emerging system or world.

After you have successfully remerged both system and world, run the reverse dependency rebuilder to fix any dependency issues:


If revdep comes back clean you now (idealy) have a flawless Gentoo enviornment that is totally updated and free of dependency issues. Hurrah!

6.3 Kernel Config

atv-bootloader is awesome, but we need our own kernel with all the modules we need. I recomend using Gentoo-sources instead of vanilla-sources. If you the latter, godspeed, but this guide will focus on the Gentoo patched sources. Emerge them:

emerge -v Gentoo-sources

As of this writing, the current unstable kernel is 2.6.35-r5

I could include my .config file, which is configured to include all the drivers you need to get things rolling. But you said you were comfortable with kernel configs, so get to it! Use lspci to get your systems info, then jump right in:

cd /usr/src/linux
make menuconfig

Here are the critical modules you need built in, doing a / search for these will get you their tree locations :

Ethernet adapter
RealTek RTL-8129/8130/8139 PCI Fast Ethernet Adapter support
Disk driver
Intel ESB, ICH, PIIX3, PIIX4 PATA/SATA support
File Systems (I include CIFS because I stream everything from a samba share
<*> Ext3 journalling file system support
[*] Ext3 extended attributes
[*] Ext3 POSIX Access Control Lists
[*] Ext3 Security Labels
<M> Apple Macintosh file system support (EXPERIMENTAL)
<M> Apple Extended HFS file system support
<M> CIFS support (advanced network filesystem, SMBFS successor)
[*] CIFS statistics
[*] Extended statistics
[*] Support legacy servers which use weaker LANMAN security
[*] Kerberos/SPNEGO advanced session setup
[*] CIFS extended attributes
[*] CIFS POSIX Extensions
[*] Enable additional CIFS debugging routines
[*] DFS feature support
Intel HD Audio
[build this as a module with all sub-components built in]
-- Support for frame buffer devices
[*] VESA VGA graphics support
[*] EFI-based Framebuffer Support
VGA NOTE: Do NOT include the in-kernel nvidia drivers! Vesa/efi only!

Remote/LIRC Stuff
Generic HID support
USB Human Interface Device (full HID) support
/dev/hiddev raw HID device support
Compile Remote Controller keymap modules
If you have one of these do NOT use the in-kernel driver. It blows.

Once you've saved your config and exited, compile your kernel and its modules:

make && make modules_install

Copy your compiled kernel over to your /boot dir:

cp arch/i386/boot/bzImage /boot/TESTING

6.4 Boot Setup and Options

You now need some way for the atv-bootloader to figure out which kerenl it should kexec over to on boot. It will search for a grub menu.lst file automatically, so that is the easiest way. Install grub:

emerge -v grub

Assuming you used the partition scheme I described earlier, edit your grub.conf

nano /boot/grub/grub.conf
to look like this:
default 0
timeout 3
title ATV-Gentoo Linux Testing
root (hd0,3)
kernel /boot/TESTING video=vesafb root=/dev/sda4

Save that file, all done. There is no need to actually install grub into the MBR of the disk as the atv-bootloader deals with all of that.

Edit your /etc/fstab file to reflect your partition layout. Mine looks like this:

# <fs>			<mountpoint>	<type>		<opts>		<dump/pass>
/dev/sda4		/		ext3		noatime		0 1
/dev/sda5		none		swap		sw		0 0
shm			/dev/shm	tmpfs		nodev,nosuid,noexec	0 0

Pretty simple...Just make sure the partition numbers and formats are correct. And add on any you may have made (like a media partition)

You will need to set up some init scripts to make sure all the important stuff starts when you boot your ATV for the first time:

rc-update add net.eth0 default
rc-update add sshd default
rc-update add dhcpcd default
rc-update add dbus default

Create a user

You should make a non-privilaged user account to run your media center under. If you add him to the 'wheel' group, then that user can su over to root. My user here is mrmedia:

useradd -m -G users,audio,video,usb -s /bin/bash mrmedia

Give him a password:

passwd mrmedia

Go ahead and use exit to drop out of your chroot and unmount all your partitions:

cd ~
umount /mnt/Gentoo/dev
umount /mnt/Gentoo/proc
umount [anything else you may have mounted inside /mnt/Gentoo]
umount /mnt/Gentoo

The last thing to do is install the magic atv-bootloader mbr. Grab it from the folks at the project and then stamp it over your local disk's current mbr:

cd ~

Install it over top your existing disk:

dd if=mbr_fast-1.0.bin of=/dev/sdb bs=512 count=1

Reboot your AppleTV;


It should take a few seconds, then show Tux on the AppleTV. It will boot the atv-bootloader install, then it will find your grub's menu.lst and splice over to whatever kernel you have listed in there. If everything goes as planned, you should end up at a happy Gentoo login prompt! Congratulations!

7 Install Packages

A Gentoo install is extremely custom. You can add whatever you feel like. In the next few sections I'm going to outline the things I use and what you will need for a pretty bare-bones xbmc box.

7.1 Basic Stuff

There are a handful of packages I put on almost every Gentoo build I do. I find them to be extremely helpful for any build and critical for many situations.

A system log daemon. Critical. You need this.
A totally superior (to nano) text editor. Crucial for editing confs
Magic. Particuarly useful if you do most of your work via ssh, screen will allow you to start long emerges and disconnect ssh without dropping the emerge process.
Index and easily search portage for packages
The ftp server to have. Easy to install, configure, etc.
The network time protocol daemon and client, crucial for obvious reasons
You should know why this is so key
system load monitor
CRON manager, crucial

Emerge all these in one shot with:

emerge -av syslog-ng vim screen eix vsftpd ntp parted htop vixie-cron

When that completes you will have to add several of them to your default run-level:

rc-update add syslog-ng add default
rc-update add ntp-client add default
rc-update add ntpd add default
rc-update add vixie-cron add default

vsftpd will need some configuration prior to starting it. It isn't hard, check out for a great HOW-TO. After you create a conf file, add vsftpd to the default run level:

rc-update add vsftpd default

Start all these services with:


7.2 Xorg

For an XBMC media-center build, only a couple X related packages are needed:

  • xorg-x11
  • nvidia-drivers
  • eterm
  • mesa-progs
  • fluxbox

I pull eterm because it is a little nicer than xterm, which ships with xorg-x11. You can install whatever low-dependency terminal you like. Stay AWAY from gnome-terminal and the kde terminal.

Installing fluxbox is optional, but I highly recommend it. Flux will give you something to fall back to should xbmc crash, and a framework in which to debug and work. It also is less than 1mb of source code and uses almost no ram while running. These instructions will assume you will install fluxbox.

Go ahead and emerge all these packages:

emerge -v xorg-x11 nvidia-drivers eterm fluxbox mesa-progs

When that finishes up, you will need to load up the nvidia display module, and switch opengl interfaces:


If it isn't loaded...

modprobe nvidia

Switch to the nvidia OpenGL interface

eselect opengl set nvidia

Next you're going to need a working xorg.conf. Thankfully, all us here at this party have the exact same hardware. This means you can copy and paste most of my config into your own /etc/X11/xorg.conf file. I actually based mine off of Davilla's posted conf file. Cheers Sir.

Alternatively you can run

X -configure

as Root and it will automagically probe and create you your own OK xorg.conf file.

This is my xorg.conf and will almost certainly work for you with two exceptions: Keyboard and monitor. These will need tweaking to align with whatever hardware you are using.

Section "ServerLayout"
	Identifier     " Configured"
	Screen      0  "Screen0" 0 0
	InputDevice    "Mouse0" "CorePointer"
	InputDevice    "Keyboard0" "CoreKeyboard"

Section "Files"
	ModulePath   "/usr/lib/xorg/modules"
	FontPath     "/usr/share/fonts/misc/"
	FontPath     "/usr/share/fonts/TTF/"
	FontPath     "/usr/share/fonts/OTF/"
	FontPath     "/usr/share/fonts/Type1/"
	FontPath     "/usr/share/fonts/100dpi/"
	FontPath     "/usr/share/fonts/75dpi/"

Section "Module"
	Load  "dbe"
	Load  "glx"
	Load  "record"
	Load  "extmod"

Section "InputDevice"
	Identifier  "Keyboard0"
	Driver      "evdev"
	Option	"Protocol"	"evdev"
	Option 	"Device"	"/dev/input/by-id/usb-Microsoft_Microsoft��_Nano_Transceiver_v1.0-event-kbd"
	Option	"XkbModel"	"evdev"	

Section "InputDevice"
	Identifier  "Mouse0"
	Driver      "mouse"
	Option	    "Protocol" "auto"
	Option	    "Device" "/dev/input/mice"
	Option	    "ZAxisMapping" "4 5 6 7"

Section "Monitor"
	Identifier   "Monitor0"
	#VendorName   "Monitor Vendor"
	ModelName    "Monitor Model"
	Option	"DPMS"

Section "Device"
	Identifier  "Card0"
	Driver      "nvidia"

Section "Screen"
    Identifier     "Screen0"
    Device         "Card0"
    Monitor        "Monitor0"
    DefaultDepth    24
    Option         "DPI" "100x100"
    Option         "UseEvents" "1"
    Option         "AddARGBVisuals" "1"
    Option         "AddARGBGLXVisuals" "1"
    Option         "UseDisplayDevice" "DFP"
    Option         "NoLogo" "True"
    Option         "Coolbits" "1"
   SubSection     "Display"
        Depth       24
        Modes      "1920x1080"

Section "Extensions"
	Option	"Composite" "Disable"

With your /etc/X11/xorg.conf file all set up, X should start. But first, we need to tell X what to do when it starts, for both our users (root and mrmedia). In this case, start FluxBox.

Run these as root:

echo "exec startfluxbox" >> ~/.xinitrc
su mrmedia
echo "exec startfluxbox" >> ~/.xinitrc

Now with a little luck if, as root, you run


You should get a fluxbox desktop. Open up Eterm and run

glxinfo |grep direct

The output should look like this:

[email protected] ~ $ glxinfo |grep direct
direct rendering: Yes

Next, load up GLXGears to confirm everything is hunky-dory:


That should bring up the three happy gears, spinning smoothly.

If all that worked as root, drop out of X and fluxbox (right click on the desktop -> Exit) switch over to your media-center user and start up X:

su mrmedia

Assuming X starts (which it will), open Eterm and run the same two tests we ran as root:

glxinfo |grep direct

If you've had green lights this whole way, then your X environment is all set up and functional.

7.3 ALSA

Presumably you want sound to come out of your media center. The Advanced Linux Sound Architecture is your friend. Because we built the correct sound card modules right into our system when we configured the kernel, alsa is a breeze to get working. First pull the utilities:

emerge -v alsa-utils

When that finishes, run:


Hit OK at the first screen to pop up. It will probe your system for available cards and find your hda-intel. Make sure it is highlighted and hit enter. It will ask if you want to modify alsa.conf. Answer Yes. A couple of confirmations and you should be done.

Add ALSA to your run-level and start it with:

rc-update add alsa-sound default
/etc/init.d/alsa-sound start

The ALSA service should start up without complaint. Launch alsamixer and mute/unmute whatever channels you are going to use. M is mute, by the way.

7.4 Installing XBMC

FINALLY! This is actually the easy part :-/ Before you proceed though, a note on CrystalHD:

If you have the Broadcom CrystalHD decoder installed already and want to use it in XBMC, you need to complete the CrystalHD section of this guide below. CrystalHD support must be built prior to building the XBMC ebuild, at least in my experience. Who knows if this will change or if I am wrong -- Better safe than sorry. If you are not a CrystalHD type, fast forward over that to the "Basic Config" section

7.4.1 CrystalHD

Do not be tempted to use the in-kernel driver for this. As of 2.6.35r5 it does not work. You want to grab the svn of the latest source by the xbmc crew. As root.... Get the source:

cd ~
svn checkout crystalhdsource

Configure, build and install the CrystalHD module:

cd crystalhdsource/crystalhd/linux_lib/libcrystalhd/
make install
cd ../../driver/linux
make install

On my box, Gentoo doesn't auto-detect and load the CHD driver by default, so add it to your module list:

vi /etc/conf.d/modules

You want to add this line to the very end of that file:


You should now be able to reboot and Gentoo will load that module automatically. Alternatively, you can load it manually now:

modprobe crystalhd

7.4.2 Basic config


Now that Dharma has gone stable, this whole process is much easier. However, it will depend on whether you have previously used this guide or not. Depending on your situation, follow the appropriate section below:

If you have a previous, beta (bug) ebuild built of XBMC:

First, unmerge the existing beta install:

emerge -C xbmc

Let this finish. Once it has, go into your portage overlay and delete the xbmc overlay:

cd /usr/local/portage
rm -Rv media-tv/xbmc

At this point, I also deleted my user's ~/.xbmc folder. This worked for me as my scraping and index was all mucked up. Be aware that if you do this, you will lose all your addons/preferences/scrapes.

rm -Rv /home/yourxbmcuser/.xbmc

Now sync up portage:

emerge --sync

If you want the webserver portion of XBMC to work, you need to add that use flag:

echo "media-tv/xbmc webserver" >> /etc/portage/package.use

When it is finished you can install XBMC by running:

emerge -av xbmc

It will ask you to confirm the installation. Make sure it is installing "media-tv/xbmc-10.0" then hit enter to confirm installation.

If this is the first time you're trying this guide (no previous XBMC install):

Make sure you have the ~x86 branch of portage unmasked and sync up:

emerge --sync

If you want the webserver portion of XBMC to work, you need to add that use flag:

echo "media-tv/xbmc webserver" >> /etc/portage/package.use

Then emerge the xbmc package:

emerge -av xbmc


7.4.3 LIRC

I haven't got XBMC working with LIRC yet. LIRC is configured and receiving commands from the ATV Remote, XBMC is just ignoring them :-( This is on my list of "things to do", stay tuned.

7.5 Auto Log In

For the truly media-center experience, you will probably want your machine to log in a user and launch XBMC when it is booted, without any prodding.

The easiest way to do this is to create a small script and then edit your inittab. Obviously replace mrmedia with your users name:

su mrmedia --command "startx"

Save that file as /sbin/autologin and make it executable:

chmod +x /sbin/autologin

Now, open up /etc/inittab in your favorite editor. Find this line in the middle:

c1:12345:respawn:/sbin/agetty 38400 tty1 linux

Comment it out using a # and replace it with this:

c1:12345:respawn:/sbin/agetty -n -l /sbin/autologin 38400 tty1 linux

Save that file.

The last thing that needs doing is editing your media user's Fluxbox Startup file, start by switching over to them and opening up the fluxbox startup file:

su mrmedia
vi ~/.fluxbox/startup

In that file, add "xbmc &", directly above "exec fluxbox". That section should look like this:

# And last but not least we start fluxbox.
# Because it is the last app you have to run it with exec before it. 
xbmc &
exec fluxbox

Save that file and drop out of the mrmedia su with 'exit'

With this setup, the system will now boot, check and run inittab, which will call the login script. The login script executes startx as our media user. When X starts, it will call the user's xinitrc file and launch fluxbox, which will then launch XBMC. Easy, right? :-)

Enjoy XBMC.