Changes between Initial Version and Version 1 of HeadlessUsage


Ignore:
Timestamp:
Oct 27, 2008, 5:13:53 PM (13 years ago)
Author:
charles
Comment:

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

Legend:

Unmodified
Added
Removed
Modified
  • HeadlessUsage

    v1 v1  
     1= Running Transmission on a headless machine =
     2[[PageOutline]]
     3
     4Some 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.
     5
     6== Unix ==
     7=== Requirements ===
     8 * A PC with at least 200 MHz and 64 MB RAM (less will work, but it may be slow)
     9 * A Linux distribution installed on that machine (preferably Debian or Ubuntu Server, see Gentoo notes below)
     10
     11=== Setup ===
     12 1. After setting up your server and configuring it properly, you should install Transmission either [wiki:"Building#OnUnix" "from source"], by downloading one of the [wiki:Binaries] or using your favorite package manager. Check if you can start transmission-daemon.
     13 1. 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').
     14 1. 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:
     15  * TRANSMISSION_HOME=/path/to/your/configuration/dir
     16  * TORRENTFOLDER=/path/to/your/downloads/folder
     17  * PORT=54318
     18  * USERNAME=transmission
     19  * REMOTE_USER=admin
     20  * REMOTE_PASS=password
     21 1. Check that the paths in $TRANSMISSION_HOME and $TORRENTFOLDER are owned by the user in $USERNAME (which should be transmission).
     22 1. Check your configuration AGAIN
     23
     24Hint: 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.
     25
     26To start transmission manually, you can call the init-script with the 'start' parameter:
     27{{{
     28/etc/init.d/transmission-daemon start
     29}}}
     30
     31
     32=== Starting Transmission at boot time ===
     33 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.
     34
     35{{{
     36#! /bin/sh
     37### BEGIN INIT INFO
     38# Provides:          transmission-daemon
     39# Required-Start:    networking
     40# Required-Stop:     networking
     41# Default-Start:     2 3 4 5
     42# Default-Stop:      0 1 6
     43# Short-Description: Start the transmission BitTorrent client daemon.
     44### END INIT INFO
     45
     46# Author: Lennart A. Jütte, based on Rob Howell's script
     47# (can be found here: http://forum.transmissionbt.com/viewtopic.php?f=8&t=4310)
     48
     49# Do NOT "set -e"
     50
     51#
     52# ----- CONFIGURATION -----
     53#
     54# The folder where Transmission stores the config
     55TRANSMISSION_HOME=/etc/.transmission-config
     56 
     57# The folder where Transmission stores downloads
     58TORRENTFOLDER=/mnt/incoming
     59
     60# The port Transmission uses to connect to other peers
     61PORT=54318
     62
     63# The name of the user that should run Transmission
     64USERNAME=transmission
     65
     66# Login credentials for the Web- and the RPC-interface
     67REMOTE_USER=admin
     68REMOTE_PASS=password
     69
     70
     71
     72# ----- *ADVANCED* CONFIGURATION -----
     73# Only change these options if you know what you are doing!
     74#
     75# PATH should only include /usr/* if it runs after the mountnfs.sh script.
     76PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
     77DESC="bittorrent client"
     78NAME=transmission-daemon
     79DAEMON=$(which $NAME)
     80PIDFILE=/var/run/$NAME.pid
     81SCRIPTNAME=/etc/init.d/$NAME
     82
     83# Exit if the package is not installed
     84[ -x "$DAEMON" ] || exit 0
     85
     86# Read configuration variable file if it is present
     87[ -r /etc/default/$NAME ] && . /etc/default/$NAME
     88
     89# Load the VERBOSE setting and other rcS variables
     90[ -f /etc/default/rcS ] && . /etc/default/rcS
     91
     92# Define LSB log_* functions.
     93# Depend on lsb-base (>= 3.0-6) to ensure that this file is present.
     94. /lib/lsb/init-functions
     95
     96#
     97# Function that starts the daemon/service
     98#
     99
     100do_start()
     101{
     102        # Set the configuration directory
     103        export TRANSMISSION_HOME
     104
     105        # Return
     106        #   0 if daemon has been started
     107        #   1 if daemon was already running
     108        #   2 if daemon could not be started
     109        start-stop-daemon --chuid $USERNAME --start --pidfile $PIDFILE --exec $DAEMON \
     110                --test -- $TRANSMISSION_ARGS > /dev/null \
     111                || return 1
     112        start-stop-daemon --chuid $USERNAME --start --pidfile $PIDFILE --exec $DAEMON \
     113                -- --auth --username $REMOTE_USER --password $REMOTE_PASS \
     114                --config-dir $TRANSMISSION_HOME --download-dir $TORRENTFOLDER \
     115                || return 2
     116        sleep 1
     117       
     118        transmission-remote --portmap --port $PORT --auth $REMOTE_USER:$REMOTE_PASS > /dev/null
     119}
     120
     121#
     122# Function that stops the daemon/service
     123#
     124do_stop()
     125{
     126        # Return
     127        #   0 if daemon has been stopped
     128        #   1 if daemon was already stopped
     129        #   2 if daemon could not be stopped
     130        #   other if a failure occurred
     131        start-stop-daemon --stop --quiet --retry=TERM/10/KILL/5 --pidfile $PIDFILE --name $NAME
     132        RETVAL="$?"
     133        [ "$RETVAL" = 2 ] && return 2
     134
     135        # Wait for children to finish too if this is a daemon that forks
     136        # and if the daemon is only ever run from this initscript.
     137        # If the above conditions are not satisfied then add some other code
     138        # that waits for the process to drop all resources that could be
     139        # needed by services started subsequently.  A last resort is to
     140        # sleep for some time.
     141
     142        start-stop-daemon --stop --quiet --oknodo --retry=0/30/KILL/5 --exec $DAEMON
     143        [ "$?" = 2 ] && return 2
     144
     145        # Many daemons don't delete their pidfiles when they exit.
     146        rm -f $PIDFILE
     147
     148
     149
     150        return "$RETVAL"
     151
     152}
     153
     154#
     155# Function that sends a SIGHUP to the daemon/service
     156#
     157do_reload() {
     158        #
     159        # If the daemon can reload its configuration without
     160        # restarting (for example, when it is sent a SIGHUP),
     161        # then implement that here.
     162        #
     163        start-stop-daemon --stop --signal 1 --quiet --pidfile $PIDFILE --name $NAME
     164        return 0
     165}
     166
     167case "$1" in
     168  start)
     169        log_daemon_msg "Starting $DESC" "$NAME"
     170        do_start
     171        case "$?" in
     172                0|1) log_end_msg 0 ;;
     173                2)  log_end_msg 1 ;;
     174        esac
     175        ;;
     176  stop)
     177        log_daemon_msg "Stopping $DESC" "$NAME"
     178        do_stop
     179        case "$?" in
     180                0|1) log_end_msg 0 ;;
     181                2) log_end_msg 1 ;;
     182        esac
     183        ;;
     184  restart|force-reload)
     185        #
     186        # If the "reload" option is implemented then remove the
     187        # 'force-reload' alias
     188        #
     189        log_daemon_msg "Restarting $DESC" "$NAME"
     190        do_stop
     191        case "$?" in
     192          0|1)
     193                do_start
     194                case "$?" in
     195                        0) log_end_msg 0 ;;
     196                        1) log_end_msg 1 ;; # Old process is still running
     197                        *) log_end_msg 1 ;; # Failed to start
     198                esac
     199                ;;
     200          *)
     201                # Failed to stop
     202                log_end_msg 1
     203                ;;
     204        esac
     205        ;;
     206  *)
     207        echo "Usage: $SCRIPTNAME {start|stop|restart|force-reload}" >&2
     208        exit 3
     209        ;;
     210esac
     211
     212:
     213
     214}}}
     215
     216=== Notes on Gentoo ===
     217
     218As 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[http://www.gentoo.org/].
     219
     220The 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.
     221
     222What 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.
     223
     224==== Installation ====
     225The usual command line is used, but we add a couple of environment options to get exactly what we want:
     226{{{
     227ACCEPT_KEYWORDS="~amd64" USE="-X -gtk" emerge -av transmission
     228or
     229ACCEPT_KEYWORDS="~x86"   USE="-X -gtk" emerge -av transmission
     230}}}
     231Let's dissect the above line:
     232
     233 * 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.
     234With 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.
     235 * 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.
     236 * 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.
     237
     238Now, 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".
     239
     240==== Configuration ====
     241Following 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.
     242
     243We'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.
     244
     245'''/etc/conf.d/transmission'''
     246{{{
     247# For information on options, see the transmission-daemon(1) man page.
     248#
     249# The commented variables in this file are the defaults that are used
     250# in the init-script.  You don't need to uncomment them except to
     251# customize them to different values.
     252
     253#
     254# ----- MAIN CONFIGURATION -----
     255#
     256
     257# The folder where Transmission stores its config and .torrent files
     258# TR_HOME=/var/transmission/config
     259 
     260# The folder where Transmission stores downloads
     261# TR_DOWNLOAD=/var/transmission/downloads
     262
     263# The port Transmission uses to connect to other peers
     264# TR_PORT=54318
     265
     266# The name of the user that runs transmission-daemon and owns the files
     267# TR_USERNAME=nobody
     268
     269# Login credentials for the Web- and the RPC-interface
     270# - default: leave commented/empty to disable access authentication
     271# REMOTE_USER=""
     272# REMOTE_PASS=""
     273# - alternative: set a user name and password
     274# REMOTE_USER=admin
     275# REMOTE_PASS=password
     276
     277#
     278# ----- ADVANCED OPTIONS -----
     279#
     280
     281# Acces control lists
     282# (machines/networks allowed/denied to control transmission -- comma separated)
     283# TR_ACL="+127.0.0.1"
     284
     285# Enable use of block lists
     286# (read the Wiki about what else needs to be done)
     287# TR_BLOCK=no
     288
     289# Control port used
     290# (only privileged users can use ports < 1024, this applies to REMOTE_USER)
     291# CTL_PORT=9091
     292
     293# Initial speed limits (in K/s)
     294# default: no limits? 100/100 seems to be the hardcoded default
     295# TR_UP_SPEED=unlimited
     296# TR_DN_SPEED=unlimited
     297
     298# Peer exchange
     299# TR_PX=no
     300
     301# Port mapping using NAT/UPnP
     302# TR_PMAP=no
     303
     304# Encryption
     305# Any of :
     306# TR_ENCRYPT=tolerated
     307# TR_ENCRYPT=prefered
     308# TR_ENCRYPT=required
     309}}}
     310
     311You can add extra dependencies to transmission by adding some variables to this file, for instance:
     312    RC_NEED="nfs"
     313
     314You'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.
     315
     316{{{
     317mkdir -p /var/transmission/config
     318mkdir -p /var/transmission/downloads
     319chown -R nobody:nogroup /var/transmission
     320}}}
     321
     322And the startup script, which uses automagically the options file:
     323
     324'''/etc/init.d/transmission'''
     325{{{
     326#!/sbin/runscript
     327#
     328
     329# DO NOT EDIT!
     330# ------------
     331# All configurable options are set in /etc/conf.d/transmission
     332
     333NAME=transmission-daemon
     334declare -a OPTIONS
     335OPTIONS+=" -a ${TR_ACL:=+127.0.0.1}"
     336if [ -z "$TR_BLOCK" -o "$TR_BLOCK" = "no" ]; then
     337   OPTIONS+=" -B"
     338else
     339   OPTIONS+=" -b"
     340fi
     341OPTIONS+=" -g ${TR_HOME:-/var/transmission/config}"
     342OPTIONS+=" -p ${CTL_PORT:-9091}"
     343if [ -z "$REMOTE_USER" -o -z "$REMOTE_PASS" ]; then
     344   OPTIONS+=" -T"
     345else
     346   OPTIONS+=" -t"
     347   OPTIONS+=" -u $REMOTE_USER"
     348   OPTIONS+=" -v $REMOTE_PASS"
     349fi
     350OPTIONS+=" -w ${TR_DOWNLOAD:-/var/transmission/downloads}"
     351declare -a EXTRA_OPT
     352if [ -z "$TR_UP_SPEED" -o "$TR_UP_SPEED" = "unlimited" ]; then
     353   EXTRA_OPT+=" -U"
     354else
     355   EXTRA_OPT+=" -u $TR_UP_SPEED"
     356fi
     357if [ -z "$TR_DN_SPEED" -o "$TR_DN_SPEED" = "unlimited" ]; then
     358   EXTRA_OPT+=" -D"
     359else
     360   EXTRA_OPT+=" -d $TR_DN_SPEED"
     361fi
     362if [ -z "$TR_PX" -o "$TR_PX" = "no" ]; then
     363  EXTRA_OPT+=" -X"
     364else
     365  EXTRA_OPT+=" -x"
     366fi
     367if [ -z "$TR_PMAP" -o "$TR_PMAP" = "no" ]; then
     368  EXTRA_OPT+=" -M"
     369else
     370  EXTRA_OPT+=" -m"
     371fi
     372if [ -z "$TR_ENCRYPT" -o "$TR_ENCRYPT" = "tolerated" ]; then
     373  EXTRA_OPT+=" -et"
     374elif [ "$TR_ENCRYPT" = "prefered" ]; then
     375  EXTRA_OPT+=" -ep"
     376elif [ "$TR_ENCRYPT" = "required" ]; then
     377  EXTRA_OPT+=" -er"
     378else
     379  EXTRA_OPT+=" -et"
     380fi
     381E_MSG="ERROR starting transmission, check configuration."
     382
     383depend() {
     384   need net
     385}
     386
     387start() {
     388   ebegin "Starting transmission daemon"
     389   start-stop-daemon --start --quiet \
     390      --chuid ${TR_USERNAME:-nobody} \
     391      --exec /usr/bin/transmission-daemon -- ${OPTIONS[@]} \
     392   || { eerror $E_MSG; eend 1; return 1; }
     393   sleep 1
     394   transmission-remote ${CTL_PORT:-9091} \
     395      ${REMOTE_PASS:+-n $REMOTE_USER:$REMOTE_PASS} \
     396      --port ${TR_PORT:-54318} ${EXTRA_OPT[@]} > /dev/null
     397   eend $?
     398}
     399
     400stop() {
     401   ebegin "Stopping transmission daemon"
     402   start-stop-daemon --stop --quiet --retry=TERM/30/KILL/5 \
     403      --name $NAME
     404   eend $?
     405}
     406
     407# vim: set ft=gentoo-init-d ts=3 sw=3 et:
     408}}}
     409
     410Make the script executable:
     411{{{
     412chmod +x /etc/init.d/transmission
     413}}}
     414==== Use ====
     415 * Activate the use of the script (starts the daemon at boot time, stops it at shutdown)
     416
     417{{{
     418rc-update add transmission default
     419}}}
     420 * Manual start / stop / restart / status
     421
     422Once you installed everything you can start the daemon without rebooting, for instance, as root:
     423{{{
     424/etc/init.d/transmission start
     425}}}
     426Similarly you can stop it and, every time you change the configuration parameters, use restart which is just a combination of stop and start.
     427 * Web client
     428
     429Remember to use the port configured as control port, 9091 if you didn't change it:
     430{{{
     431http://your.server.ip:9091/
     432}}}
     433
     434==== Advanced Topics ====
     435 * !MoBlock
     436
     437Here's a good reference on setting up !MoBlock on Gentoo [http://gentoo-wiki.com/Moblock].
     438
     439After setting ''!MoBlock'' as a service, you can link its database to be the one used by Transmission:
     440{{{
     441ln -s /var/db/moblock/guarding.p2p /var/transmission/config/blocklists/
     442}}}
     443That 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).
     444
     445 * Local ebuild
     446
     447The 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.
     448----
     449== Comments ==
     450> 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. http://launchd.macosforge.org/
     451
     452> 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.