Difference between revisions of "Transmission"

From ArchWiki
Jump to: navigation, search
m
(Reducing journal spam: wrapper script example)
 
(109 intermediate revisions by 39 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]]
 
[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:
 
{{hc|/etc/tmpfiles.d/transmission.conf|
 
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:
+
=== Reducing journal spam ===
# systemctl daemon-reload
+
  
Don't forget to change permissions to '''777''' on folder '/run/transmission'.
+
Running transmission-daemon can lead to a lot of unwanted journal entries. Output can be filtered by starting it with a small wrapper script. The following example also provides some notifications:
 +
{{hc|transwrap.sh|<nowiki>
 +
#!/bin/zsh
 +
killall transmission-daemon 2> /dev/null
 +
transmission-daemon --foreground --log-info 2>&1 | while read line; do
 +
echo $line |
 +
grep -v "announcer.c:\|platform.c:\|announce done (tr-dht.c:" |
 +
grep -v "Saved.*variant.c:" |
 +
while read line; do
 +
echo $line | grep -q "Queued for verification (verify.c:" &&
 +
notify-send --app-name="Transmission Started" "${line#* * }"
 +
echo $line | grep -q "changed from .Incomplete. to .Complete." &&
 +
notify-send --app-name="Transmission Complete" "${line#* * }"
 +
echo $line | systemd-cat --identifier="TransWrap" --priority=5
 +
done 2>&1 > /dev/null
 +
done&disown
 +
</nowiki>
 +
}}
  
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:
+
=== Run only while connected to network ===
# chgrp transmission /path/to/download
+
==== Netctl ====
# chmod g+w /path/to/download
+
  
==See also==
+
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.
 +
 
 +
{{hc|/etc/netctl/hooks/90-transmission.sh|<nowiki>
 +
#!/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
 +
</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
 +
}}
 +
 
 +
== 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 16:39, 17 September 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


Reducing journal spam

Running transmission-daemon can lead to a lot of unwanted journal entries. Output can be filtered by starting it with a small wrapper script. The following example also provides some notifications:

transwrap.sh
#!/bin/zsh
killall transmission-daemon 2> /dev/null
transmission-daemon --foreground --log-info 2>&1 | while read line; do
	echo $line |
		grep -v "announcer.c:\|platform.c:\|announce done (tr-dht.c:" |
		grep -v "Saved.*variant.c:" |
		while read line; do
			echo $line | grep -q "Queued for verification (verify.c:" &&
				notify-send --app-name="Transmission Started" "${line#* * }"
			echo $line | grep -q "changed from .Incomplete. to .Complete." &&
				notify-send --app-name="Transmission Complete" "${line#* * }"
			echo $line | systemd-cat --identifier="TransWrap" --priority=5
		done 2>&1 > /dev/null
	done&disown

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

See also