Changes between Version 1 and Version 2 of HeadlessUsage


Ignore:
Timestamp:
Oct 27, 2008, 7:59:29 PM (12 years ago)
Author:
theCrank
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HeadlessUsage

    v1 v2  
    99 * A Linux distribution installed on that machine (preferably Debian or Ubuntu Server, see Gentoo notes below)
    1010
    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
     11=== HowTos ===
     12Currently HowTos for the following distributions exist:
     13 * [HeadlessUsageDebian Debian (etch)]
     14 * [HeadlessUsageGentoo Gentoo]
    2315
    24 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.
    25 
    26 To 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
    55 TRANSMISSION_HOME=/etc/.transmission-config
    56  
    57 # The folder where Transmission stores downloads
    58 TORRENTFOLDER=/mnt/incoming
    59 
    60 # The port Transmission uses to connect to other peers
    61 PORT=54318
    62 
    63 # The name of the user that should run Transmission
    64 USERNAME=transmission
    65 
    66 # Login credentials for the Web- and the RPC-interface
    67 REMOTE_USER=admin
    68 REMOTE_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.
    76 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    77 DESC="bittorrent client"
    78 NAME=transmission-daemon
    79 DAEMON=$(which $NAME)
    80 PIDFILE=/var/run/$NAME.pid
    81 SCRIPTNAME=/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 
    100 do_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 #
    124 do_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 #
    157 do_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 
    167 case "$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         ;;
    210 esac
    211 
    212 :
    213 
    214 }}}
    215 
    216 === Notes on Gentoo ===
    217 
    218 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[http://www.gentoo.org/].
    219 
    220 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.
    221 
    222 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.
    223 
    224 ==== Installation ====
    225 The usual command line is used, but we add a couple of environment options to get exactly what we want:
    226 {{{
    227 ACCEPT_KEYWORDS="~amd64" USE="-X -gtk" emerge -av transmission
    228 or
    229 ACCEPT_KEYWORDS="~x86"   USE="-X -gtk" emerge -av transmission
    230 }}}
    231 Let'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.
    234 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.
    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 
    238 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".
    239 
    240 ==== Configuration ====
    241 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.
    242 
    243 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.
    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 
    311 You can add extra dependencies to transmission by adding some variables to this file, for instance:
    312     RC_NEED="nfs"
    313 
    314 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.
    315 
    316 {{{
    317 mkdir -p /var/transmission/config
    318 mkdir -p /var/transmission/downloads
    319 chown -R nobody:nogroup /var/transmission
    320 }}}
    321 
    322 And 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 
    333 NAME=transmission-daemon
    334 declare -a OPTIONS
    335 OPTIONS+=" -a ${TR_ACL:=+127.0.0.1}"
    336 if [ -z "$TR_BLOCK" -o "$TR_BLOCK" = "no" ]; then
    337    OPTIONS+=" -B"
    338 else
    339    OPTIONS+=" -b"
    340 fi
    341 OPTIONS+=" -g ${TR_HOME:-/var/transmission/config}"
    342 OPTIONS+=" -p ${CTL_PORT:-9091}"
    343 if [ -z "$REMOTE_USER" -o -z "$REMOTE_PASS" ]; then
    344    OPTIONS+=" -T"
    345 else
    346    OPTIONS+=" -t"
    347    OPTIONS+=" -u $REMOTE_USER"
    348    OPTIONS+=" -v $REMOTE_PASS"
    349 fi
    350 OPTIONS+=" -w ${TR_DOWNLOAD:-/var/transmission/downloads}"
    351 declare -a EXTRA_OPT
    352 if [ -z "$TR_UP_SPEED" -o "$TR_UP_SPEED" = "unlimited" ]; then
    353    EXTRA_OPT+=" -U"
    354 else
    355    EXTRA_OPT+=" -u $TR_UP_SPEED"
    356 fi
    357 if [ -z "$TR_DN_SPEED" -o "$TR_DN_SPEED" = "unlimited" ]; then
    358    EXTRA_OPT+=" -D"
    359 else
    360    EXTRA_OPT+=" -d $TR_DN_SPEED"
    361 fi
    362 if [ -z "$TR_PX" -o "$TR_PX" = "no" ]; then
    363   EXTRA_OPT+=" -X"
    364 else
    365   EXTRA_OPT+=" -x"
    366 fi
    367 if [ -z "$TR_PMAP" -o "$TR_PMAP" = "no" ]; then
    368   EXTRA_OPT+=" -M"
    369 else
    370   EXTRA_OPT+=" -m"
    371 fi
    372 if [ -z "$TR_ENCRYPT" -o "$TR_ENCRYPT" = "tolerated" ]; then
    373   EXTRA_OPT+=" -et"
    374 elif [ "$TR_ENCRYPT" = "prefered" ]; then
    375   EXTRA_OPT+=" -ep"
    376 elif [ "$TR_ENCRYPT" = "required" ]; then
    377   EXTRA_OPT+=" -er"
    378 else
    379   EXTRA_OPT+=" -et"
    380 fi
    381 E_MSG="ERROR starting transmission, check configuration."
    382 
    383 depend() {
    384    need net
    385 }
    386 
    387 start() {
    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 
    400 stop() {
    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 
    410 Make the script executable:
    411 {{{
    412 chmod +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 {{{
    418 rc-update add transmission default
    419 }}}
    420  * Manual start / stop / restart / status
    421 
    422 Once you installed everything you can start the daemon without rebooting, for instance, as root:
    423 {{{
    424 /etc/init.d/transmission start
    425 }}}
    426 Similarly 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 
    429 Remember to use the port configured as control port, 9091 if you didn't change it:
    430 {{{
    431 http://your.server.ip:9091/
    432 }}}
    433 
    434 ==== Advanced Topics ====
    435  * !MoBlock
    436 
    437 Here's a good reference on setting up !MoBlock on Gentoo [http://gentoo-wiki.com/Moblock].
    438 
    439 After setting ''!MoBlock'' as a service, you can link its database to be the one used by Transmission:
    440 {{{
    441 ln -s /var/db/moblock/guarding.p2p /var/transmission/config/blocklists/
    442 }}}
    443 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).
    444 
    445  * Local ebuild
    446 
    447 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.
    44816----
    44917== Comments ==