mb_boot_tv, a boot loader for the Apple TV.

James McKenzie,

For the impatient, here's a walk-through for installing mb_boot_tv onto an Apple TV.

We are planning to start offering dedicated hosting on Apple TVs shortly; check our services page soon for prices.

New version 1.0.7 - fixes a problem where some appletvs refused to load an OS X kernel with such a large bss, and also adds support for booting from usb without opening the case

mb_boot_tv is a simple and (almost) fully featured boot loader for the Apple TV. It currently supports:

bzImage kernels
ramdisks
setting the kernel command line
netbooting via dhcp and tftp
booting from ext2 partitions

What it lacks is any form of keyboard support, but this should be fixed soon. We use mb_boot_tv at mythic-beasts.com to make Apple TVs remotely manageable.

mb_boot_tv is based on code and work from lots of other places:

mach_linux_boot for the base boot loader, and the video drivers
etherboot for the realtek 8139 driver, and the ATA driver, and for DHCP and TFTP code
the linux kernel for the EFI GPT (partition table) parser
ELILO for the ext2/3 filesystem drivers

How to get mb_boot_tv

Either download a a precompiled binary version or
download the source code. If you want to compile the source code under linux you'll need a darwin cross-compiler. You can download it as three rpms from the original site:

Or download the whole lot unpacked from their rpms as a local tar.gz. NB: modern GCCs hard-code the path to the other binaries in the executables, so the old trick of editing the .spec file no-longer works and therefore you have to install it where it was compiled in /opt.

How to install and use mb_boot_tv

For the impatient, here's a walk-through for installing mb_boot_tv onto an Apple TV.

The following instructions require you to mount the Apple TV's disk on another machine. You can either use another Mac OS X machine, or follow the instructions in the walk-through to mount the Mac OS X file systems under linux.

You can now run mb_boot_tv without even opening the case of the Apple TV using a USB stick. The Apple TV will on detecting the stick, run mb_boot_tv and then will net-boot Linux - instructions here.

Copy the mb_boot_tv executable into the root directory of the main Mac OS X partition (sda3), and optionally the recovery partition (sda2). Edit the com.apple.Boot.plist file (located in /System/Library/CoreServices/ in the OSX partition and in the root directory of the recovery partition) and change the lines which read

<key>Kernel</key>
<string>mach_kernel</string>
<key>Kernel Cache</key>
<string>mach_kernel.prelink</string>

so that they instead read

<key>Kernel</key>
<string>mb_boot_tv</string>

Once you've done that, either

a) unmount the Mac OS X filesystem, delete the media partition (sda4), and create a boot root and swap partition (see the walk-through). Make an ext2 or 3 file system on the boot partition. Place the kernel and mb_boot_tv.conf into the boot partition (and optionally a ramdisk). You can also populate the root filesystem now using debbootstrap or whatever your distribution's favourite tool is.
b) set up DHCP, TFTP and NFS servers to netboot boot your Apple TV

format of the mb_boot_tv.conf file

mb_boot_tv ignores all lines it doesn't recognise; it currently understands the following directives (note that there must not be any white space between the beginning of the line and the directive):

`kernel /path/to/vmlinuz`	the path to the file containing the kernel. NB: paths are relative to the root of the filesystem
`options kernel-options`	the options that are appended to the kernel command line are replaced with `kernel-options`, quotes are not stripped
`append kernel-options`	a synonym for `options`
`ramdisk /path/to/initrd`	the path to the file containing the ramdisk
`initrd /path/to/ramdisk`	a synonym for `ramdisk`
`try-net-boot`	the boot loader will attempt a DHCP/TFTP boot first before attempting a disk boot (only valid in mb_boot_tv.conf files on disk)
`force-disk-boot`	if present the boot loader will abort the network boot and (re-)attempt a disk boot, ignoring any try-net-boot directives (only valid in mb_boot_tv.conf files fetched from the network)

What mb_boot_tv actually does

1. looks for the first hard disk
2. looks for a valid EFI GPT
3. looks at each partition in turn to see if it contains a valid ext2 file system containing either the file /mb_boot_tv.conf or /boot/mb_boot_tv.conf
4. reads the first such mb_boot_tv.conf file found
5. if the mb_boot_tv.conf file contains the try-net-boot directive, it proceeds to step 8.
6. the kernel and optionally the ramdisk specified in the mb_boot_tv.conf file are loaded.
7. the kernel is booted with the options specified in the mb_boot_tv.conf file (if any) and some options setting up the framebuffer console.
If any of the steps 1-7 fail, including reading the files, the boot loader proceeds to step 8 (note that mb_boot_tv only tries the first mb_boot_tv.conf file it finds and stops searching for more after that)
8. brings up the realtek 8139 network adaptor and tries to configure the interface using DHCP
9. fetches the file specified in the DHCP option 67 bootfile name.
10. if the bootfile containts the force-disk-boot directive, it proceeds to step 14.
11. loads the kernel and optionally the ramdisk specificied in the bootfile
12. shuts down the 8139 network chip
13. boots the kernel with the options specified in the bootfile, if any, and some options to set up the framebuffer.
If any of the steps 8-13 fail (including a null bootfile) it proceeds to step 14.
14. attempts to disk boot again following steps 1-7, but this time ignoring the try-net-boot directive if present.