Transmission on AppleTV

Abstract

This is a tutorial to install the superb Transmission bittorrent client, with its equally superb Clutch web interface, on an AppleTV with 3.01 (it however works great on take 2). It is based on many posts found on the internet and personal experience.

For tecnhical reasons the tutorial is divided in two kinds of installation:

• Version 1.06
• Version 1.33 and posteriors

What you need

• An AppleTV :) with SSH enabled
• The Transmission code.
  • 1.06. [Updated] I have Transmission daemon
  • 1.33 working on AppleTV OS 2.4. This includes the Clutch WebUI and eliminates the need to separately download and install Clutch and MAMP/Apache. The only other requirement for this is XCode to build the binaries.
  • version 1.75 tested binaries of transmission-daemon and transmission-remote source files for v1.75
  • version 2.0 via the excellent compilation made by ifroen

For version 1.06:

• The Clutch WebUI - Not required for Tranmission 1.33
• The MAMP Server. Warning: this download weighs about 130 MB - Not required for Tranmission 1.33
• A Mac with Tiger (10.4) or Leopard (10.5) OS, with XCode 2.5 or 3.0 installed (these are on your installation disks, or you can get the last releases from the Apple Developer Connection)

Version 1.06

Transmission building and installation

Uncompress the Transmission file. You should get a folder which contains a file named Transmission.xcodeproj: double-click on it, XCode should open. We need to setup options in the project to build a version compatible with AppleTV OS, do the following:

• From the menu select Project -> Set Active SDK -> Mac OS X 10.4
• From the menu select Project -> Set Active Build Configuration -> Release
• From the menu select Project -> Edit Project Settings. In the Architectures section set Base SDK to Mac OS X 10.4
• If you're running 10.6, you will have to change the GCC version used here to 4.0 in Project Settings under Compiler to get the dependencies to compile
• After closing the Project setting dialog, from the Overview drop-down menu on the window, select transmission-daemon as active target. Press the Build and Go icon.
• Do the same selecting transmission-remote (verify in the lower-right corner of the window you get a "Succeded" message in both cases).

Now, you should have a newly created folder in your Transmission folder named build. This folder should contain (you guessed it!) the builds, in a subfolder called Release: they are aptly named transmission-daemon and transmission-remote. Copy these two files on your AppleTV (using SSH or whatever else you want) in the /Users/frontrow directory. Be sure they have rwxr-xr-x permissions and belong to the frontrow user and the frontrow group. If you're in doubt just use these two commands:

sudo chmod 755 transmission-*
sudo chown frontrow:frontrow transmission-*

You will also need to copy the web folder that's part of the Transmission release in to /Users/frontrow/Contents/Resources/web folder (you will need to create the Contents and Resources folders first).

MAMP installation

• This can be skipped for Transmission 1.33.

Copy the MAMP folder (it's in the .dmg file you downloaded) on your AppleTV in the /Users/frontrow directory. Give the command

sudo ln -s /Users/frontrow/MAMP /Applications/MAMP

If you want to save hard disk space on your AppleTV, there are several things you can delete from this folder (for example, everything related to php4, SQLite and mysql). If you want to be on the safe side, don't worry.

Clutch installation

• This can be skipped for Transmission 1.33.

Uncompress the Clutch file. In the folder you get, locate the file socket.txt in the subfolder data of the subfolder remote, open it, delete what's inside and insert the row

/Users/frontrow/Library/Application Support/Transmission/daemon/socket

Save the file and copy the contents of the Clutch folder (not the folder itself) on your AppleTV in the /Users/frontrow/MAMP/htdocs directory. Give the command

sudo chmod -R 775 /Users/frontrow/MAMP

Test everything is working

Open two SSH sessions to your AppleTV. On the first one, give the command

/Users/frontrow/transmission-daemon -d

You should get something like this:

Transmission 1.06 (5129) started
Bound socket 7 to port 51413
Port Mapping: opened port 51413 to listen for incoming peer connections

On the second one, give the command

 /Users/frontrow/MAMP/bin/startApache.sh

Now, using your browser, go to http://appletv.local:8888/. If everything is alright you should get the Clutch interface, try downloading your first torrent. It should go to the /Users/frontrow directory. You can use the transmission-remote program (transmission-remote -h gives the help) or the Clutch interface itself to set your preferences, including the download directory. When you've had enough, use Ctrl-C to stop transmission-daemon.

Version 1.33 and posteriors

Transmission installation of precompiled binaries

• Unpack the binaries and copy the files transmission-daemon and transmission-remote in /Users/frontrow.
• ssh your appletv and repair permissions

sudo chmod 755 transmission-*
sudo chown frontrow:frontrow transmission-*

• Make the folders

mkdir /Users/frontrow/Contents

and

mkdir /Users/frontrow/Contents/Resources

• Copy the web folder in to /Users/frontrow/Contents/Resources/web folder and run

sudo chmod -R 775 /Users/frontrow/Contents/Resources/web

Test everything is working

Open an SSH session to your AppleTV. Issue the command

/Users/frontrow/transmission-daemon -f

You should see a message similar to this

 Transmission 1.33 (6607) started
 Port Forwarding: Opened port 51413 to listen for incoming peer connections
 Serving the web interface files from "/mnt/Scratch/Users/frontrow/Contents/Resources/web"

This will start the transmission daemon and run it in the foreground (useful for debugging any issues). This will also create the default Transmission working directory (/Users/frontrow/Library/Applications Resources/transmission-daemon). Here we can modify the settings for the daemon in settings.json, and also add blocklist files.

Now after launching the daemon and closing it down, if we look in /Users/frontrow/Library/Application Support/transmission-daemon/settings.json This configuration file will only be generated after the first time you run transmission. This is also where you can set all other parametewrs of the daemon. (see http://trac.transmissionbt.com/wiki/EditConfigFiles for more info)

sudo nano /Users/frontrow/Library/Application\ Support/transmission-daemon/settings.json

and change the line with “rpc-whitelist” to “rpc-whitelist”: “*.*.*.*” or the range you want to whitelist eg. "192.168.1.*"

• When you run transmission-daemon, be sure to whitelist your LAN IPs. For example, running "./transmission-daemon -a 192.168.1.*" will allow web clients from any system in the 192.168.1 network. This will allow you to access the built in web client running on port 9091. Please refer to the transmission man pages for more startup options. See sections below for testing and auto startup.

Now, using your browser, go to http://appletv.local:9091/.  If everything is alright you should get the Clutch interface.

Make it automatic

To start Transmission and its interface when you boot your AppleTV (so it keeps working even after power failures) you should create two documents in the /Library/LaunchDaemons directory. Here are the necessary commands:

sudo nano /Library/LaunchDaemons/transmission.plist

This is the text to paste inside:

<?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>Debug</key>
<true/>
<key>GroupName</key>
<string>frontrow</string>
<key>Label</key>
<string>org.m0k.transmission</string>
<key>OnDemand</key>
<false/>
<key>ProgramArguments</key>
<array>
<string>/Users/frontrow/transmission-daemon</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>ServiceDescription</key>
<string>transmission</string>
<key>UserName</key>
<string>frontrow</string>
<key>WorkingDirectory</key>
<string>/Users/frontrow/Library/Application Support/Transmission</string>
</dict>
</plist>

Press Ctrl-O to save the file and then Ctrl-X to exit. If installing Transmission 1.06, also repeat for the apache service as below:

sudo nano /Library/LaunchDaemons/apache.plist

This one creates a new file called apache.plist in the appropriate directory. Paste these rows inside:

<?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>Debug</key>
<true/>
<key>GroupName</key>
<string>frontrow</string>
<key>Label</key>
<string>org.apache.httpd</string>
<key>OnDemand</key>
<false/>
<key>ProgramArguments</key>
<array>
<string>/Users/frontrow/MAMP/bin/startApache.sh</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>ServiceDescription</key>
<string>apache</string>
<key>UserName</key>
<string>frontrow</string>
<key>WorkingDirectory</key>
<string>/Users/frontrow/MAMP/</string>
</dict>
</plist>

Reboot your AppleTV and test if everything is working correctly.

External resources

This has been compiled with help from many resources out there, some of the most useful have been:

• thanks to J.Smith a junior member at the boxee forum
• evilsoap (which has a tremendosly useful way of installing usenet on the ATV)
• this guy has a very clear set of installation guides not only for transmission
• and last but not least to ifroen who has compiled the recent versions of transmission so we can use them easily