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

THIS PAGE IS OUTDATED: 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: Archive:Install XBMC on Apple TV 1 (Linux)

Installing Linux on the AppleTV is already quite well documented and easy thanks to atv-bootloader. If you plan on installing Linux on your AppleTV, you should definitively start there.

With Broadcom Crystal HD now out, the AppleTV can handle 1080p and this makes it a very nice media center alternative. XBMC works fine under the AppleTV OS, but there are a few pro's for having Linux and some might just prefer it.

That said, setting up Linux can be a bit tricky. If you want sound over HDMI, you have to use at least alsa-driver-1.0.18a and NVIDIA 100.14.19 drivers that compile only on Ubuntu 8.04. Any more dissent release seems affected by a regression bug #385076 and it need to be resolved first.

This guide explains how to achieve it using Ubuntu 8.04 for now. Linux will be installed on the AppleTV internal disk without removing the AppleTV OS

I would not recommend this guide if you are not familiar with Linux and the CLI.

If you are not a fan of vi, just use nano instead.

Prerequisites

• A USB Hub
• A USB keyboard
• A USB flash drive of 256MB or greater (64MB should even be enough)
• A network with a DHCP server
• A wired network connection to the AppleTV
• A Mac or Linux computer on the same network (Windows should probably work as well)

Create the bootable USB flash drive

If you have a Mac, just download and run the OS X version of atvusb-creator. Choose "ATV-Bootloader" for the installation and create your bootable flash drive. When done, if you unplug/plug the USB disk, you should see an empty PATCHSTICK partition.

Download Hardy netboot image and copy the needed files to the empty PATCHSTICK partition created by ATV USB creator.

curl -O http://archive.ubuntu.com/ubuntu/dists/hardy/main/installer-i386/current/images/netboot/netboot.tar.gz
tar xfz netboot.tar.gz
cp ubuntu-installer/i386/linux /Volumes/PATCHSTICK
cp ubuntu-installer/i386/initrd.gz /Volumes/PATCHSTICK
rm -rf netboot.tar.gz ubuntu-installer pxelinux.0 pxelinux.cfg

If you only have a Linux machine, just follow those instructions: LinuxUSBPenBoot. Make another partition to copy linux and initrd.gz from the netboot image.

Linux installation

Connect the USB keyboard and flash drive previously created to your AppleTV using a USB Hub. Reboot the AppleTV and telnet in from your computer (username/password: root). You should see the IP address on your TV screen.

telnet <IP address>

Backup!

Before touching the disk partition, you should do a backup! We gonna follow the ATVBackup procedure but do a tar instead of a copy. This ensures that permissions won't be changed, no matter the file system on your USB flash drive partition.

mkdir src dst
# Mount the patchstick partition
# If you created the flash drive manually, it might be sdb2
mount /dev/sdb3 dst

# Mount the source
fsck.hfsplus -f /dev/sda2
mount -t hfsplus /dev/sda2 src

# Make a tar of all files on the "Recovery" partition
cd src
tar cf ../dst/backup.tar *
cd ..
# force a disk buffer flush
sync

umount src dst
rmdir src dst

Run "parted" and make a copy of the original partitioning for the internal PATA disk. The disk can then be re-partitioned back to the original later using this file as a guide. Copy this to the first partition of the USB flash drive for safe keeping.

mkdir tmp

# If you created the flash drive manually, it might be sdb1 here
fsck.hfsplus /dev/sdb2
mount /dev/sdb2 tmp

parted -s /dev/sda unit s print > tmp/org_gtp.txt

Check the file. This is how my 40GB disk looked like:

cat tmp/org_gtp.txt
Model: ATA FUJITSU MHW2040A (scsi)
Disk /dev/sda: 78140160s
Sector size (logical/physical): 512B/512B
Partition Table: gpt

Number Start End Size File system Name Flags
 1      40s       69671s     69632s     fat32        EFI System Partition  boot
 2      69672s    888871s    819200s    hfs+         Apple_HFS_Untitled_1  atvrecv
 3      888872s   2732071s   1843200s   hfs+         Apple_HFS_Untitled_2
 4      2732072s  78140119s  75408048s  hfs+         Customer

umount tmp

If you need to restore the disk to its original state, just follow the Restore procedure (watch the sdb partition number), but instead of doing:

cp -arp src/* dst/

do:

cd dst
tar xf ../src/backup.tar
cd ..

Make space for Linux

I didn't exactly follow the procedure described here (btw, it seems Apple doesn't always follow the same naming convention). I just did a resize on my "Customer" partition and it worked fine. I didn't have to perform a "Factory Restore" and didn't lose anything.
But from my Linux experience, when doing a resize on a disk, you should be ready in case it doesn't work. That means, if you have data on that partition you don't want to lose, backup first!
Note that we did NOT backup that partition previously (only the Recovery partition was). This partition is where you might have synced, pictures, movies... If the resize doesn't work, you'll have to remove the partition and do a "Factory Restore". Read this page for more explanations.
You can adjust the partitions sizes to your needs.

# Resize partition 4 and create the main partition for Linux + swap
parted -s /dev/sda resize 4 2732072s 54525951s
parted -s /dev/sda mkpart primary ext3 54525952s 77091549s
parted -s /dev/sda mkpart primary linux-swap 77091550s 78140126s

# Sync the partition tables
partprobe /dev/sda

# Format the new partition
mkfs.ext3 -b 4096 -L Linux /dev/sda5

Here is how the disk should now look like:

parted /dev/sda unit s print
Model: ATA FUJITSU MHW2040A (scsi)
Disk /dev/sda: 78140160s
Sector size (logical/physical): 512B/512B
Partition Table: gpt

Number Start End Size File system Name Flags
 1      40s        69671s     69632s     fat32        EFI System Partition  boot
 2      69672s     888871s    819200s    hfs+         Apple_HFS_Untitled_1  atvrecv
 3      888872s    2732071s   1843200s   hfs+         Apple_HFS_Untitled_2
 4      2732072s   54525951s  51793880s  hfs+         Customer
 5      54525952s  77091549s  22565598s  ext3         Linux
 6      77091550s  78140126s  1048577s   linux-swap   primary

Start Linux installation

Bootstrap into netboot installer

# Mount the patchstick partition with the netboot files
# If you created the flash drive manually, it might be sdb2
mount /dev/sdb3 tmp
kexec --load tmp/linux --initrd=tmp/initrd.gz --command-line="nosplash vesa video=vesafb"
kexec -e

You should now see the Ubuntu install screen on your TV. Proceed with the keyboard you connected earlier.

Follow the steps of the installer.
When asked for partitioning Method, choose manual
Select the ext3 partition you created previously: sdb5 (the USB stick shows up as sda, so the internal disk is sdb)
Use as : Ext3
Mount point: /
sb6 should already be selected as swap
Write the changes to disk

When asked for username, do NOT use “xbmc”, create an admin user

If you are asked to select a specific kernel, just take the default choice (generic kernel)

When you come to the “Software selection” window, choose only "OpenSSH server"

When the install is done, reboot.

Post installation fix

Telnet again to your AppleTV.

telnet <IP address>

Change the USB flash drive, so that it will boot automatically to Linux next time

mkdir tmp
mount /dev/sdb2 tmp
vi tmp/com.apple.Boot.plist

-> change patchstick to auto

umount tmp

Edit your menu.lst

mount /dev/sda5 tmp
vi tmp/boot/grub/menu.lst

Change it to something like this (check your kernel version):

default 0
timeout 3
title Linux
root (hd0,4)
kernel /boot/vmlinuz-2.6.24-28-generic root=/dev/sda5 ro vesa video=vesafb
initrd /boot/initrd.img-2.6.24-28-generic
boot

Bootstrap to this new kernel (or just reboot)

kexec --load tmp/boot/vmlinuz-2.6.24-28-generic --initrd=tmp/boot/initrd.img-2.6.24-28-generic --command-line="root=/dev/sda5 ro vesa video=vesafb"
kexec -e

Linux setup

You can now ssh to your AppleTV. Use the user you created during installation.

ssh [email protected]

Set the MAX_CSTATE

You may experience dropped ethernet packets if you do not adjust the maximum cstate for the AppleTV's processor. Cstates are different levels of power that the processor will operate at. The intention is to conserve energy when the system is not in use, but in Linux's case this can cause a few issues. I have seen better and more reliable network activities after performing the following steps.

Add the following line to your /etc/modprobe.d/options file:

options processor max_cstate=2

Then update the initrd image using the following command:

sudo update-initramfs -u

The initrd image is now updated to include the option. Then reboot. Verify if it works:

cat /proc/acpi/processor/CPU0/power |grep max_cstate

You should see:

max_cstate: C2

Install alsa-driver 1.0.19

At least 1.0.18a is needed but it failed to compile on my system. 1.0.19 worked fine.

sudo apt-get install linux-sound-base alsa-utils build-essential linux-headers-`uname -r`
wget ftp://ftp.alsa-project.org/pub/driver/alsa-driver-1.0.19.tar.bz2
tar xfj alsa-driver-1.0.19.tar.bz2
cd alsa-driver-1.0.19
# alsa-driver package installs in /lib/modules/'uname -r'/kernel/sound by default
# but ubuntu has the alsa drivers in /lib/modules/'uname -r'/ubuntu/sound/alsa-driver
# so give the ubuntu directory
./configure --with-moddir=/lib/modules/`uname -r`/ubuntu/sound/alsa-driver
make
sudo make install
cd

Install Xserver and NVIDIA 100.14.19 drivers

Check http://www.nvidia.com/object/linux_display_ia32_100.14.19.html

sudo apt-get remove --purge nvidia*
sudo apt-get install xserver-xorg-core xserver-xorg-dev xinit xfonts-base x11-xserver-utils xauth
wget http://us.download.nvidia.com/XFree86/Linux-x86/100.14.19/NVIDIA-Linux-x86-100.14.19-pkg1.run
sudo sh NVIDIA-Linux-x86-100.14.19-pkg1.run
sudo nvidia-xconfig --no-composite --no-logo

Take the opportunity to edit your xorg.conf

sudo vi /etc/X11/xorg.conf

Turn off the use of TurboCache by the nvidia binary driver by adding (see ATV blog):

Option "RegistryDwords" "RMDisableRenderToSysmem=1"

Some people experienced problem with refresh rate due to NVIDIA’s DynamicTwinView feature, so disable it by adding:

Option "DynamicTwinView" "false"

Your nvidia driver section should look like:

Section "Device"
    Identifier     "Device0"
    Driver         "nvidia"
    VendorName     "NVIDIA Corporation"
    Option "RegistryDwords" "RMDisableRenderToSysmem=1"
    Option "DynamicTwinView" "false"
EndSection

Install atvclient

To get the front LED stop flashing and get the Apple Remote to work, just install atvclient See https://github.com/Evinyatar/atvclient/wiki/Installation-on-Ubuntu-8.04

sudo apt-get install git-core libusb-dev pkg-config
git clone git://github.com/Evinyatar/atvclient.git
cd atvclient
./configure && make
sudo make install
sudo cp atvclient /etc/init.d/atvclient
sudo update-rc.d atvclient defaults
sudo /etc/init.d/atvclient start
cd ..

Install crystal HD driver and library

svn trunk and git trees might be unstable. So use the last tag from http://code.google.com/p/crystalhd-for-osx/ (it contains both osx and linux source code).

sudo apt-get install subversion autoconf
svn checkout http://crystalhd-for-osx.googlecode.com/svn/tags/crystalhd-for-osx-3.6.0
cd crystalhd-for-osx-3.6.0/crystalhd/linux_lib/libcrystalhd
make
sudo make install
cd ../../driver/linux
autoconf
./configure
make
sudo make install
sudo modprobe crystalhd
cd

Time to install XBMC

To get Official PPA and SVN PPA, update your system's software sources:

sudo vi /etc/apt/sources.list

Add:

deb http://ppa.launchpad.net/team-xbmc/ppa/ubuntu hardy main
deb-src http://ppa.launchpad.net/team-xbmc/ppa/ubuntu hardy main
deb http://ppa.launchpad.net/team-xbmc-svn/ppa/ubuntu hardy main
deb-src http://ppa.launchpad.net/team-xbmc-svn/ppa/ubuntu hardy main

Add the keys and update your list of software:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 91E7EE5E
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 64234534
sudo apt-get update
# Install xbmc
sudo apt-get install xbmc

Create xbmc user:

sudo adduser xbmc --gecos XBMC
sudo usermod --group audio,video,fuse,plugdev xbmc

Here is one way to have XBMC started automatically at boot. You could as well choose to just install xbmc-live.

Change tty1 for automatic login:

sudo vi /etc/event.d/tty1

Change this line:

exec /sbin/getty 38400 tty1

To:

exec /bin/login -f xbmc </dev/tty1 > /dev/tty1 2>&1
#exec /sbin/getty 38400 tty1

Update your Xwrapper.config

sudo vi /etc/X11/Xwrapper.config

Replace console by anybody

allowed_users=anybody

Login as xbmc and create a .bash_profile

su - xbmc
vi .bash_profile

Set it to:

if [["`tty`" == "/dev/tty1"]] 
then
  clear && startx -- -br & >/dev/null
fi

Create a .xsession:

echo "exec xbmc --standalone" > .xsession
# Logout
exit

Reboot

sudo reboot

Set up the HDMI audio output

After reboot, XBMC should start up automatically. You might have some strange colors. Just unmute the HDMI audio output by running alsamixer.

ssh to your appletv

ssh [email protected]

alsamixer

-> unmute IEC958 1 (that's the HDMI audio output)
Save the driver setup:

sudo alsactl store 0

You can check the device by running:

aplay -l

You should see:

card 0: Intel [HDA Intel], device 3: ATI HDMI [ATI HDMI]

Go to XBMC Audio output settings and choose custom for the Audio output device.
Set it to: plughw:0,3 Do the same thing for Passthrough output device.

That's it, you should have sound over HDMI!

What next?

If you don't want to have to plug/unplug the USB stick to boot into Linux/AppleTV OS, check: https://github.com/Evinyatar/atvclient/wiki/AppleTV-Linux-bootmenu

I don't really like to put a password in clear text in a script... I removed the password from the script, and added the script to the sudoers file instead:

sudo visudo

Add:

xbmc ALL=NOPASSWD: /usr/local/bin/bootAppleTV.sh

Same can be done on the AppleTV OS side

Faster boot

atv-bootloader boots a default Linux kernel and then finds and boots your Linux kernel using kexec. You can avoid this double boot process by creating a custom atv-bootloader. To do so you need a Mac computer with the Developer Tools installed (it should be possible under Linux with the darwin-cross tools to compile/link).

On your Mac, get the atv-bootloader source code:

svn checkout http://atv-bootloader.googlecode.com/svn/trunk/ atv-bootloader-read-only
cd atv-bootloader-read-only
# Remove the default kernel
rm vmlinuz initrd.gz

Copy from your atv to that directory your ubuntu kernel (check your kernel version) and run make

scp [email protected]:/boot/vmlinuz-2.6.24-27-generic vmlinuz
scp [email protected]:/boot/initrd.img-2.6.24-27-generic initrd.gz
make

You should now have a custom mach_kernel.
To use it to directly boot into your Linux installation, you just need to give the arguments that will get passed to the Linux kernel in the com.apple.Boot.plist.

• If you use an USB flash drive to boot into Linux, replace the mach_kernel by the one you created and replace the plist by the following one:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>Background Color</key>
        <integer>0</integer>
        <key>Boot Fail Logo</key>
        <string></string>
        <key>Boot Logo</key>
        <string>BootLogo.png</string>
        <key>Kernel</key>
        <string>mach_kernel</string>
        <key>Kernel Flags</key>
        <string>root=/dev/sda5 ro vesa video=vesafb</string>
</dict>
</plist>

Check the kernel arguments on the last line. They should be the same as the ones you have in your /boot/grub/menu.lst file. Note that there is no need for the "atv-boot=auto" line.

• If you switch plist to boot into ATV OS / Linux as explained here, just replace the /mach_kernel_linux with the one you created and edit the /System/Library/CoreServices/com.apple.Boot.plist.linux file to add the kernel arguments as described above.

Runing Firefox

Exit XBMC and at the terminal install Firefox and Flash:

sudo apt-get --no-install-recommends install firefox flashplugin-nonfree

Create a script to start firefox:

vi firefox.sh

add:

#!/bin/bash
echo "exec firefox --standalone" > /home/xbmc/.xsession
startx

Make firefox.sh executable:

chmod +x firefox.sh

HDMI audio:

vi .asoundrc

add:

pcm.!default {
type plug
slave {
pcm "plughw:0,3"
}
}

Edit rc.local to restore launching xbmc at boot.

sudo vi /etc/rc.local

add:

echo "exec xbmc --standalone" > /home/xbmc/.xsession

Increase font size:

sudo vi /etc/X11/xorg.conf

Add an option DPI in the "monitor" section:

Option "DPI" "200 x 200"

run script

./firefox.sh

ps.: It can take up to 3min to load firefox at first time. ps2.: to return to terminal: Ctrl+Alt+backspace

VNC Server

Install X11vnc

sudo apt-get install x11vnc

Set a password (optional)

x11vnc -storepasswd

Make X to load X11vnc at startup

echo "x11vnc -display :0 -bg -nopw -noxdamage -forever" > ~/.xsessionrc

External Links

This guide is based on differents sources. Thanks to the original authors (sorry if I forgot some):

• http://code.google.com/p/atv-bootloader
• http://code.google.com/p/atvusb-creator
• http://wiki.xbmc.org/?title=XBMCbuntu
• http://wiki.eple.us/appletv_ubuntu_9.10_xbmc
• http://artem-astafyev.blogspot.com/2008/11/hdmi-audio-in-linux-running-on-apple-tv.html
• https://github.com/Evinyatar/atvclient/wiki/Installation-on-Ubuntu-8.04
• http://www.inliniac.net/blog/2008/07/25/fixing-noise-on-ubuntu-hardy-804-aka-setting-max_cstate.html
• http://teknogeekz.com/blog/?p=422 remote support