--- title: "Transmission" date: 2023-07-22 icon: "transmission.png" tags: ["service"] short_desc: "Decentralized file-sharing with BitTorrent." --- [Transmission] allows you to send and receive files via the BitTorrent protocol. This tutorial shows you how to use Transmission to run a "seedbox" - a server for downloading and seeding torrents. (For an explanation of BitTorrent, see [Appendix 1].) [Transmission]: https://transmissionbt.com/ [Appendix 1]: #appendix-1-what-is-bittorrent ## Installation The Transmission daemon is available in the Debian repositories: ```sh apt install transmission-daemon ``` Besides installing Transmission, this command creates: * A user for running the service (`debian-transmission`) * A default configuration file (`/var/lib/transmission-daemon/info/settings.json`) * A default service file (`/etc/systemd/system/multi-user.target.wants/transmission-daemon.service`) ## Configuration ### Transmission-Daemon Any time you need to modify Transmission\'s configuration, you must stop the `transmission-daemon` service. Otherwise, Transmission will overwrite your changes. ```sh service transmission-daemon stop ``` Open `/var/lib/transmission-daemon/info/settings.json` to view Transmission\'s configuration. The file should look something like this: ```json { "alt-speed-down": 50, "alt-speed-enabled": false, "alt-speed-time-begin": 540, "alt-speed-time-day": 127, "alt-speed-time-enabled": false, "alt-speed-time-end": 1020, "alt-speed-up": 50, "bind-address-ipv4": "0.0.0.0", "bind-address-ipv6": "::", "blocklist-enabled": false, "blocklist-url": "http://www.example.com/blocklist", "cache-size-mb": 4, "dht-enabled": true, "download-dir": "/var/lib/transmission-daemon/downloads", "download-limit": 100, "download-limit-enabled": 0, "download-queue-enabled": true, "download-queue-size": 5, "encryption": 1, "idle-seeding-limit": 30, "idle-seeding-limit-enabled": false, "incomplete-dir": "/var/lib/transmission-daemon/Downloads", "incomplete-dir-enabled": false, "lpd-enabled": false, "max-peers-global": 200, "message-level": 1, "peer-congestion-algorithm": "", "peer-id-ttl-hours": 6, "peer-limit-global": 200, "peer-limit-per-torrent": 50, "peer-port": 51413, "peer-port-random-high": 65535, "peer-port-random-low": 49152, "peer-port-random-on-start": false, "peer-socket-tos": "default", "pex-enabled": true, "port-forwarding-enabled": false, "preallocation": 1, "prefetch-enabled": true, "queue-stalled-enabled": true, "queue-stalled-minutes": 30, "ratio-limit": 2, "ratio-limit-enabled": false, "rename-partial-files": true, "rpc-authentication-required": true, "rpc-bind-address": "0.0.0.0", "rpc-enabled": true, "rpc-host-whitelist": "", "rpc-host-whitelist-enabled": true, "rpc-password": "{224c4b5e26569d0baa8a161a68263253bbc69c26dnhxDeWg", "rpc-port": 9091, "rpc-url": "/transmission/", "rpc-username": "transmission", "rpc-whitelist": "127.0.0.1", "rpc-whitelist-enabled": true, "scrape-paused-torrents-enabled": true, "script-torrent-done-enabled": false, "script-torrent-done-filename": "", "seed-queue-enabled": false, "seed-queue-size": 10, "speed-limit-down": 100, "speed-limit-down-enabled": false, "speed-limit-up": 100, "speed-limit-up-enabled": false, "start-added-torrents": true, "trash-original-torrent-files": false, "umask": 18, "upload-limit": 100, "upload-limit-enabled": 0, "upload-slots-per-torrent": 14, "utp-enabled": true } ``` Here are the options you should definitely look at: 1. `download-dir` specifies where Transmission should save downloaded torrents. (You can probably leave this at the default of `/var/lib/transmission-daemon/downloads`.) If you change this, make sure `debian-transmission` has permissions to use the directory. 2. `peer-port` specifies what port Transmission should listen on to connect to peers. (You can probably leave this at the default of `51413`.) 3. `rpc-password` specifies the password required to control Transmission. Change this by typing it in as plaintext. When the Transmission service starts, it will be hashed and prefixed with a left curly bracket (`{`). 4. `rpc-port` specifies the port Transmission will listen on for remote commands. (You can probably leave this at the default of `9091`, unless you have another service listening on this port for some reason.) 5. `rpc-username` specifies the username required to control Transmission. The default is `transmission`, but feel free to change this. ### Firewall If `peer-port-random-on-start` is set to the default of `false`, your firewall must allow TCP and UDP traffic on the `peer-port`. Assuming you are using `ufw`, and `peer-port` is at the default of `51413`, enter: ```sh ufw allow 51413 ``` #### Note on Port Randomization If you set `peer-port-random-on-start` to `true`, your firewall must allow both TCP and UDP traffic on the port range specified by `peer-port-random-low` and `peer-port-random-high`. Assuming you are using `ufw`, and `peer-port-random-high` is `65535`, and `peer-port-random-low` is `49152`, enter: ```sh ufw allow 49152:65535/tcp ufw allow 49152:65535/udp ``` ### Starting the Service After modifying and saving the `transmission-daemon` configuration, start the service: ```sh service transmission-daemon start ``` Transmission will hash your password in the configuration. You should be able to connect to the daemon with `transmission-remote` locally on the server using your credentials as shown next. ## Controlling Transmission Locally `transmission-daemon` runs your torrent session in the background. It is controlled by an HTTP API that it serves on the `rpc-port` at `localhost`. `transmission-remote` is the command line utility you can use to control the daemon, and it was installed automatically when you installed `transmission-daemon`. ### Authentication You first need to authenticate `transmission-remote` using the username and password you set up in `settings.json`. There are 2 basic ways you can do this. #### .netrc File The first method is via a `.netrc` file in your home directory. The advantage of this method is that you do not need to provide your credentials every time you run a `transmission-remote` command. The disadvantage is that your Transmission password is stored in your home folder as plaintext. To add the necessary record to your `.netrc` file, run the following command, where `` is the `rpc-username`, and `` is the plaintext version of `rpc-password` in `settings.json`: ```sh echo "machine localhost login password " >> ~/.netrc ``` Then, to authenticate, run: ```sh transmission-remote --netrc ``` Subsequent `transmission-remote` commands will not require entering your credentials. #### \-\-auth Flag The second method to authenticate is to include an `auth` flag in every `transmission-remote` command you execute. Substituting your credentials for `username` and `password`, you can enter the following command to list your torrents: ```sh transmission-remote --auth=username:password --list ``` At this point, you should be able to use `transmission-remote` on your server to manage your torrents. ### Hosting Torrents Here is a cookbook of common `transmission-remote` commands for hosting torrents. Add a torrent via a magnet link: ```sh transmission-remote --add "magnet:link" ``` Add a torrent via a .torrent file: ```sh transmission-remote --add "your.torrent" ``` List the status of your torrents (and get their numerical IDs): ```sh transmission-remote --list ``` Get information about a specific torrent (where `ID` is the torrent ID from the prior command): ```sh transmission-remote --torrent=ID --info ``` Remove a torrent and keep its data (where `ID` is the torrent ID): ```sh transmission-remote --torrent=ID --remove ``` Remove a torrent and delete its data (where `ID` is the torrent ID): ```sh transmission-remote --torrent=ID --remove-and-delete ``` Get information about the current Transmission session: ```sh transmission-remote --session-info ``` Get statistics about the current Transmission session: ```sh transmission-remote --session-stats ``` ### Downloading Completed Torrents via Secure Shell Completed torrent downloads will be saved in the directory indicated by `download-dir` in your configuration. (This is `/var/lib/transmission-daemon/downloads` by default.) You should be able to download those files and directories from your seedbox using tools like [`rsync`], `(s)ftp`, and `scp`. [`rsync`]: ../rsync/ If this is sufficient for you, you do not need to configure Transmission for remote access. ## Creating New Torrents `transmission-create` is used to create torrents. It was installed automatically on your server when you installed `transmission-daemon`. You can use it on any machine that has it installed and has a copy of the file or directory you want to share. (`transmission-edit` is also available to edit .torrent files. It can do things like add and delete tracker urls. However, this tool tends to be more useful when working with other\'s .torrent files and less so when creating torrents from scratch.) ### Creating the .torrent File Here is a template command for creating a .torrent file: ```sh transmission-create --outfile "my.torrent" \ --comment "My cool torrent" \ --tracker "https://tracker1.example.org/announce" \ --tracker "https://tracker2.example.org/announce" \ "path/to/my/file/or/directory" ``` * `outfile` specifies where to write the .torrent file. * `comment` specifies a comment for the torrent. * `tracker` specifies a torrent tracker to use. You can have multiple of these. `udp://open.tracker.cl:1337/announce` is usually a good choice, but there are many others. * The path indicates the file or directory you want to make a torrent of. ### Generating the Magnet Link `transmission-show` is used to generate magnet links from .torrent files, and it was installed when you installed `transmission-daemon`. Given any .torrent file, you can run: ```sh transmission-show --magnet "my.torrent" ``` ### Seeding Your New Torrent First, copy the file or directory that you are hosting to the download directory (`download-dir`) specified in the `transmission-daemon` configuration. If the `download-dir` is at the default, you could write: ```sh cp "the-file-or-directory-to-share" \ "/var/lib/transmission-daemon/downloads/" ``` Then, add your torrent to Transmission via your .torrent file or magnet link: ```sh transmission-remote --add "the-torrent-file-or-magnet-link" ``` Your server should begin seeding your torrent, and you can share it via the .torrent file or magnet link. **Warning:** Make sure you copy the file or directory you are seeding to the `download-dir` directory *before* adding the torrent to Transmission. If you copy the source file/directory into your download directory *after* adding the torrent, run `transmission-remote` to get the ID of your torrent: ```sh transmission-remote --list ``` Then, where `ID` is the ID of the torrent, run this command so Transmission will know it already has the data: ```sh transmission-remote --torrent=ID --verify ``` The torrent should then begin seeding. ## Controlling Transmission Remotely At this point, you should be able to manage your seedbox locally by using `transmission-remote` on your server via secure shell. However, it may be convenient to also configure the box for remote access. You can do this by exposing Transmission\'s HTTP API, which includes a web app. The Transmission web app acts as a graphical stand-in for `transmission-remote`. You can manage your torrents and the daemon with it. Similar to `transmission-remote` itself, however, you cannot download completed torrents via the web app. (That requires serving the files via a different channel, whether that be `rsync`, `sftp`, `scp`, `http(s)`, etc. Serving completed torrents via `http(s)` is explained later.) Exposing Transmission\'s HTTP interface to the internet additionally allows you to control your seedbox from a different machine using `transmission-remote`. ### Configuring Remote Access By default, `transmission-daemon` only allows RPC commands from `localhost`. For remote access, it must allow connections from the IP addresses you want to access the daemon from. The most direct way of doing this is by disabling the whitelist, which allows all IP addresses, but you can specify a whitelist if you like. Stop `transmission-daemon`: ```sh service transmission-daemon stop ``` Then, set `rpc-whitelist-enabled` to `false` in your configuration. This makes it so that any IP address can connect and control `transmission-daemon`. (You will just need your `rpc-username` and the plaintext version of your `rpc-password` to authenticate.) Alternatively, if you want to use the whitelist, set `rpc-whitelist-enabled` to `true`, and set `rpc-whitelist` to a comma-separated list of IP addresses. (Asterisks are used as wildcards.) For example, you could write: ``` 101.125.137.168,89.72.*.221 ``` While you have the configuration open, take note of the value of `rpc-port`, which is 9091 by default. This value will be necessary for configuring remote access. After saving your configuration, start `transmission-daemon`: ```sh service transmission-daemon start ``` ### Running Nginx as a Reverse Proxy It is possible to open remote access to `transmission-daemon` simply by opening its `rpc-port` in the firewall, 9091 by default. This connection will be run over insecure HTTP, so your username and password will be sent unencrypted. While this may be acceptable when testing a system, it is generally preferable to use a web server with TLS as a reverse proxy to Transmission\'s HTTP interface. If you are already running nginx with working TLS, allowing access to Transmission\'s web interface simply requires adding a `location` block to your `server` block in your nginx configuration. Assuming `rpc-port` is 9091, and `rpc-url` is `/transmission/` in your `transmission-daemon` configuration, add the following block to your nginx configuration: ```nginx location /transmission/ { proxy_pass http://localhost:9091/transmission/ ; } ``` Reload nginx so your changes takes effect: ```sh nginx -s reload ``` At this point, if `example.org` is your domain, and you are connected from a permitted IP address: * The Transmission web app will be available at `https://example.org/transmission/web/`. * `transmission-remote` will be able to connect to `https://example.org/transmission`. (Note the omission of the trailing forward slash.) #### Serving Transmission at a Different Path By default, Transmission serves it\'s interface at the path `/transmission/`. You can change this in the configuration, but note that your chosen path must start and end with a forward slash. For example, to serve Transmission\'s interface at `/~luke/torrents/`: 1. Stop the `transmission-daemon` service. 2. Set `rpc-url` in the configuration to your chosen path. That is `/~luke/torrents/` in this example. 3. Modify the `location` block\'s path pattern and `proxy_pass` url in your nginx configuration to use the new path (and the correct `rpc-port`). For this example, that is: ```nginx location /~luke/torrents/ { proxy_pass http://localhost:9091/~luke/torrents/ ; } ``` 4. Start the `transmission-daemon` service. 5. Reload nginx. The Transmission web app will then be accessible at `https://example.org/~luke/torrents/web/`. `transmission-remote` will be able to connect to `https://example.org/~luke/torrents`. ### Connecting via a Browser Where `example.org` is your website, and `/transmission/` is the `rpc-url` in your `transmission-daemon` configuration, point your web browser to `https://example.org/transmission/web/`. After entering your credentials into the login (using your `rpc-username` and plaintext `rpc-password`), you will be greeted by the web interface with a list of your torrents. Here is a Transmission instance that is downloading one torrent: {{A screenshot of the Transmission web interface}} ### Connecting via Transmission-Remote You can control `transmission-daemon` on your server from other machines that have `transmission-remote` installed. You do this by calling `transmission-remote` with a url consisting of the domain name (or IP), the `rpc-port`, and the path specified by `rpc-url` in the configuration (`/transmission/` by default) with the trailing forward slash omitted. For example, after inserting your credentials for `username` and `password`, assuming the `rpc-url` is at the default of `/transmission/`, you could invoke the following command on your local machine to list the status of the torrents on your server: ```sh transmission-remote https://example.org/transmission \ --auth=username:password \ --list ``` Note how the `rpc-url` is `/transmission/`, but `/transmission` is specified in the command. **Warning:** The Transmission web app and `transmission-remote` both allow you to make changes to Transmission\'s port settings. Be careful change these, because you might also need to update your server\'s firewall configuration. ## Serving Complete Torrent Downloads via HTTP(S) The Transmission web interface and `transmission-remote` do not allow you to download completed torrents from your seedbox via HTTP(S). However, in some scenarios, downloading via HTTP(S) may be preferable where shell access and other supporting tools (`rsync`, `scp`, `sftp`, `ftp`, etc.) are unavailable on the client machine. Serving completed torrent downloads involves configuring nginx to serve the `download-dir` of `transmission-daemon`. (Serving completed torrent downloads via HTTP(S) does not require exposing Transmission\'s HTTP API and web app.) **Warning:** The Transmission interfaces give you the option of saving completed torrent downloads to directories other than the `download-dir` specified in your `transmission-daemon` configuration. Downloading a torrent to a different directory and not serving that directory with nginx will prevent that completed torrent from being served to clients via the static file server shown here. Assuming you wish to serve your completed torrents from the directory `/downloads/` on your web server, and `download-dir` is at the default of `/var/lib/transmission-daemon/downloads/`, you can add this `location` block into the `server` block of your nginx configuration: ```nginx location /downloads { root /var/lib/transmission-daemon/downloads ; proxy_max_temp_file_size 0 ; autoindex on ; } ``` Note how the trailing forward slash has been omitted in both the `location` pattern and the `root` path. The `proxy_max_temp_file_size` option prevents disk caching that would potentially break nginx\'s ability to serve files larger than a few gigabytes. If you omit the `autoindex` option or set it to `off`, nginx will not show a directory listing of your downloaded torrents. (You will need the direct link to download a given torrent.) After saving the configuration, reload nginx. Where `example.org` is your website, and assuming `autoindex` is `on`, opening `https://example.org/downloads/` in a web browser should show a list of links to download your completed torrents. While downloading via HTTP(S) can be convenient, resuming interrupted downloads can be a nuisance. See [Appendix 2] for tips on how to combat this. [Appendix 2]: #appendix-2-reliable-downloading-via-https ### Preventing Unauthorized Downloading If you want to prevent others from downloading completed torrents via HTTP(S) from your seedbox, you have a few options: 1. When defining the nginx `location` block, you can use some random string for the path match pattern, like `/DJRmdL8HPn`. Only those who know the path will able to download your completed torrents. 2. You can protect the directory with a username and password using [HTTP basic authentication]. [HTTP basic authentication]: ../auth/ ## Troubleshooting `journalctl` can be used to view the logs of `transmission-daemon`. For example, you could run: ```sh journalctl | grep transmission-daemon ``` Transmission\'s [documentation] contains help and answers to common questions. [documentation]: https://github.com/transmission/transmission/blob/main/docs/README.md ## Appendix 1: What is BitTorrent? Many protocols for sending files over the internet, such as Hypertext Transfer Protocol (HTTP) and File Transfer Protocol (FTP), operate on a \"client-server\" (or \"server-client\") model. A server will store a file. A client will send a request for the file from the server. If the request is accepted, the server will respond with the file. In contrast, BitTorrent is a decentralized, peer-to-peer, file-sharing protocol. Instead of relying on a dedicated server, a file will be assembled by downloading it in chunks from many different hosts. Anyone who has the file (or pieces of it) can then help serve the file to others. This makes file-sharing via BitTorrent much less susceptible to data loss and downtime than the client-server model since the file can be replicated and shared across a potentially large number of independent hosts. The individual hosts are called \"peers\". The process of a host offering their copy of the file for download to others is called \"seeding\". The set of peers collectively hosting the file is called a \"swarm\". The peers usually find out about each other using \"trackers\", dedicated servers that help peers find those who possess or want a specific file. Trackers are identified by URLs. A peer can \"announce\" to a tracker that it possesses a specific file. If a peer wants to download a file, the peer can ask the tracker for peers that possess the file. Trackers do not actually transfer the torrent between peers. They simply facilitate peer-discovery. The BitTorrent network also uses other mechanisms for peer-discovery, including a \"DHT\", or Distributed Hash Table. Similar to trackers, these help peers find each other. Unlike trackers, a DHT is entirely peer-to-peer as it is based on a distributed data structure rather than a dedicated server. The DHT that BitTorrent uses is called the Mainline DHT. Most modern torrent clients will give you the option of using it to help you find peers. (Transmission supports it.) Before downloading a desired file or directory, you will need its .torrent file or magnet link. These are usually distributed via webpages, and they contain metadata and other information required for downloading the file, including: * The cryptographic hash of the file for validating its integrity. (A .torrent file will also include hashes for individual chunks of the file.) * The name of the torrent. * A list of tracker URLs to use for finding peers. Once the .torrent file or magnet link has been imported into a torrent client, the client will query the network to discover peers that possess the file. The swarm will then work together to send the user the file in chunks. The chunks will be cryptographically validated and assembled to create the final file. After the user has downloaded the file (or even if they only have pieces of it), they also can be part of the swarm by helping to seed the file to others who want it. \"Leeching\" is when a user downloads torrents and does not seed them to others. This practice hurts the overall functioning of the swarm and will also usually reduce the bandwidth that other peers are willing to dedicate to you in the future. Always reseed. 🌱 ## Appendix 2: Reliable Downloading via HTTP(S) Downloading via HTTP(S) can be very convenient when shell access is unavailable. It can also be very troublesome with large files due to interrupted or corrupted downloads. Thankfully, utilities like `wget` and `zsync` can help combat this. ### wget `wget` supports resuming interrupted downloads. It isn\'t as robust for this use case as other utilities (like `zsync`), but it can be convenient because: * It doesn\'t require any extra setup on your server. * It comes preinstalled on most \*nix systems. Supposing you want to download a very large file from your web server and save it to your current directory, you might run: ```sh wget https://example.org/downloads/large.file ``` If this command is stopped or interrupted, running it again with the `--continue` flag will cause `wget` to resume your download: ```sh wget --continue https://example.org/downloads/large.file ``` If your network connection is particularly poor, you can also specify the `--tries=0` flag. `wget` will retry connecting indefinitely, so you don\'t need to run the command multiple times if it disconnects. One major downside of using `wget` is that the resumption of the download is based on the difference between the file length on the server and the length of the partial file on your disk. No cryptography or checksum is used to validate the file's integrity. `wget` also supports downloading directories, but this can be finicky. You might need to experiment with the arguments depending on the contents of the directory. For example, assuming directory listing is enabled in the relevant directory on your web server, you might run a command like: ```sh wget --recursive --no-parent \ https://example.org/downloads/large-directory/ ``` The `--recursive` flag indicates that `wget` should download the contents of the directory as well as its subdirectories up to 5 levels deep. The `--no-parent` flag indicates that `wget` should not download any files at higher levels in the directory hierarchy. **Note:** Enabling `autoindex` for a directory in nginx implicitly creates `index.html` files in the directory and its subdirectories from the perspective of HTTP(S) clients like `wget`. However, the `--reject index.html` flag is omitted in the above command because `wget` needs the links in those index files to download all of the files in the target directory. (In fact, for this reason, the above command might potentially fail to download all the files in the directory if the target directory contains `index.html` files.) Once the directory has been downloaded to your disk, you would then need to delete the `index.html` files that were created by the web server's directory listing in your downloaded copy. Additionally, the actual directory structure created on your disk with this example would be `example.org/downloads/large-directory/`, not `large-directory/`. ### zsync `zsync` is another option for more reliable HTTP(S) downloading. The advantages of `zsync` include: * It offers significantly more data validation than `wget` by using hashes and checksums. * By using the `-i` flag, you can specify file chunks you have on disk from the same or similar downloads to potentially accelerate the current download. The disadvantages of `zsync` include: * It does not usually come pre-installed on *nix systems. * Unlike `wget`, it does not support downloading directories. It only supports files. * It must be installed on the client-side. * It requires additional setup on the server-side. `zsync` is available in the Debian repositories. Install it on your server by running: ```sh apt install zsync ``` (You will also need to install it on your client machine.) On your server, change your directory to your torrent download directory, `/var/lib/transmission-daemon/downloads/` by default. Then, run `zsyncmake` by providing the url and name of the file you want to use `zsync` on: ```sh zsyncmake -u "https://example.org/downloads/large.file" large.file ``` This will create a new file with the same name as your original file but with the `.zsync` extension added: `large.file.zsync` in this case. (Note that if the file you are sharing changes, you need to regenerate the `.zsync` file.) If you view your torrent download directory in a browser, and nginx has `autoindex` turned `on`, you should notice the addition of the `.zsync` file in the directory. On your HTTP(S) client, where the provided url is the link to the new `.zsync` file, run: ```sh zsync "https://example.org/downloads/large.file.zsync" ``` If your download is interrupted, just run the command again, and `zsync` will read your partial download, resume it, checksum it, and cleanly assemble the target file, `large.file`. If your downloads directory is protected with HTTP basic authentication, you can specify your credentials by adding an `-A` flag before the URL: ```sh zsync -A example.org=username:password \ "https://example.org/downloads/large.file.zsync" ``` If you have a piece of the file with a different name or a different version of the file, you can specify those pieces with the `-i` flag to potentially reduce what `zsync` needs to fetch over the network: ```sh zsync -i "large.file.piece" -i "large.file.old" \ "https://example.org/downloads/large.file.zsync" ``` `zsync` will attempt to look for file chunks in `large.file.piece` and `large.file.old` that can be used to help assemble `large.file`. For example, if you have a Linux ISO on your computer, and you want to download an updated version from your seedbox, there\'s a good chance that only certain sections of the ISO changed from the version you already have. You can specify the old version of the ISO you have with the `-i` flag to potentially reuse chunks from the old version when downloading the new ISO. --- *Written by: Luke Hamann*