arch-wiki-md-repo
Version:
All arch-wiki articles in markdown format, updated every two days.
283 lines (181 loc) • 14.1 kB
Markdown
[Transmission](http://www.transmissionbt.com/) is a light-weight and cross-platform BitTorrent client.
## Contents
* [1 Installation](#Installation)
* [2 Configuring the GUI version](#Configuring_the_GUI_version)
* [3 Transmission daemon and CLI](#Transmission_daemon_and_CLI)
* [3.1 Starting and stopping the daemon](#Starting_and_stopping_the_daemon)
* [3.2 Reducing journal spam](#Reducing_journal_spam)
* [3.3 Run only while connected to network](#Run_only_while_connected_to_network)
* [3.3.1 Netctl](#Netctl)
* [3.3.2 Wicd](#Wicd)
* [3.4 Choosing a user](#Choosing_a_user)
* [3.5 Configuring the daemon](#Configuring_the_daemon)
* [3.5.1 Host whitelist](#Host_whitelist)
* [3.5.2 Watch dir](#Watch_dir)
* [3.5.3 Enable IPv6](#Enable_IPv6)
* [3.5.4 CLI Examples](#CLI_Examples)
* [4 Web Interface](#Web_Interface)
* [4.1 The GUI way](#The_GUI_way)
* [4.2 The CLI way](#The_CLI_way)
* [5 Troubleshooting](#Troubleshooting)
* [5.1 Cannot access the daemon over the network](#Cannot_access_the_daemon_over_the_network)
* [5.2 Web interface cannot be reached](#Web_interface_cannot_be_reached)
* [6 See also](#See_also)
## Installation
There are several options:
* [transmission-cli](https://www.archlinux.org/packages/?name=transmission-cli) - daemon, with CLI, and [#Web Interface](#Web_Interface).
* [transmission-gtk](https://www.archlinux.org/packages/?name=transmission-gtk) - GTK+ 3 package.
* [transmission-qt](https://www.archlinux.org/packages/?name=transmission-qt) - Qt5 package.
* [tremc-git](https://aur.archlinux.org/packages/tremc-git/) - Curses interface for the daemon.
**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 tremc package for a curses-based GUI.
## 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://github.com/transmission/transmission/wiki/Editing-Configuration-Files](https://github.com/transmission/transmission/wiki/Editing-Configuration-Files).
## Transmission daemon and CLI
The commands for *transmission-cli* are:
*transmission-daemon*: starts the daemon.
*transmission-remote*: invokes the [CLI](https://en.wikipedia.org/wiki/Command-line_interface "wikipedia:Command-line interface") for the daemon, whether local or remote, followed by the command you want the daemon to execute.
*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.
*transmission-cli*: ([deprecated](https://github.com/transmission/transmission/commit/950387ab5a443629598f93c057f41150707866ab)) starts a non-daemonized local instance of *transmission*, for manually downloading a torrent.
*tremc*: (requires [tremc-git](https://aur.archlinux.org/packages/tremc-git/)) starts the [curses](https://en.wikipedia.org/wiki/curses_(programming_library) interface for the daemon, whether local or remote.
### Starting and stopping the daemon
As explained in [#Choosing a user](#Choosing_a_user), the transmission daemon can be run:
* As the user *transmission*, by starting/enabling `transmission.service` [using systemd](/index.php/Systemd#Using_units "Systemd").
you can change the user as explained in [#Choosing a user](#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](#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](#Starting_and_stopping_the_daemon) in folder `/etc/wicd/scripts/postconnect`, and a [stop script](#Starting_and_stopping_the_daemon) 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](/index.php/Sudo "Sudo")).
* Under your own user.
To set this up, [override](/index.php/Systemd#Editing_provided_units "Systemd") 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](#Starting_and_stopping_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](http://localhost:9091) in a supported browser.
A guide to configuration options can be found on the Transmission web site: [https://github.com/transmission/transmission/wiki/Editing-Configuration-Files](https://github.com/transmission/transmission/wiki/Editing-Configuration-Files)
**Note:** If you want to edit the configuration manually using a text editor, [stop the daemon](#Starting_and_stopping_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.
#### Host whitelist
If you plan to access the Transmission daemon over the network using the server's hostname, you need to add this hostname to `rpc-host-whitelist` in `settings.json`. Otherwise, you will get a "421 Misdirected Request" error when accessing the server.
If you connect to the daemon using the server's IP-address, this is not required.
#### 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](/index.php/Systemd#Editing_provided_units "Systemd").
#### Enable IPv6
By default, the daemon only listens for IPv4 connections. To also listen for IPv6 connections, install [transmission-cli-ipv6](https://aur.archlinux.org/packages/transmission-cli-ipv6/) (or [transmission-cli-git](https://aur.archlinux.org/packages/transmission-cli-git/), or wait for Transmission 3.0), and change the `rpc-bind-address` option to `"::"` in `settings.json`.
#### 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
```
## Web Interface
### The GUI way
Once Transmission is installed, you can easily set up the web interface. All you need to do is click the **edit** menu and select **preferences**. Click the **Remote** tab and enable **Allow remote access**.
Here, you have the opportunity to change the default listening port from 9091.
Check the **Use authentication** and fill in a username and password so that authentication can be used.
To increase security, you can restrict access from any IP address by enabling **Only allow these IP addresses**.
Now you are ready to launch the web interface by either clicking on the **Open web client**, which makes your default web browser open it, or manually reaching `http://*TARGET_IP_ADDRESS*:*PORT*` with any supported web browser.
If you haven't changed the listening port, the default one is 9091\. In this case, the link is `[http://localhost:9091](http://localhost:9091)`
**Note:** Keep in mind that [transmission-cli](https://www.archlinux.org/packages/?name=transmission-cli) must be installed
### The CLI way
You don't need a graphical interface to set up the web interface, the daemon offers the very same options. You can reach the web interface without specifing any flags. See [#Starting and stopping the daemon](#Starting_and_stopping_the_daemon)
Nevertheless, you can specify everything that you see in the previous section:
`$ transmission-daemon --auth --username arch --password linux --port 9091 --allowed "127.0.0.1"` is equivalent to `$ transmission-daemon -t -u arch -v linux -p 9091 -a "127.0.0.1"`
## 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](/index.php/Systemd#Editing_provided_units "Systemd"):
`/etc/systemd/system/transmission.service.d/fixdep.conf`
```
[Unit]
Requires=network.target
```
#### Web interface cannot be reached
```
404: Not Found
Couldn't find Transmission's web interface files!
Users: to tell Transmission where to look, set the TRANSMISSION_WEB_HOME environment variable to the folder where the web interface's index.html is located.
Package Builders: to set a custom default at compile time, #define PACKAGE_DATA_DIR in libtransmission/platform.c or tweak tr_getClutchDir () by hand.
```
Even if you use the graphical interface, you still need to install [transmission-cli](https://www.archlinux.org/packages/?name=transmission-cli) in order for web interface to work.
## See also
* [Transmission wiki](https://trac.transmissionbt.com/wiki)
* [HeadlessUsage](https://trac.transmissionbt.com/wiki/HeadlessUsage/General)