Install Asterisk on Apple TV

by editor @ AppleTVHacks.net on April 2, 2007


The winner of the bounty to get the Asterisk PBX system running on Apple TV, kindly sponsored by Sokol & Associates, has been won!

l0rdr0ck (email) was the first to submit a verifiable procedure, and will collect the $500 reward. His process for installing is included below.

Getting Started

To get Asterisk running on Apple TV requires (obviously) and Apple TV. It also requires an Intel Mac, as there are no development tools available on the Apple TV (yet). We’ve divided the process into three steps: preparing your Apple TV, building Asterisk on your Mac, and finally installing the compiled Asterisk code onto the Apple TV.

Preparing Your Apple TV

Installing SSH

Before you can do anything else you will need to install SSH on the Apple TV. This gives you the ability to access the system remotely and to copy files to the system. Unfortunately, the best way to do this is by opening up your Apple TV (and invalidating the warranty in the process) and mounting the disk drive to your Mac using a FireWire or USB interface. Use this tutorial:

http://www.appletvhacks.net/2007/03/24/enable-ssh-and-afp-on-your-apple-tv/

Mounting The Filesystem In Read/Write Mode

Apple TV mounts its root filesystem in read-only mode, which presents some problems. Fortunately, it’s easy to correct this. To override this default behavior, create a file called .readwrite in the root (/) directory. You can do this from the terminal using the touch command as follows:

# touch /Volumes/OSBoot/.readwrite

Disabling Watchdog Services

Once you have the Apple TV open for SSH, you’ll want to disable a few of the Apple TV’s integrated protections. The Apple TV comes with several mechanisms to prevent hacking and to automatically fix issues that may crop up while the device is in use. These have the unfortunate side effect of disabling software you add. To disable the watchdog services, follow the tutorial here:

http://wiki.awkwardtv.org/wiki/Watchdog

Useful Binaries

In order for you to make full use of the command line interface in Apple TV, you’ll want to install a few extra binary files. First, you will need gzip to uncompress gzip-compressed archives (i.e. most tar files). You will also want an editor to manipulate text files (you can do without and simply SCP files back and forth, but that becomse tedious after a bit. We recommend you copy the following additional binaries while you have the Apple TV’s drive mounted to your Mac:

$ cp /usr/bin/gzip /Volumes/OSBoot/usr/bin/
$ chmod +x /Volumes/OSBoot/usr/bin/gzip
$ cp /usr/bin/nano /Volumes/OSBoot/usr/bin/
$ chmod +x /Volumes/OSBoot/usr/bin/nano
$ cp /usr/bin/vi /Volumes/OSBoot/usr/bin/
$ chmod +x /Volumes/OSBoot/usr/bin/vi

Disabling FrontRow (Optional)

Apple TV runs FrontRow as the default shell application (i.e. in place of Finder, which runs as the default shell on a standard Mac). While there is nothing to prevent you from running both FrontRow and Asterisk at the same time, be aware that FrontRow is a bit of a CPU hog. If you’re converting your Apple TV into a full-time PBX appliance, you can simply remove FrontRow. If you want it to serve as both PBX and entertainment center, you can move the FrontRow application to another directory and launch it when you want it using the ‘open’ shell command. For instructions on disabling FrontRow, check here:

http://tutorialninjas.net/2007/03/26/hacking-the-apple-tv/

Preparing Your Mac

You will need the developer tools installed on your Mac, so install the full Xcode suite from your OS X install discs, or a href=”http://developer.apple.com/tools/xcode/index.html”>download them. Once the Apple developer tools are installed, you will need to add on a few open source applications to complete the process.

1) Download the source code to Asterisk 1.4.2 from here and extract the files into a sane place. Unpack it using the tar command as follows:

$ tar -xzvf asterisk-1.4.2.tar.gz

2) Download Subversion (the source code control system used by the Asterisk development team) for OS X from this site. Open the disk image file and install the software to your Mac.

3) Next, download the Asterisk GUI from the source code control system at Digium using Subversion as follows:

$ svn checkout http://svn.digium.com/svn/asterisk-gui/trunk asterisk-gui

4) Download a copy of wget Intel binary, as this is necessary to download the Asterisk sounds. Put wget into your path either at /usr/local/bin or /usr/bin. Note that you can also install wget from either Fink or Darwin Ports.

Building Asterisk

On your Mac, open a terminal window, change directory to the location where you extracted the Asterisk source code, and begin the build process by executing the following commands:

$ ./configure

When the autoconf configuration is complete, select the options to be built using:

$ make menuconfig

Note: For my initial build I removed the Asterisk sounds and Zaptel module to build, however, it will build with the default options. Complete the build process by executing the following:

$ make
$ sudo make install
$ sudo make samples

Building The GUI

Locate the asterisk-gui folder from the Subversion checkout. To configure the source from the terminal run:

$ ./configure
$ make
$ sudo make checkconfig
$ sudo make install

Once these items have completed, you have the files needed to put on the AppleTV.

Moving To Apple TV

Once all the files have been build and placed on your Mac, you can test your installation by launching Asterisk. To do this, type the following in a terminal window:

$ sudo asterisk -vvvvvvddddgci

Asterisk should respond by loading and displaying a good deal of startup information. When the load is complete you should see the Asterisk command line symbol as follows:

Asterisk Ready.
*CLI>

If you see this, you have a live Asterisk installation on your Mac. Now let’s exit out and move it over to the Apple TV. Exit by typing:

*CLI> stop now

Archive the Asterisk directories and their contents using the tar command as follows:

$ cd /
$ sudo tar -czvf asterisk.tar.gz \
/var/lib/asterisk \
/var/spool/asterisk \
/var/log/asterisk \
/usr/lib/asterisk \
/usr/sbin/asterisk \
/usr/sbin/astgenkey \
/etc/asterisk \

Once the tar file has been build (it should be between 20 and 25 megs) you will need to move it over to the Apple TV. You can do this via AFS or using the scp command from the terminal. To use SCP, log into your Apple TV using SSH, then execute scp as follows:

$ sudo scp user@192.168.0.102:/asterisk.tar.gz /

Substitute your user name on your Mac for ‘user’ and the IP address of your Mac for the address listed. Note that you will be challenged for a password twice. The first time you will need to enter ‘frontrow’ (the password on the Apple TV default user). The second prompt is for the password associated with your user on the Mac.

After the file has copied to the Apple TV, you can uncompress it from the terminal as follows:

$ cd /
$ sudo tar -xzvf asterisk.tar.gz

This will extract all of the files into their proper places and should, with any luck, turn your Apple TV into an Asterisk-based PBX. Next, you’ll need to make some changes to the Asterisk configuration files (which are located in the /etc/asterisk folder). At this point you will need an editor (either the nano or vi executable) installed on your Apple TV.

Configuring The Manager and GUI

The new Asterisk GUI depends on the Asterisk Manager Interface (AMI) – a kind of computer-telephony integration protocol that, among many other things, allows AJAX applications to interface with Asterisk. The Manager interface is disabled by default, so we will need to turn it on and activate a user.

Change directories to the /etc/asterisk directory on the Apple TV. Edit the manager.conf file using nano or vi. Make the following changes:

Enabled both the Ethernet port and the Airport interface by setting the ‘bindport’ option as follows:

bindport = 0.0.0.0

Enable the Manager by setting the ‘enabled’ option as follows:

enabled = yes

Enable the web interface by setting webenabled as follows:

webenabled = yes

Create an administrative user entry as follows:

[manager]
secret=manager
read = system,call,log,verbose,command,agent,user,config
write = system,call,log,verbose,command,agent,user,config

Next, edit http.conf to enable built-in web server. Simply set the ‘enabled’ option to ‘yes’ and set the ‘bindport’ option to ‘0.0.0.0’ to bind to all TCP/IP interfaces on the Apple TV.

Starting Asterisk

Now you are ready to fire up the Asterisk server. The binary is found in /usr/sbin (which should be part of your path). To launch it, use sudo as follows:

$ sudo asterisk -vvvvvdddgci

If the asterisk console starts the builtin webserver in the asterisk-gui will also be active. From any web browser, go to your Apple TV’s IP and you can start working

The interface at the installer URL (per the asterisk-gui Readme file) will not work properly because a probram called zapscan keeps running (and failing). At this point you must manually edit the ‘providers.conf’ file to disable the setup wizard, then simply go to the cfgbasic.htm file as follows:

http://appleTV.local:8088/asterisk/static/config/cfgbasic.html

You should be greeted by the Asterisk GUI. From there you can start to configure your PBX as you see fit. For more information on Asterisk, check out the following resources:

http://www.sokol-associates.com Training Classes
http://www.asteriskdocs.org Free copy of O’Reilly’s “Asterisk: The Future of Telephony”
http://www.asteriskguru.com Asterisk Recipes
http://www.voip-info.org Asterisk Wiki (Tons Of Help)

Follow Up

There is alot of testing needed and some call applications may not work yet. It’s also unfortunate that the installation requires cracking the case and voiding the warranty. Hopefully in the near future somebody will come up with a reliable way to boot from USB and the SSH daemon, obviating the need for a hardware hacking.

As yet we don’t know how much load the Apple TV can handle. The 1 Ghz Dothan-class Pentium M is not known as a powerhouse, but then people have been running Asterisk on Gumstix systems and Linksys routers (both of which are much less powerful than the Apple TV). We hope to have some results soon indicating the number of simultaneous calls that can be supported, etc.

We also need a new splash screen to take the place of FrontRow. The application only needs to give us the IP addresses of the Ethernet and Airport interfaces and let us know that Asterisk is up and running.

More as we have it.

Previous post:

Next post: