Running Transmission on a headless machine (Gentoo)

(for other distributions see the Headless Usage article)

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 January, 2009. 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. The start script can be improved; 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="-gtk" emerge -av transmission
ACCEPT_KEYWORDS="~x86"   USE="-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 Intel/AMD or compatible 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 an option, in fact subtracts it, meaning that we want to install all of Transmission except those parts that depend on gtk. The Web client is not affected and we get the daemon and the command line tools; we don't get the desktop application. Of course you can install both, daemon and GUI client, by not using this option.
  • 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.

Currently Gentoo's portage lists Transmission 1.42 (but they deleted all versions between 1.22 and 1.42, why? your guess is as good as mine), what can we do if we want another, like the upcoming 1.50? 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="+"
# or (for versions 1.4x -- different syntax)
# 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 TR_USERNAME
# 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

# Overall peer limit.
# TR_PEERS=240

# Peer limit per torrent.
# TR_PPT=60

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+=" -l ${TR_PPT:-60}"
OPTIONS+=" -L ${TR_PEERS:-240}"
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 2
   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/45/KILL/15 \
      --exec /usr/bin/transmission-daemon
   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.


  1. With version 1.42, the change from ACL to whitelist prompted the change above of dropping the "+"; leaving it causes a failure on the script when transmission-remote tries to change some parameters and is not authorized to do so (the whitelist is probably empty, not even
  1. As reported on the forum, the sleep on the script was increased to 2 seconds to avoid a communication failure between transmission-remote and the daemon. I observed this problem, with twice the torrents reported before in the forum, so the daemon startup might be slower the more torrents it has and the problem may persist.
  1. Transmission 1.42 was added to portage... bad news is they discarded all my changes shown above, there's at least one report about that release's init.d script not working (I'm not going to test it, I'm not happy with the way the Gentoo kids came, complained about the format I uploaded the changes -- which I already had re-uploaded after their first complain, ignored the comments in the thread and in the documentation I added, marked as obsolete everything prior and then released their junk).
Last modified 12 years ago Last modified on Jan 13, 2009, 5:59:05 PM