Version 1 (modified by charles, 12 years ago) (diff)

moved from "Headless Transmission" to better follow wiki naming conventions

Running Transmission on a headless machine

Some users would like to run Transmission on a headless pc/server (without monitor or keyboard/mouse). This page explains what you need to know to set up a headless server yourself.



  • A PC with at least 200 MHz and 64 MB RAM (less will work, but it may be slow)
  • A Linux distribution installed on that machine (preferably Debian or Ubuntu Server, see Gentoo notes below)


  1. After setting up your server and configuring it properly, you should install Transmission either from source, by downloading one of the Binaries or using your favorite package manager. Check if you can start transmission-daemon.
  2. Now we'll set up a new user called "transmission". For the sake of security you shouldn't set a password (try 'adduser --disabled-password transmission').
  3. Copy the init-script below to /etc/init.d/transmission-daemon and configure it using your favorite text editor. Watch out for the "TRANSMISSION - CONFIGURATION" section. It contains the following variables which have to be set up properly, otherwise transmission won't start or behave unexpected:
    • TRANSMISSION_HOME=/path/to/your/configuration/dir
    • TORRENTFOLDER=/path/to/your/downloads/folder
    • PORT=54318
    • USERNAME=transmission
    • REMOTE_USER=admin
    • REMOTE_PASS=password
  4. Check that the paths in $TRANSMISSION_HOME and $TORRENTFOLDER are owned by the user in $USERNAME (which should be transmission).
  5. Check your configuration AGAIN

Hint: The script below is written for Debian. If you're using another distribution, you may have to change $NAME and $SCRIPTNAME in the *Advanced* section. $NAME should contain the name of the executable (usually transmission-daemon). $SCRIPTNAME should point to the script itself.

To start transmission manually, you can call the init-script with the 'start' parameter:

/etc/init.d/transmission-daemon start

Starting Transmission at boot time

By installing the following init-script, your server will start Transmission automatically at every boot. You can use rcconf or similar tools to add the script to the correct runlevels.

#! /bin/sh
# Provides:          transmission-daemon
# Required-Start:    networking
# Required-Stop:     networking
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Start the transmission BitTorrent client daemon.

# Author: Lennart A. Jütte, based on Rob Howell's script 
# (can be found here:

# Do NOT "set -e"

# ----- CONFIGURATION -----
# The folder where Transmission stores the config
# The folder where Transmission stores downloads

# The port Transmission uses to connect to other peers

# The name of the user that should run Transmission

# Login credentials for the Web- and the RPC-interface

# Only change these options if you know what you are doing!
# PATH should only include /usr/* if it runs after the script.
DESC="bittorrent client"
DAEMON=$(which $NAME)

# Exit if the package is not installed
[ -x "$DAEMON" ] || exit 0

# Read configuration variable file if it is present
[ -r /etc/default/$NAME ] && . /etc/default/$NAME

# Load the VERBOSE setting and other rcS variables
[ -f /etc/default/rcS ] && . /etc/default/rcS

# Define LSB log_* functions.
# Depend on lsb-base (>= 3.0-6) to ensure that this file is present.
. /lib/lsb/init-functions

# Function that starts the daemon/service

	# Set the configuration directory
        export TRANSMISSION_HOME

        # Return
        #   0 if daemon has been started
        #   1 if daemon was already running
        #   2 if daemon could not be started
        start-stop-daemon --chuid $USERNAME --start --pidfile $PIDFILE --exec $DAEMON \
                --test -- $TRANSMISSION_ARGS > /dev/null \
                || return 1
        start-stop-daemon --chuid $USERNAME --start --pidfile $PIDFILE --exec $DAEMON \
                -- --auth --username $REMOTE_USER --password $REMOTE_PASS \
                --config-dir $TRANSMISSION_HOME --download-dir $TORRENTFOLDER \
                || return 2
        sleep 1
        transmission-remote --portmap --port $PORT --auth $REMOTE_USER:$REMOTE_PASS > /dev/null

# Function that stops the daemon/service
        # Return
        #   0 if daemon has been stopped
        #   1 if daemon was already stopped
        #   2 if daemon could not be stopped
        #   other if a failure occurred
        start-stop-daemon --stop --quiet --retry=TERM/10/KILL/5 --pidfile $PIDFILE --name $NAME
        [ "$RETVAL" = 2 ] && return 2

        # Wait for children to finish too if this is a daemon that forks
        # and if the daemon is only ever run from this initscript.
        # If the above conditions are not satisfied then add some other code
        # that waits for the process to drop all resources that could be
        # needed by services started subsequently.  A last resort is to
        # sleep for some time.

        start-stop-daemon --stop --quiet --oknodo --retry=0/30/KILL/5 --exec $DAEMON
        [ "$?" = 2 ] && return 2

        # Many daemons don't delete their pidfiles when they exit.
        rm -f $PIDFILE

        return "$RETVAL"


# Function that sends a SIGHUP to the daemon/service
do_reload() {
        # If the daemon can reload its configuration without
        # restarting (for example, when it is sent a SIGHUP),
        # then implement that here.
        start-stop-daemon --stop --signal 1 --quiet --pidfile $PIDFILE --name $NAME
        return 0

case "$1" in
        log_daemon_msg "Starting $DESC" "$NAME"
        case "$?" in
                0|1) log_end_msg 0 ;;
                2)  log_end_msg 1 ;;
        log_daemon_msg "Stopping $DESC" "$NAME"
        case "$?" in
                0|1) log_end_msg 0 ;;
                2) log_end_msg 1 ;;
        # If the "reload" option is implemented then remove the
        # 'force-reload' alias
        log_daemon_msg "Restarting $DESC" "$NAME"
        case "$?" in
                case "$?" in
                        0) log_end_msg 0 ;;
                        1) log_end_msg 1 ;; # Old process is still running
                        *) log_end_msg 1 ;; # Failed to start
                # Failed to stop
                log_end_msg 1
        echo "Usage: $SCRIPTNAME {start|stop|restart|force-reload}" >&2
        exit 3


Notes on Gentoo

As you have read above, a successfull installation entails three parts: package installation, configuration, and use. We'll re-visit each part with a focus on Gentoo Linux

The following information is current as of October 5, 2008. As things change all the time details could become incorrect or obsolete, take that into account.

What is accomplished by these notes? The current distribution of Transmission on Gentoo has several errors and lacks functionality. A start script as the one above is a much better alternative; the instructions below show how to adjust the installation and the script under Gentoo.


The usual command line is used, but we add a couple of environment options to get exactly what we want:

ACCEPT_KEYWORDS="~amd64" USE="-X -gtk" emerge -av transmission
ACCEPT_KEYWORDS="~x86"   USE="-X -gtk" emerge -av transmission

Let's dissect the above line:

  • ACCEPT_KEYWORDS is used to allow selection of "masked" packages for your processor (use amd64 for all 64-bit Intel or AMD processors, use x86 for 32-bit processors). It really means that we're accepting untested / unstable / non-working packages, so use carefully (also with the dependencies included, you could install the stable version of those first, then transmission); in transmission's case is just untested and this happens with all new versions of packages.

With Transmission we usually need it to select the very latest version; also, for those using 64-bit processors, most packages are left untested or at least takes longer.

  • USE adds a couple of options, in fact substracts them, meaning that we want to install all of Transmission except those parts that depend on X windows and gtk. The Web client is not affected and we get the daemon and the command line tools; we don't get the desktop application.
  • emerge options just make it easy to check exactly what we are installing, it shows all the dependencies and the package with versions, stopping to ask if it is what we want.

Now, currently Gentoo does not list the latest Transmission (i.e. shows several available versions up to 1.33 but the current version is 1.34), what can we do? See below, under "Advanced Topics".


Following best practices we leave the configurable parameters in one file, which is the only one you'll need to change to fine tune the installation to your needs, and adjust the startup script accordingly.

We're not going to touch, or use, the script left by the Gentoo installation: /etc/init.d/transmission-daemon. Currently it has a couple of errors so it doesn't even work right.


# For information on options, see the transmission-daemon(1) man page.
# The commented variables in this file are the defaults that are used
# in the init-script.  You don't need to uncomment them except to
# customize them to different values.


# The folder where Transmission stores its config and .torrent files
# TR_HOME=/var/transmission/config
# The folder where Transmission stores downloads
# TR_DOWNLOAD=/var/transmission/downloads

# The port Transmission uses to connect to other peers
# TR_PORT=54318

# The name of the user that runs transmission-daemon and owns the files
# TR_USERNAME=nobody

# Login credentials for the Web- and the RPC-interface
# - default: leave commented/empty to disable access authentication
# - alternative: set a user name and password
# REMOTE_PASS=password

# ----- ADVANCED OPTIONS -----

# Acces control lists
# (machines/networks allowed/denied to control transmission -- comma separated)
# TR_ACL="+"

# Enable use of block lists
# (read the Wiki about what else needs to be done)

# Control port used
# (only privileged users can use ports < 1024, this applies to REMOTE_USER)
# CTL_PORT=9091

# Initial speed limits (in K/s)
# default: no limits? 100/100 seems to be the hardcoded default
# TR_UP_SPEED=unlimited
# TR_DN_SPEED=unlimited

# Peer exchange
# TR_PX=no

# Port mapping using NAT/UPnP
# TR_PMAP=no

# Encryption
# Any of :
# TR_ENCRYPT=tolerated
# TR_ENCRYPT=prefered
# TR_ENCRYPT=required

You can add extra dependencies to transmission by adding some variables to this file, for instance:


You'll have to create the directories used, if they don't exist (this is something the Gentoo installation should have done, but since it installs for transmission running as root, its not). Adjust paths as necessary to be the same as your configuration.

mkdir -p /var/transmission/config
mkdir -p /var/transmission/downloads
chown -R nobody:nogroup /var/transmission

And the startup script, which uses automagically the options file:



# ------------
# All configurable options are set in /etc/conf.d/transmission

declare -a OPTIONS
OPTIONS+=" -a ${TR_ACL:=+}"
if [ -z "$TR_BLOCK" -o "$TR_BLOCK" = "no" ]; then
   OPTIONS+=" -B"
   OPTIONS+=" -b"
OPTIONS+=" -g ${TR_HOME:-/var/transmission/config}"
OPTIONS+=" -p ${CTL_PORT:-9091}"
if [ -z "$REMOTE_USER" -o -z "$REMOTE_PASS" ]; then
   OPTIONS+=" -T"
   OPTIONS+=" -t"
OPTIONS+=" -w ${TR_DOWNLOAD:-/var/transmission/downloads}"
declare -a EXTRA_OPT
if [ -z "$TR_UP_SPEED" -o "$TR_UP_SPEED" = "unlimited" ]; then
   EXTRA_OPT+=" -U"
if [ -z "$TR_DN_SPEED" -o "$TR_DN_SPEED" = "unlimited" ]; then
   EXTRA_OPT+=" -D"
if [ -z "$TR_PX" -o "$TR_PX" = "no" ]; then
  EXTRA_OPT+=" -X"
  EXTRA_OPT+=" -x"
if [ -z "$TR_PMAP" -o "$TR_PMAP" = "no" ]; then
  EXTRA_OPT+=" -M"
  EXTRA_OPT+=" -m"
if [ -z "$TR_ENCRYPT" -o "$TR_ENCRYPT" = "tolerated" ]; then
  EXTRA_OPT+=" -et"
elif [ "$TR_ENCRYPT" = "prefered" ]; then
  EXTRA_OPT+=" -ep"
elif [ "$TR_ENCRYPT" = "required" ]; then
  EXTRA_OPT+=" -er"
  EXTRA_OPT+=" -et"
E_MSG="ERROR starting transmission, check configuration."

depend() {
   need net

start() {
   ebegin "Starting transmission daemon"
   start-stop-daemon --start --quiet \
      --chuid ${TR_USERNAME:-nobody} \
      --exec /usr/bin/transmission-daemon -- ${OPTIONS[@]} \
   || { eerror $E_MSG; eend 1; return 1; }
   sleep 1
   transmission-remote ${CTL_PORT:-9091} \
      --port ${TR_PORT:-54318} ${EXTRA_OPT[@]} > /dev/null
   eend $?

stop() {
   ebegin "Stopping transmission daemon"
   start-stop-daemon --stop --quiet --retry=TERM/30/KILL/5 \
      --name $NAME
   eend $?

# vim: set ft=gentoo-init-d ts=3 sw=3 et:

Make the script executable:

chmod +x /etc/init.d/transmission


  • Activate the use of the script (starts the daemon at boot time, stops it at shutdown)
rc-update add transmission default
  • Manual start / stop / restart / status

Once you installed everything you can start the daemon without rebooting, for instance, as root:

/etc/init.d/transmission start

Similarly you can stop it and, every time you change the configuration parameters, use restart which is just a combination of stop and start.

  • Web client

Remember to use the port configured as control port, 9091 if you didn't change it:


Advanced Topics

  • MoBlock

Here's a good reference on setting up MoBlock on Gentoo

After setting MoBlock as a service, you can link its database to be the one used by Transmission:

ln -s /var/db/moblock/guarding.p2p /var/transmission/config/blocklists/

That means MoBlock will take care of updating the data base. It also means MoBlock will be blocking access using the firewall (iptables) and Transmission will not try to connect to blocked addresses (connections that will be blocked anyway by MoBlock).

  • Local ebuild

The procedure is not difficult but involves more work: create a local emerge repository structure, copy the contents from the current transmission branch, inside your local copy duplicate the file transmission-1.33.ebuild into transmission-1.34.ebuild, change the configuration in /etc/make.conf adding 'PORTDIR_OVERLAY="/usr/local/portage"', rebuild the package (2 ebuild commands), and emerge will show it as an option.


Waldorf: I think this page may include a guide on how to do this using Launchd, the default/preferred way of running daemons on a mac. However, All Unix users might benefit from Launched too, since it removes the need for custom start and boot scripts.

theCrank: I believe it's best to use this page as a starting point: The general steps will be mentioned (download, compile, bootscript, blocklist) and more or less precise explanations for each system/distro will be split up to seperate pages.