Difference between revisions of "Transmission"

From ArchWiki
Jump to: navigation, search
(Watch dir: improve wording, reported in https://bbs.archlinux.org/viewtopic.php?id=213635)
 
(106 intermediate revisions by 38 users not shown)
Line 1: Line 1:
[[Category:Internet Applications]]
+
[[Category:Internet applications]]
 
[[de:Transmission]]
 
[[de:Transmission]]
 +
[[fr:Transmission]]
 
[[it:Transmission]]
 
[[it:Transmission]]
 +
[[ja:Transmission]]
 
[[zh-CN:Transmission]]
 
[[zh-CN:Transmission]]
 
[http://www.transmissionbt.com/ Transmission] is a light-weight and cross-platform BitTorrent client. It is the default BitTorrent client in many Linux distributions.
 
[http://www.transmissionbt.com/ Transmission] is a light-weight and cross-platform BitTorrent client. It is the default BitTorrent client in many Linux distributions.
  
==Installation==
+
== Installation ==
There are several options in [[Official Repositories]]:
+
There are several options in [[official repositories]]:
 +
* {{Pkg|transmission-cli}} - daemon, with [[Wikipedia:Command-line interface|CLI]], and web client (http://localhost:9091) interfaces.
 +
* {{Pkg|transmission-remote-cli}} - Curses interface for the daemon.
 +
* {{Pkg|transmission-gtk}} - GTK3 package.
 +
* {{Pkg|transmission-qt}} - Qt5 package.
  
;{{pkg|transmission-cli}}: includes CLI tools, daemon and web client.
+
{{Note|
 +
* The GTK client cannot connect to the daemon, so users wishing to use the daemon will need to consider using the Qt package for a GUI or the remote-cli package for a curses-based GUI.
 +
* You cannot connect to the daemon over IPv6.[https://trac.transmissionbt.com/ticket/2236]
 +
}}
  
;{{pkg|transmission-gtk}}: GTK+ GUI.
+
== Configuring the GUI version ==
 +
Both GUI versions, ''transmission-gtk'' and ''transmission-qt'', can function autonomously without a formal back-end daemon.  
  
;{{pkg|transmission-qt}}: Qt GUI.
+
GUI versions are configured to work out-of-the-box, but the user may wish to change some of the settings. The default path to the GUI configuration files is {{ic|~/.config/transmission}}.
  
==Configuration==
+
A guide to configuration options can be found on the Transmission web site: https://trac.transmissionbt.com/wiki/EditConfigFiles#Options.
For {{pkg|transmission-gtk}} and {{pkg|transmission-qt}}, the default path of configuration files is {{ic|~/.config/transmission}}.
+
  
For {{pkg|transmission-cli}}, default configuration path is {{ic|~/.config/transmission-daemon}}.
+
=== GTK+ temporary cosmetic fix ===
  
===Run as a daemon===
+
With GTK+ 3.18, transmission-gtk shows black borders in random places; these can be hidden via {{ic|gtk.css}}:
First install {{pkg|transmission-cli}}. Then start the ''transmission'' [[daemon]].
+
  
Navigate to http://127.0.0.1:9091 in your web browser to see the web client.
+
{{hc|~/.config/gtk-3.0/gtk.css|
 +
.tr-workarea .overshoot,
 +
.tr-workarea .undershoot { border: none; }
 +
}}
  
You can edit the main configuration file {{ic|~/.config/transmission-daemon/settings.json}} to fit your preference. '''You need to stop the daemon''' before editing configuration files, or your edits '''will not be saved'''.
+
== Transmission daemon and CLI ==
By default, the daemon will run as the user ''transmission'', whose home directory is {{ic|/var/lib/transmission/}}. This means the default location for the configuration file is {{ic|/var/lib/transmission/.config/transmission-daemon/settings.json}}.
+
  
{{Note|If you cannot find the {{ic|~/.config/transmission-daemon}} folder, run {{ic|transmission-daemon}} once to create it.}}
+
The commands for ''transmission-cli'' are:
 +
:''transmission-daemon'': starts the daemon.
 +
:''transmission-remote'': invokes the [[Wikipedia:Command-line interface|CLI]] for the daemon, whether local or remote, followed by the command you want the daemon to execute.
 +
:''transmission-remote-cli'': (requires {{Pkg|transmission-remote-cli}}) starts the [[Wikipedia:curses (programming library)|curses]] interface for the daemon, whether local or remote.
 +
:''transmission-cli'': (deprecated) starts a non-daemonized local instance of ''transmission'', for manually downloading a torrent.
 +
:''transmission-show'': returns information on a given torrent file.
 +
:''transmission-create'': creates a new torrent.
 +
:''transmission-edit'': add, delete, or replace a tracker's announce URL.
  
If you change your download location, make sure the ''transmission'' user has rw privileges to your download directory.
+
=== Starting and stopping the daemon ===
 +
As explained in [[#Choosing a user]], the transmission daemon can be run:
  
====Changing daemon user====
+
* As the user ''transmission'', by starting/enabling {{ic|transmission.service}} [[systemd#Using units|using systemd]].
 +
: you can change the user as explained in [[#Choosing a user]]
  
If you use systemd, you have to override the user in both the service file ({{ic|/usr/lib/systemd/system/transmission.service}}) and the tmpfile ({{ic|/usr/lib/tmpfiles.d/transmission.conf}}). To do so, copy both files to the appropriate directory in {{ic|/etc}}:
+
* As your own user, by running under your user name: {{bc|$ transmission-daemon}} The daemon can then be stopped with: {{bc|$ killall transmission-daemon}}
# cp /usr/lib/systemd/system/transmission.service /etc/systemd/system/
+
# cp /usr/lib/tmpfiles.d/transmission.conf /etc/tmpfiles.d/
+
  
Create a new group named for example, {{ic|transmission}}:
+
Starting the daemon will create an initial ''transmission'' configuration file. See [[#Configuring the daemon]].
# groupadd transmission
+
  
Add your custom user to the newly created {{ic|1=[group]}} ie. {{ic|transmission}}:
+
An alternative option to stop transmission is to use the ''transmission-remote'' command:
  # gpasswd -a [user] [group]
+
  $ transmission-remote --exit
  
Then change {{ic|1=User=}} to your custom user in the service file and edit the tmpfile to the following:
+
=== Run only while connected to network ===
{{hc|/etc/tmpfiles.d/transmission.conf|
+
==== Netctl ====
d /run/transmission - [user] [group] -}}
+
Then run {{ic|systemd-tmpfiles --create transmission.conf}} and restart the transmission service.
+
  
You may need to reload service files after editing:
+
It may only be desirable to run transmission on certain networks. The following script checks that the connection is to a list of authorized networks and then proceeds to launch transmission-daemon.
  # systemctl daemon-reload
+
  
Don't forget to change permissions to '''777''' on folder '/run/transmission'.
+
{{hc|/etc/netctl/hooks/90-transmission.sh|<nowiki>
 +
#!/bin/bash
  
If you would use Transmission daemon with its own group, you have to give the writing permission to transmission group in your download's directory. For this you need to run:
+
# The SSIDs for which we enable this.
# chgrp transmission /path/to/download
+
declare -A ssids=(
# chmod g+w /path/to/download
+
    ["network_1"]=y
 +
    ["network_2"]=y
 +
)
  
==See also==
+
if [[ ${ssids[$SSID]} ]]; then
 +
    case $ACTION in
 +
        CONNECT|REESTABLISHED)
 +
            # Need to wait, otherwise doesn't seem to bind to 9091.
 +
            sleep 30
 +
            systemctl start transmission
 +
            ;;
 +
        *)
 +
            systemctl stop transmission
 +
            ;;
 +
    esac
 +
fi
 +
</nowiki>
 +
}}
 +
 
 +
==== Wicd ====
 +
Create a [[#Starting and stopping the daemon|start script]] in folder {{ic|/etc/wicd/scripts/postconnect}}, and a [[#Starting and stopping the daemon|stop script]] in folder {{ic|/etc/wicd/scripts/predisconnect}}. Remember to make them executable. For example:
 +
 
 +
{{hc|/etc/wicd/scripts/postconnect/transmission|2=
 +
#!/bin/bash
 +
 
 +
systemctl start transmission
 +
}}
 +
{{hc|/etc/wicd/scripts/predisconnect/transmission|2=
 +
#!/bin/bash
 +
 
 +
systemctl stop transmission
 +
}}
 +
 
 +
=== Choosing a user ===
 +
Choose how you want to run {{ic|transmission}}:
 +
 
 +
*As a separate user, {{ic|transmission}} by default (recommended for increased security).
 +
By default, ''transmission'' creates a user and a group {{ic|transmission}}, with its home files at {{ic|/var/lib/transmission/}}, and runs as this "user". This is a security precaution, so ''transmission'', and its downloads, have no access to files outside of {{ic|/var/lib/transmission/}}. Configuration, operation, and access to downloads needs to be done with "root" privileges (e.g. by using [[sudo]]).
 +
 
 +
*Under the user's own user name.
 +
To set this up, [[systemd#Editing provided units|override]] the provided service file and specify your username:
 +
 
 +
{{hc|/etc/systemd/system/transmission.service.d/username.conf|2=
 +
[Service]
 +
User=''your_username''
 +
}}
 +
 
 +
=== Configuring the daemon ===
 +
Create an initial configuration file by [[#Starting and stopping the daemon|starting the daemon]].
 +
 
 +
* If running Transmission under the username {{ic|transmission}}, the configuration file will be located at {{ic|/var/lib/transmission/.config/transmission-daemon/settings.json}}.
 +
 
 +
* If running Transmission under your own username, the configuration file will be located at {{ic|~/.config/transmission-daemon/settings.json}}.
 +
 
 +
One can customize the daemon by using a Transmission client or using the included web interface accessible via http://localhost:9091 in a supported browser.
 +
 
 +
A guide to configuration options can be found on the Transmission web site: https://trac.transmissionbt.com/wiki/EditConfigFiles#Options
 +
 
 +
{{Note|If you want to edit the configuration manually using a text editor, [[#Starting and stopping the daemon|stop the daemon]] first; otherwise, it would overwrite its configuration file when it closes.
 +
}}
 +
{{Note|Alternatively, the daemon can be instructed to reload its configuration with SIGHUP, by running {{ic|kill -s SIGHUP `pidof transmission-daemon`}}.
 +
}}
 +
 
 +
A recommendation for those running under username {{ic|transmission}} is to create a shared download directory with the correct permissions to allow access to both the {{ic|transmission}} user and system users, and then to update the configuration file accordingly. For example:
 +
# mkdir /mnt/data/torrents
 +
# chown -R facade:transmission /mnt/data/torrents
 +
# chmod -R 775 /mnt/data/torrents
 +
 
 +
Now {{ic|/mnt/data/torrents}} will be accessible for the system user {{ic|facade}} and for the {{ic|transmission}} group to which the {{ic|transmission}} user belongs. Making the target directory world read/writable is highly discouraged (i.e. do not ''chmod'' the directory to ''777''). Instead, give individual users/groups appropriate permissions to the appropriate directories.
 +
 
 +
{{Note|If {{ic|/mnt/data/torrents}} is located on a removable device, e.g. with an {{ic|/etc/fstab}} entry with the option {{ic|nofail}}, Transmission will complain that it cannot find your files. To remedy this, you can add {{ic|1=RequiresMountsFor=/mnt/data/torrents}} to {{ic|/etc/systemd/system/transmission.service.d/transmission.conf}} in the section {{ic|[Unit]}}.}}
 +
 
 +
An alternative is to add your user to the {{ic|transmission}} group ({{ic|#usermod -a -G transmission yourusername}}) and then modify the permissions on the {{ic|/var/lib/transmission}} and {{ic|/var/lib/transmission/Downloads}} directories to allow {{ic|rwx}} access by members of the {{ic|transmission}} group.
 +
 
 +
==== Watch dir ====
 +
If you want to ''Automatically add .torrent files from a folder'', but you find that the {{ic|watch-dir}} and {{ic|watch-dir-enabled}} options set in the config file do not work, you can start the transmission daemon with the flag {{ic|-c /path/to/watch/dir}}.
 +
 
 +
If you're using systemd, edit the {{ic|transmission.service}} unit as described in [[systemd#Editing provided units]].
 +
 
 +
==== CLI Examples ====
 +
 
 +
If you want to remove all finished torrents you can use the following command with your own username and password
 +
# transmission-remote -n 'username:password' -l | grep 100% | awk '{print $1}'| paste -d, -s | xargs -i transmission-remote -t {} -r
 +
 
 +
== Troubleshooting ==
 +
 
 +
==== Cannot access the daemon over the network ====
 +
The daemon is started after {{ic|network.service}} was initialised. However, if you enable the service {{ic|dhcpcd}} as opposed to the device-specific service, such as {{ic|dhcpcd@enp1s0.service}} for example, it may happen that Transmission is started too early and cannot bind to the network interface. Thus, the web interface is unreachable. A possible solution is to add the {{ic|Requires}} line to the unit's [[systemd#Editing provided units|configuration file]]:
 +
 
 +
{{hc|/etc/systemd/system/transmission.service.d/fixdep.conf|2=
 +
[Unit]
 +
Requires=network.target
 +
}}
 +
 
 +
=== UDP Failed to set receive/sent buffer ===
 +
The error messages {{ic|UDP Failed to set receive buffer}} and {{ic|UDP Failed to set sent buffer}} mean that Transmission would like a bigger sent and receive buffer. These buffers can be changed by adding the following file:
 +
 
 +
{{hc|/etc/sysctl.d/60-net_buffer.conf|
 +
<nowiki>
 +
net.core.rmem_max = 16777216
 +
net.core.wmem_max = 4194304
 +
</nowiki>
 +
}}
 +
 
 +
To load the new configuration run {{ic|# sysctl --system}} and then reload Transmission.
 +
 
 +
== See also ==
 
*[https://trac.transmissionbt.com/wiki Transmission wiki]
 
*[https://trac.transmissionbt.com/wiki Transmission wiki]
 
*[https://trac.transmissionbt.com/wiki/HeadlessUsage/General HeadlessUsage]
 
*[https://trac.transmissionbt.com/wiki/HeadlessUsage/General HeadlessUsage]

Latest revision as of 17:04, 11 June 2016

Transmission is a light-weight and cross-platform BitTorrent client. It is the default BitTorrent client in many Linux distributions.

Installation

There are several options in official repositories:

Note:
  • The GTK client cannot connect to the daemon, so users wishing to use the daemon will need to consider using the Qt package for a GUI or the remote-cli package for a curses-based GUI.
  • You cannot connect to the daemon over IPv6.[1]

Configuring the GUI version

Both GUI versions, transmission-gtk and transmission-qt, can function autonomously without a formal back-end daemon.

GUI versions are configured to work out-of-the-box, but the user may wish to change some of the settings. The default path to the GUI configuration files is ~/.config/transmission.

A guide to configuration options can be found on the Transmission web site: https://trac.transmissionbt.com/wiki/EditConfigFiles#Options.

GTK+ temporary cosmetic fix

With GTK+ 3.18, transmission-gtk shows black borders in random places; these can be hidden via gtk.css:

~/.config/gtk-3.0/gtk.css
.tr-workarea .overshoot,
.tr-workarea .undershoot { border: none; }

Transmission daemon and CLI

The commands for transmission-cli are:

transmission-daemon: starts the daemon.
transmission-remote: invokes the CLI for the daemon, whether local or remote, followed by the command you want the daemon to execute.
transmission-remote-cli: (requires transmission-remote-cli) starts the curses interface for the daemon, whether local or remote.
transmission-cli: (deprecated) starts a non-daemonized local instance of transmission, for manually downloading a torrent.
transmission-show: returns information on a given torrent file.
transmission-create: creates a new torrent.
transmission-edit: add, delete, or replace a tracker's announce URL.

Starting and stopping the daemon

As explained in #Choosing a user, the transmission daemon can be run:

  • As the user transmission, by starting/enabling transmission.service using systemd.
you can change the user as explained in #Choosing a user
  • As your own user, by running under your user name:
    $ transmission-daemon
    The daemon can then be stopped with:
    $ killall transmission-daemon

Starting the daemon will create an initial transmission configuration file. See #Configuring the daemon.

An alternative option to stop transmission is to use the transmission-remote command:

$ transmission-remote --exit

Run only while connected to network

Netctl

It may only be desirable to run transmission on certain networks. The following script checks that the connection is to a list of authorized networks and then proceeds to launch transmission-daemon.

/etc/netctl/hooks/90-transmission.sh
#!/bin/bash

# The SSIDs for which we enable this.
declare -A ssids=(
    ["network_1"]=y
    ["network_2"]=y
)

if [[ ${ssids[$SSID]} ]]; then
    case $ACTION in
        CONNECT|REESTABLISHED)
            # Need to wait, otherwise doesn't seem to bind to 9091.
            sleep 30
            systemctl start transmission
            ;;
        *)
            systemctl stop transmission
            ;;
    esac
fi

Wicd

Create a start script in folder /etc/wicd/scripts/postconnect, and a stop script in folder /etc/wicd/scripts/predisconnect. Remember to make them executable. For example:

/etc/wicd/scripts/postconnect/transmission
#!/bin/bash

systemctl start transmission
/etc/wicd/scripts/predisconnect/transmission
#!/bin/bash

systemctl stop transmission

Choosing a user

Choose how you want to run transmission:

  • As a separate user, transmission by default (recommended for increased security).

By default, transmission creates a user and a group transmission, with its home files at /var/lib/transmission/, and runs as this "user". This is a security precaution, so transmission, and its downloads, have no access to files outside of /var/lib/transmission/. Configuration, operation, and access to downloads needs to be done with "root" privileges (e.g. by using sudo).

  • Under the user's own user name.

To set this up, override the provided service file and specify your username:

/etc/systemd/system/transmission.service.d/username.conf
[Service]
User=your_username

Configuring the daemon

Create an initial configuration file by starting the daemon.

  • If running Transmission under the username transmission, the configuration file will be located at /var/lib/transmission/.config/transmission-daemon/settings.json.
  • If running Transmission under your own username, the configuration file will be located at ~/.config/transmission-daemon/settings.json.

One can customize the daemon by using a Transmission client or using the included web interface accessible via http://localhost:9091 in a supported browser.

A guide to configuration options can be found on the Transmission web site: https://trac.transmissionbt.com/wiki/EditConfigFiles#Options

Note: If you want to edit the configuration manually using a text editor, stop the daemon first; otherwise, it would overwrite its configuration file when it closes.
Note: Alternatively, the daemon can be instructed to reload its configuration with SIGHUP, by running kill -s SIGHUP `pidof transmission-daemon`.

A recommendation for those running under username transmission is to create a shared download directory with the correct permissions to allow access to both the transmission user and system users, and then to update the configuration file accordingly. For example:

# mkdir /mnt/data/torrents
# chown -R facade:transmission /mnt/data/torrents
# chmod -R 775 /mnt/data/torrents

Now /mnt/data/torrents will be accessible for the system user facade and for the transmission group to which the transmission user belongs. Making the target directory world read/writable is highly discouraged (i.e. do not chmod the directory to 777). Instead, give individual users/groups appropriate permissions to the appropriate directories.

Note: If /mnt/data/torrents is located on a removable device, e.g. with an /etc/fstab entry with the option nofail, Transmission will complain that it cannot find your files. To remedy this, you can add RequiresMountsFor=/mnt/data/torrents to /etc/systemd/system/transmission.service.d/transmission.conf in the section [Unit].

An alternative is to add your user to the transmission group (#usermod -a -G transmission yourusername) and then modify the permissions on the /var/lib/transmission and /var/lib/transmission/Downloads directories to allow rwx access by members of the transmission group.

Watch dir

If you want to Automatically add .torrent files from a folder, but you find that the watch-dir and watch-dir-enabled options set in the config file do not work, you can start the transmission daemon with the flag -c /path/to/watch/dir.

If you're using systemd, edit the transmission.service unit as described in systemd#Editing provided units.

CLI Examples

If you want to remove all finished torrents you can use the following command with your own username and password

# transmission-remote -n 'username:password' -l | grep 100% | awk '{print $1}'| paste -d, -s | xargs -i transmission-remote -t {} -r

Troubleshooting

Cannot access the daemon over the network

The daemon is started after network.service was initialised. However, if you enable the service dhcpcd as opposed to the device-specific service, such as dhcpcd@enp1s0.service for example, it may happen that Transmission is started too early and cannot bind to the network interface. Thus, the web interface is unreachable. A possible solution is to add the Requires line to the unit's configuration file:

/etc/systemd/system/transmission.service.d/fixdep.conf
[Unit]
Requires=network.target

UDP Failed to set receive/sent buffer

The error messages UDP Failed to set receive buffer and UDP Failed to set sent buffer mean that Transmission would like a bigger sent and receive buffer. These buffers can be changed by adding the following file:

/etc/sysctl.d/60-net_buffer.conf

net.core.rmem_max = 16777216
net.core.wmem_max = 4194304

To load the new configuration run # sysctl --system and then reload Transmission.

See also