mirror
/
transmission
mirror of https://github.com/transmission/transmission
1
0
Fork 0
Code Issues Releases Wiki Activity

Improve the documentation (#2900) 

* Unify the line endings to the Unix style (LF only).

* Fix (where possible) or remove broken links.

* Improve the documentation.

Fix or remove broken links (depending on whether I could find a
working version of the resource).

Change all links to use HTTPS instead of HTTP.

Unify the capitalizations (e.g. uppercase abbreviations, capitalize
proper names and downcase other words).

Fix or improve some parts of the text, clarifying what is meant.

Improve some parts of the program examples (e.g. only use root
privileges where really required).
This commit is contained in:
maxz 2022-04-11 19:38:32 +02:00 committed by GitHub
parent 70fbce71ec
commit 7c76d40a4d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
23 changed files with 343 additions and 513 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/Blocked-Traffic.md
View File

@ -4,7 +4,7 @@
Some ISPs are blocking all BitTorrent traffic to save money or to avoid a high load on their network. Some analyze the packets and filter by type, some just block known ports.
## Tips ##
* Configure your Transmission to accept encrypted peers only
* Change your Transmission port
* Use a tunnel
* Use a proxy
* Configure your Transmission to accept encrypted peers only.
* Change your Transmission port.
* Use a tunnel.
* Use a proxy.

27
docs/Blocklists.md
View File

@ -1,38 +1,33 @@
A Blocklist is third-party list of peer addresses to block. This can be used to block peers whose addresses are believed to belong to spyware or malware manufacturers.
A blocklist is third-party list of peer addresses to block. This can be used to block peers whose addresses are believed to belong to spyware or malware manufacturers.
## What blocklist does Transmission Use? ##
## What blocklist does Transmission use? ##
Transmission supports the [P2P plaintext format](https://en.wikipedia.org/wiki/PeerGuardian#P2P_plaintext_format), which is used by PeerGuardian, Bluetack, Vuze, ProtoWall, and KTorrent, and the DAT format, which was originally made popular by eMule.
Transmission supports the [P2P Plaintext Format](http://en.wikipedia.org/wiki/PeerGuardian), which is used by PeerGuardian, Bluetack, Vuze, ProtoWall, and KTorrent, and the DAT format, which was originally made popular by eMule.
The Transmission Project does not evaluate or endorse any specific blocklists. If you do not know what blocklist to use, you might [read about some third-party blocklists](https://www.google.com/search?q=blocklist+url) and evaluate them on your own.
The Transmission Project does not evaluate or endorse any specific blocklists. If you do not know what blocklist to use, you might [read about some third-party blocklists](http://www.google.com/search?q#blocklist+url) and evaluate them on your own.
If "Enable automatic updates" is enabled, Transmission will periodically refresh its copy of your blocklist from your specified URL.
If "Enable automatic updates" is enabled, Transmission will periodically refresh its copy of your blocklist from the specified URL.
When you press the "Update Blocklist" button, Transmission will download a new copy of your blocklist.
## Adding Other Blocklists ##
## Adding other blocklists ##
Transmission stores blocklists in a folder named `blocklists` in its [configuration folder](Configuration-Files.md).
In that directory, files ending in ".bin" are blocklists that Transmission has parsed into a binary format suitable for quick lookups. When transmission starts, it scans this directory for files not ending in ".bin" and tries to parse them. So to add another blocklist, all you have to do is put it in this directory and restart Transmission. Text and gzip formats are supported.
In that directory, files ending in ".bin" are blocklists that Transmission has parsed into a binary format suitable for quick lookups. When Transmission starts, it scans this directory for files not ending in ".bin" and tries to parse them. So to add another blocklist, all you have to do is put it in this directory and restart Transmission. Text and gzip formats are supported.
## Using Blocklists in transmission-daemon ##
## Using blocklists in transmission-daemon ##
transmission-daemon does not have an "update blocklist" button, so its users have two options. They can either copy blocklists from transmission-gtk's directory to transmission-daemon's directory, or they can download a blocklist by hand, uncompress it, and place it in the daemon's `blocklists` folder. In both cases, the daemon's [settings.json file](Configuration-Files.md) will need to be edited to set "blocklist-enabled" to "true".
transmission-daemon doesn't have an "update blocklist" button, so its users have two options. They can either copy blocklists from transmission-gtk's directory to transmission-daemon's directory, or they can download a blocklist by hand, uncompress it, and place it in the daemon's `blocklists` folder. In both cases, the daemon's [settings.json file](Configuration-Files.md) will need to be edited to set "blocklist-enabled" to "true".
Also in both cases, the daemon is unaware of blocklist updates. Only when it starts it creates new .bin files.
In both cases the daemon is unaware of blocklist updates. Only when it starts it creates new .bin files.
There is a third option: add the blocklist URL in settings.json (only one blocklist is allowed), and use transmission-remote to tell the daemon to update it periodically.
settings.json snippet:
```json
"blocklist-enabled": true,
"blocklist-url": "http://www.example.com/blocklist",
```
update by hand example:
Manual update example:
```console
$ transmission-remote -n admin:password --blocklist-update
localhost:9091/transmission/rpc/ responded: "success"

68
docs/Bug-Submission.md
View File

@ -1,71 +1,65 @@
# Submitting a Bug Report #
If you're having trouble with Transmission then the things you should do in order are:
# Submitting a bug report #
If you are having trouble with Transmission then the things you should do in order are:
1. Make sure you are running the current release
1. Search the documentation
1. For a bug, ideally we'd like you to check if it still exists in the [nightly build](https://build.transmissionbt.com/).
1. For a bug, ideally we would like you to check if it still exists in the [nightly build](https://build.transmissionbt.com/).
1. Search the Issue Tracker to see if your concern has already been reported:
* [All open tickets](http://trac.transmissionbt.com/report/2)
* [Search](http://trac.transmissionbt.com/search)
1. If you _don't_ see a ticket matching your problem or feature
* read the section below on **Submitting a Bug Report**
* [add a new ticket](http://trac.transmissionbt.com/newticket).
* [All open tickets](https://trac.transmissionbt.com/report/2)
* [Search](https://trac.transmissionbt.com/search)
1. If you _do not_ see a ticket matching your problem or feature
* Read the section below on **Submitting a bug report**
* [Add a new ticket](https://trac.transmissionbt.com/newticket).
If you _do_ see an existing ticket, please add a comment there again adding as much information as possible.
The more users interested in a ticket, the higher priority it's given.
The more users are interested in a ticket, the higher its priority will be.
## Information Required in a Bug Report ##
* State the version of Transmission you're using (e.g. Linux/GTK+ 1.80).
If you're using a GUI version of Transmission, you can find its version in the `About` dialog in the Help menu.
**Don't** say _the latest version_ it's ambiguous.
## Information required in a bug report ##
* State the version of Transmission you are using (e.g. Linux/GTK+ 1.80).
If you are using a GUI version of Transmission, you can find its version in the `About` dialog in the Help menu.
**Do not** say _the latest version_ it's ambiguous.
* State what operating system and version (e.g. Mac OS X 10.5.8, Ubuntu 8.04, ...)
* Describe the symptoms in a short precise manner.
* Describe the symptoms in a short yet precise manner.
* If the problem is reproducible and you explain how to reproduce it, then it stands a high chance of being addressed.
If the problem is intermittent then we still want to know, but if you can't tell us how to reproduce it we can't easily work on it.
If the problem is intermittent then we still want to know, but if you can not tell us how to reproduce it we cannot easily work on it.
* See if the problem only occurs under certain conditions.
E.g.: If you're seeing the bug with 50 torrents running and speed limits turned on, see if it persists with speed limits turned off.
See if it persists with 1 torrent running. See if it persists after pausing and restarting the torrent. etc.
E.g.: If you are seeing the bug with 50 torrents running and speed limits turned on, also check if it persists with speed limits turned off.
See if it persists with 1 torrent running. See if it persists after pausing and restarting the torrent, etc.
**The more work you do to narrow down the bug, the more chance we have of finding and fixing it.**
**The more work you do to narrow down the bug, the higher our chance of finding and fixing it.**
## Reporting specific types of problems ##
Additional information or steps are required for certain categories of problem:
### Slow Speeds ###
If you're experiencing slow speeds and you've been through the wiki, then please provide the following information **in addition** to that above:
### Slow speeds ###
If you are experiencing slow speeds and you have been through the documentation, then please provide the following information **in addition** to the above:
* Do you have any per-torrent or global speed limits set?
* What are your global and per-torrent peer limits?
* How many seeds and peers does the "Peers" tab say there are in the swarm?
* How long ago does the "Tracker" tab say the last announce and scrape results were?
* In the "Tracker" tab's list of trackers, how many Tiers are there, and how many trackers are listed for each tier?
* How long ago does the "Tracker" tab say the last announce and scrape results were obtained?
* In the "Tracker" tab's list of trackers, how many tiers are there, and how many trackers are listed for each tier?
* How many peers are you connected to?
* Has your torrent finished downloading?
* If you're still downloading, do any of the connected peers have a higher "completed" percentage than you?
* If you are still downloading, do any of the connected peers have a higher "completed" percentage than you?
* Is your incoming peer port open or closed?
The "Peers" and "Tracker" tabs are in the dialog named "Inspector" on the Mac GUI and "Torrent Properties" on the GTK+ GUI.
### Crash on the Mac ###
If you have problems on the Mac version then please do these extra steps:
* Make sure your system is updated to the latest version of your operating system. Note As of 1.60 Transmission requires Mac OS X 10.5 or later.
* If you're running a nightly build, set the language to English. The localizations will sometimes crash the nightly builds until they are updated right before an official release.
* Make sure your system is updated to the latest version of your operating system. Note as of version 1.60, Transmission requires Mac OS X 10.5 or later.
* If you are running a nightly build, set the language to English. The localization will sometimes crash the nightly builds until they are updated (right before an official release).
* OS X collects two pieces of crash information that can help us fix the crash:
1. In Console.app, look under LOG FILES > ~/Library/Logs/ > CrashReporter > for Transmission. If you find one, include it in your forum post.
2. In Console.app, select LOG DATABASE QUERIES > Console Messages, and search for Transmission. If you find a message that mentions an assertion failure, include it in your forum post.
If these two pieces of information above are too large for your forum post, Paste them [here](http://transmission.pastebin.com/), click the "one month" and "send" buttons, and include the pastebin's URL in your forum post.
### Port Mapping Error ###
If the two pieces of information above are too large for your forum post, paste them [here](https://pastebin.com/), choose a paste expiration of one month and click the "Create New Paste" button. Then include the pastebin's URL in your forum post.
### Port mapping error ###
Read the [Port Forwarding Guide](Port-Forwarding-Guide.md) first.
You then need to include:
* what router you're using
* that you've confirmed that either UPnP or NAT-PMP is enabled on it
* If you're using a custom firmware, tell us which one
* Most importantly, post the lines from the Message Log that contain the phrase "Port Mapping". They will look something like this:
* What router you are using
* That you have confirmed that either UPnP or NAT-PMP is enabled on it
* If you are using a custom firmware, tell us which one
* Most importantly, post the lines from the message log that contain the phrase "Port Mapping". They will look something like this:
```
02:12:27 Port Mapping (NAT-PMP): initnatpmp returned success (0)

85
docs/Building-Transmission.md
View File

@ -1,9 +1,7 @@
## Getting the Source ##
Source code for both official and nightly releases can be found on our [download page](https://transmissionbt.com/download/).
The source code for both official and nightly releases can be found on our [download page](https://transmissionbt.com/download/).
## On Mac OS X ##
Transmission has an Xcode project file (Transmission.xcodeproj) for building in Xcode. Make sure you have this software:
* OS X 10.10 or newer
* OS X 10.10 SDK
@ -15,11 +13,8 @@ If building from source is too daunting for you, check out the [nightly builds](
(Note: These are untested snapshots. Use them with care.)
## On Unix ##
### Prerequisites ###
#### Ubuntu ####
On Ubuntu, you can install the required development tools with this command:
```console
@ -29,25 +24,20 @@ $ sudo apt-get install build-essential automake autoconf libtool pkg-config intl
_After you install those you can skip [to this section](#building-from-a-tarball)._
#### Debian Squeeze ####
Sometimes you have a need to stay current with upstream releases, even though you would like to rely on the stability of your base distribution. Here is how this can be accomplished in "quick and dirty" fashion. Lines started with a # are to be executed as root, lines starting with $ can be run as a regular user.
Sometimes you have a need to stay current with upstream releases, even though you would like to rely on the stability of your base distribution. Here is how this can be accomplished in a "quick and dirty" fashion. Lines starting with a # have to be executed as root, lines starting with $ should be run as a regular user.
1. Dependencies
First let us install every dependency Transmission needs and for which there is a usable version in the Debian repository.
```console
# apt-get install ca-certificates libcurl4-openssl-dev libssl-dev pkg-config build-essential checkinstall
```
2. libevent
Traditionally, libevent is also needed, but Transmission depends on version numbers only rarely found in Debian. So let us start by compiling libevent in a directory of your choice. Browse to http://libevent.org/ and get the latest version.
Traditionally libevent is also needed, but Transmission depends on version numbers only rarely found in Debian. So let us start by compiling libevent in a directory of your choice. Browse to https://libevent.org/ and get the latest version.
```console
$ cd /var/tmp
$ wget https://github.com/downloads/libevent/libevent/libevent-2.0.18-stable.tar.gz
$ tar xzf libevent-2.0.18-stable.tar.gz
$ tar xf libevent-2.0.18-stable.tar.gz
$ cd libevent-2.0.18-stable
$ CFLAGS="-Os -march=native" ./configure && make
```
@ -59,21 +49,20 @@ Sometimes you have a need to stay current with upstream releases, even though yo
```
3. Transmission
Now we need to prepare Transmission for compilation by configuring the source, the same as with libevent.
Now we need to prepare Transmission for compilation by configuring the source, just as with libevent.
```console
$ cd /var/tmp
$ wget http://download-origin.transmissionbt.com/files/transmission-2.51.tar.bz2
$ tar xjf transmission-2.51.tar.bz2
$ wget https://download-origin.transmissionbt.com/files/transmission-2.51.tar.bz2
$ tar xf transmission-2.51.tar.bz2
$ cd transmission-2.51
# CFLAGS="-Os -march=native" ./configure && make && checkinstall
$ CFLAGS="-Os -march=native" ./configure && make
# checkinstall
```
_Thanks to josen at http://falkhusemann.de/blog/2012/05/compiling-transmission-bittorrent-for-debiand/ for the original Debian Squeeze howto section._
_Thanks to josen at https://falkhusemann.de/blog/2012/05/compiling-transmission-bittorrent-for-debiand/ for the original Debian Squeeze HowTo section._
#### CentOS 5.4 ####
The packages you need are:
* gcc
* gcc-c++
@ -85,18 +74,16 @@ The packages you need are:
* openssl-devel
Or simply run the following command:
```console
$ yum install gcc gcc-c++ m4 make automake libtool gettext openssl-devel
```
However, Transmission needs other packages unavailable in `yum`:
* [pkg-config](http://pkg-config.freedesktop.org/wiki/)
* [libcurl](http://curl.haxx.se/)
* [intltool](http://ftp.gnome.org/pub/gnome/sources/intltool/)
* [pkg-config](https://pkg-config.freedesktop.org/wiki/)
* [libcurl](https://curl.haxx.se/)
* [intltool](https://ftp.gnome.org/pub/gnome/sources/intltool/)
Before building Transmission, you need to set the pkgconfig environment setting:
```console
$ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
```
@ -104,40 +91,36 @@ $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
_After you install those you can skip [to this section](#building-from-a-tarball)._
#### Normal ####
If this is your first time compiling on Unix, you'll need a few basic tools:
If this is your first time compiling on Unix, you will need a few basic tools:
* gcc
* libtool
* gettext 0.14.1 or newer
* intltool 0.40 or newer
If you're planning to build from source:
If you are planning to build from source:
* automake 1.9 or newer
* autoconf 2.54 or newer
Once you've got the basics out of the way, here are the libraries that Transmission needs to have in order to build:
* OpenSSL 0.9.8 or newer, preferably ssl or gnutls support.
Once you have got the basics out of the way, here are the libraries that Transmission needs to have in order to build:
* OpenSSL 0.9.8 or newer, preferably SSL or GnuTLS support.
* libcurl 7.16.3 or newer
* GTK+ 2.6 or newer (only needed by the GTK+ gui)
* libnotify 0.4.4 (optional, and only needed by the GTK+ gui)
* DBUS 0.70 (optional, and only needed by the GTK+ gui)
* GTK+ 2.6 or newer (only needed by the GTK+ GUI)
* libnotify 0.4.4 (optional and only needed by the GTK+ GUI)
* DBUS 0.70 (optional and only needed by the GTK+ GUI)
#### RPM users ####
_You'll also need to install the corresponding `-devel` packages._
_You will also have to install the corresponding `-devel` packages._
### Building from a tarball ###
```console
$ tar xvjf transmission-1.76.tar.bz2
$ tar xf transmission-1.76.tar.bz2
$ cd transmission-1.76
$ ./configure -q && make -s
$ su # if necessary for the next line
$ make install
# make install
```
### Building Transmission from Git (first time) ###
```console
$ git clone https://github.com/transmission/transmission Transmission
$ cd Transmission
@ -151,7 +134,6 @@ $ sudo make install
```
### Building Transmission from Git (updating) ###
```console
$ cd Transmission/build
$ make clean
@ -164,18 +146,16 @@ $ sudo make install
```
## On Windows ##
For Windows XP and above there are several choices:
### Cygwin environment ###
With Cygwin https://cygwin.com/ installed, the CLI tools (transmission-remote, transmission-cli, etc.) and the daemon can be built easily.
With Cygwin http://cygwin.com/ installed, the CLI tools (transmission-remote, transmissioncli, etc.) and the daemon can be built easily.
No patches needed(\*), all the recent versions of Transmission build almost out-of-the-box (you need to install the prerequisites), and the CLI tools work better under Cygwin than those built with MinGW.
No patches needed(\*), all the recent versions of Transmission built almost out-of-the-box (you need to install the prerequisites), and the CLI tools work better under Cygwin that those built with MinGW.
(\*) At the release time of version 2.0, **libevent** is not bundled and it is also not in the Cygwin distribution (but was added later)... so you need to build it (which is as easy as ./configure, make install). To build Transmission you may need to add LDFLAGS="-L/usr/local/lib" to the configure script (LIBEVENT_LIBS does not seem to work when it comes to build all the test programs). Additionally **libutp** needs deleting -ansi on the Makefile.
(\*) At the release time of version 2.0, **libevent** is not bundled and it's also not in Cygwin distribution (but was added later)... so you need to build it (which is as easy as ./configure, make install). To build transmission you may need to add LDFLAGS="-L/usr/local/lib" to the configure script (LIBEVENT_LIBS doesn't seem to work when it comes to build all the test programs). Additionally **libutp** needs deleting -ansi on the Makefile.
With version 2.51 miniupnpc fails to build, see http://miniupnp.tuxfamily.org/forum/viewtopic.php?t#1130.
With version 2.51 miniupnpc fails to build, see https://miniupnp.tuxfamily.org/forum/viewtopic.php?t#1130.
Version 2.80 breaks building on Cygwin, adding this https://github.com/adaptivecomputing/torque/blob/master/src/resmom/cygwin/quota.h file to Cygwin's /usr/include/sys solves the problem. This is no longer needed after version 2.82 (Cygwin added the header).
@ -184,15 +164,14 @@ Version 2.81 with the above workaround needs a one line patch, see ticket #5692.
Version 2.82, same as 2.81.
Version 2.83, no need to add quota.h, Cygwin added it.
### Native Windows ###
With a MinGW http://mingw.org/ development environment, the Gtk and the Qt GUI applications can be built. The CLI tools can also be built, and in general work fine, but may fail if you use foreign characters as parameters (MinGW uses latin1 in parameters).
### Native Windows ###
With a MinGW https://mingw.org/ development environment, the GTK and the Qt GUI applications can be built. The CLI tools can also be built and in general work fine, but may fail if you use foreign characters as parameters (MinGW uses latin1 for parameters).
The procedure is documented at [Building Transmission Qt on Windows](https://trac.transmissionbt.com/wiki/BuildingTransmissionQtWindows).
## Switches ##
The transmission `./configure` (or `./autogen.sh`) script allows you to switch on/off certain parts. To use these, you'll either use `--enable-*` or `--disable-*`. e.g. To disable the GTK client: `--disable-gtk`.
The Transmission `./configure` (or `./autogen.sh`) script allows you to switch on/off certain parts. To use these, you will either use `--enable-*` or `--disable-*`, e.g. to disable the GTK client: `--disable-gtk`.
The switches that are available are:
* **gtk** = enables GTK+ client (default)
@ -202,6 +181,6 @@ The switches that are available are:
* **nls** = enables native language support (default)
* **mac** = enables Mac client (default, if possible)
* **wx** = enables wxWidgets client (unsupported)
* **beos** = enables beos client (unsupported)
* **beos** = enables BeOS client (unsupported)
Note: _`--disable-nls` removes the dependency on gettext and intltool. It's designed for, and should only be used on, [HeadlessUsage embedded devices]. If you do have GTK+ installed on your box, you must also specify `--disable-gtk`._
Note: _`--disable-nls` removes the dependency on gettext and intltool. It is designed for and should only be used on [HeadlessUsage embedded devices]. If you do have GTK+ installed on your box, you must also specify `--disable-gtk`._

7
docs/Can-I-sequence-the-files-I-download.md
View File

@ -1,24 +1,19 @@
Can I sequence the files I download? This is quite a common question. This entry will try to answer it and offer solutions.
## Why is this "feature" not implemented in Transmission?
Because it makes the overall swarm's health worse.
## But I want to sequence the files I download, how do I do it?
There're two methods basically, one DIY that requires a bit of code changing and the "user friendly" version.
There are basically two methods, one DIY method that requires some code modification and the "user friendly" version.
1. DIY code changing approach: Tweak _compareRefillPiece()_ in _libtransmission/peer-mgr.c_
Replace:
```c
/* otherwise go with our random seed */
return tr_compareUint16( a->random, b->random );
```
With:
```c
/* otherwise download the pieces in order */
return tr_compareUint16( a->piece, b->piece );

24
docs/Configuration-Files.md
View File

@ -1,7 +1,6 @@
## Locations
### Mac OS X Defaults
<table>
<tr><th>What</th><th>Where</th></tr>
<tr><td>Per-torrent settings</td><td><tt>$HOME/Library/Application Support/Transmission</tt></td></tr>
@ -10,7 +9,6 @@
</table>
### Linux / GTK Defaults
<table>
<tr><th>What</th><th>Where</th></tr>
<tr><td>GTK+/Qt client settings</td><td><tt>$HOME/.config/transmission</tt></td></tr>
@ -21,10 +19,9 @@
Some Linux distributions' start script for transmission-daemon use different location. This varies by distribution, but two paths sometimes used are `/var/lib/transmission-daemon` and `/var/run/transmission`.
If you want to swap between the two applications, all you have to do is pass in a different config directory with the -g command-line option. For example, to have the daemon pick up where the gtk+ client left off, run `transmission-daemon -g ~/.config/transmission`.
If you want to swap between the two applications, all you have to do is pass in a different config directory with the -g command-line option. For example, to have the daemon pick up where the GTK+ client left off, run `transmission-daemon -g ~/.config/transmission`.
### Windows Defaults
<table>
<tr><th>What</th><th>Where</th></tr>
<tr><td>Qt client settings</td><td><tt>%LOCALAPPDATA%/transmission</tt></td></tr>
@ -39,29 +36,22 @@ If you want to swap between the two applications, all you have to do is pass in
The per-user configuration folder's location can be overridden by setting `TRANSMISSION_HOME` and/or other [environment variables](Environment-Variables.md).
## Files
The configuration folder typically has the following files:
### settings.json
This is a json-encoded file that holds all the client's settings and preferences. It's currently only used by the daemon, GTK+ and CLI clients. json was chosen because it's mostly human-readable and -writable, but also allows data hierarchies to be stored. See the [Editing Configuration Files](Editing-Configuration-Files.md) page on how to modify them.
This is a JSON-encoded file that holds all the client's settings and preferences. It's currently only used by the daemon, GTK+ and CLI clients. JSON was chosen because it's mostly human-readable and -writable, but also allows data hierarchies to be stored. See the [Editing Configuration Files](Editing-Configuration-Files.md) page on how to modify them.
### stats.json
This is a json-encoded file that holds session statistics such as running upload and download byte counts.
This is a JSON-encoded file that holds session statistics such as running upload and download byte counts.
### torrents/
This subfolder holds the .torrent files that have been added to Transmission. The files in this folder are named with a combination of the torrent's name (to make it human-readable) and a portion of the torrent's SHA1 hash (to avoid filename collisions from similarly-named torrents).
This subfolder holds the .torrent files that have been added to Transmission. The files in this folder are named with a combination of the torrent's name (to make it human-readable) and a portion of the torrent's SHA1 hash (to avoid filename collisions from similarly-named torrents).
### resume/
This subfolder holds .resume files that hold information about a particular torrent, such as which parts have been downloaded, the folder the downloaded data was stored in, and so on. These follow an identical naming scheme to the files in the torrents subfolder.
This subfolder holds .resume files that hold information about a particular torrent, such as which parts have been downloaded, the folder the downloaded data was stored in, and so on. These follow an identical naming scheme to the files in the torrents subfolder.
### blocklists/
This subfolder holds bluetack-formatted blocklists. Files ending in ".bin" are generated by Transmission as it parses a bluetack file and stores it into a binary format for faster lookups. On startup, Transmission will try to parse any non-".bin" file and generate a new blocklist from it, so you can have multiple blocklists just by copying new bluetack files into this location. See [Blocklists](./Blocklists.md) for more information.
This subfolder holds Bluetack-formatted blocklists. Files ending in ".bin" are generated by Transmission as it parses a Bluetack file and stores it into a binary format for faster lookups. On startup, Transmission will try to parse any non-".bin" file and generate a new blocklist from it, so you can have multiple blocklists just by copying new Bluetack files into this location. See [Blocklists](./Blocklists.md) for more information.
## Legacy Versions of Transmission
Older, [pre-XDG](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) [versions](http://trac.transmissionbt.com/ticket/684) of transmission-gtk and transmission-daemon stored their settings in `$HOME/.transmission`. Newer releases try to automatically migrate these files to `$HOME/.config/transmission/`.
Older, [pre-XDG](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) [versions](http://trac.transmissionbt.com/ticket/684) of transmission-GTK and transmission-daemon stored their settings in `$HOME/.transmission`. Newer releases try to automatically migrate these files to `$HOME/.config/transmission/`.

78
docs/Editing-Configuration-Files.md
View File

@ -1,49 +1,40 @@
It's not always possible to set all configurations from the GUI, especially on the Daemon or the Web Interface. This guide will try to give an overview of how and what you can change. For the location of these files, look at the [Configuration Files](Configuration-Files.md) page.
It is not always possible to set all configurations from the GUI, especially for the daemon or the web interface. This guide will try to give an overview of how and what you can change. For the location of these files, look at the [Configuration Files](Configuration-Files.md) page.
Note: The client _should_ be closed before making changes, otherwise settings will be reverted to it's previous state.
Note: The client _should_ be closed before making changes, otherwise settings will be reverted to their previous state.
Some of Transmission's behavior can also be customized via environment variables.
# GTK / Daemon / CLI
### Overview
GTK, CLI and Daemon (both on a Mac and Linux) use a [JSON](http://www.json.org/) formatted file, mainly because of its human readability.
(Consult the [JSON](http://www.json.org/) for detailed information)
GTK, CLI and daemon (both on a Mac and Linux) use a [JSON](https://www.json.org/) formatted file, mainly because of its human readability.
(Consult the [JSON website](https://www.json.org/) for detailed information)
### Reload Settings
You can make the daemon reload the settings file by sending it the `SIGHUP` signal.
Or, simply run either of the following commands:
Or simply run either of the following commands:
```console
$ killall -HUP transmission-da
$ killall -HUP transmission-daemon
```
Or:
```console
$ pkill -HUP transmission-da
$ pkill -HUP transmission-daemon
```
### Formatting
Here is a sample of the three basic types, respectively Boolean, Number and String:
Here is a sample of the three basic types: respectively Boolean, Number and String:
```json
{
"rpc-enabled": true,
"peer-port" : 51413,
"peer-port": 51413,
"rpc-whitelist": "127.0.0.1,192.168.*.*"
}
```
### Options
#### Bandwidth
* **alt-speed-enabled:** Boolean (default = false, aka 'Turtle Mode')
_Note: Clicking the "Turtle" in the gui when the [scheduler](#Scheduling) is enabled, will only temporarily remove the scheduled limit until the next cycle._
_Note: Clicking the "Turtle" in the GUI when the [scheduler](#Scheduling) is enabled, will only temporarily remove the scheduled limit until the next cycle._
* **alt-speed-up:** Number (KB/s, default = 50)
* **alt-speed-down:** Number (KB/s, default = 50)
* **speed-limit-down:** Number (KB/s, default = 100)
@ -53,12 +44,10 @@ Here is a sample of the three basic types, respectively Boolean, Number and Stri
* **upload-slots-per-torrent:** Number (default = 14)
#### [Blocklists](./Blocklists.md)
* **blocklist-url:** String (default = http://www.example.com/blocklist)
* **blocklist-url:** String (default = https://www.example.com/blocklist)
* **blocklist-enabled:** Boolean (default = false)
#### [Files and Locations](./ConfigFiles.md)
* **download-dir:** String (default = [default locations](Configuration-Files.md#Locations))
* **incomplete-dir:** String (default = [default locations](Configuration-Files.md#Locations)) Directory to keep files in until torrent is complete.
* **incomplete-dir-enabled:** Boolean (default = false) When enabled, new torrents will download the files to **incomplete-dir**. When complete, the files will be moved to **download-dir**.
@ -66,21 +55,20 @@ Here is a sample of the three basic types, respectively Boolean, Number and Stri
* **rename-partial-files:** Boolean (default = true) Postfix partially downloaded files with ".part".
* **start-added-torrents:** Boolean (default = true) Start torrents as soon as they are added.
* **trash-original-torrent-files:** Boolean (default = false) Delete torrents added from the watch directory.
* **umask:** Number (default = 18) Sets transmission's file mode creation mask. See [the umask(2) manpage](http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/umask.2.html) for more information. Users who want their saved torrents to be world-writable may want to set this value to 0. Bear in mind that the json markup language only accepts numbers in base 10, so the standard umask(2) octal notation "022" is written in settings.json as 18.
* **umask:** Number (default = 18) Sets transmission's file mode creation mask. See [the umask(2) manpage](https://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/umask.2.html) for more information. Users who want their saved torrents to be world-writable may want to set this value to 0. Bear in mind that the JSON markup language only accepts numbers in base 10, so the standard umask(2) octal notation "022" is written in settings.json as 18.
* **watch-dir:** String
* **watch-dir-enabled:** Boolean (default = false) Watch a directory for torrent files and add them to transmission.
_Note: When **watch-dir-enabled** is true, only the transmission-daemon, transmission-gtk, and transmission-qt applications will monitor **watch-dir** for new .torrent files and automatically load them._
#### Misc
* **cache-size-mb:** Size (default = 4), in megabytes, to allocate for Transmission's memory cache. The cache is used to help batch disk IO together, so increasing the cache size can be used to reduce the number of disk reads and writes. Default is 2 if configured with --enable-lightweight.
* **dht-enabled:** Boolean (default = true) Enable [Distributed Hash Table (DHT)](http://wiki.theory.org/BitTorrentSpecification#Distributed_Hash_Table).
* **encryption:** Number (0 = Prefer unencrypted connections, 1 = Prefer encrypted connections, 2 = Require encrypted connections; default = 1) [Encryption](http://wiki.vuze.com/w/Message_Stream_Encryption) preference. Encryption may help get around some ISP filtering, but at the cost of slightly higher CPU use.
* **lazy-bitfield-enabled:** Boolean (default = true) May help get around some ISP filtering. [Vuze specification](http://wiki.vuze.com/w/Commandline_options#Network_Options).
* **lpd-enabled:** Boolean (default = false) Enable [Local Peer Discovery (LPD)](http://en.wikipedia.org/wiki/Local_Peer_Discovery).
* **dht-enabled:** Boolean (default = true) Enable [Distributed Hash Table (DHT)](https://wiki.theory.org/BitTorrentSpecification#Distributed_Hash_Table).
* **encryption:** Number (0 = Prefer unencrypted connections, 1 = Prefer encrypted connections, 2 = Require encrypted connections; default = 1) [Encryption](https://wiki.vuze.com/w/Message_Stream_Encryption) preference. Encryption may help get around some ISP filtering, but at the cost of slightly higher CPU use.
* **lazy-bitfield-enabled:** Boolean (default = true) May help get around some ISP filtering. [Vuze specification](https://wiki.vuze.com/w/Commandline_options#Network_Options).
* **lpd-enabled:** Boolean (default = false) Enable [Local Peer Discovery (LPD)](https://en.wikipedia.org/wiki/Local_Peer_Discovery).
* **message-level:** Number (0 = None, 1 = Error, 2 = Info, 3 = Debug, default = 2) Set verbosity of transmission messages.
* **pex-enabled:** Boolean (default = true) Enable [http://en.wikipedia.org/wiki/Peer_exchange Peer Exchange (PEX)].
* **prefetch-enabled:** Boolean (default = true). When enabled, Transmission will hint to the OS which piece data it's about to read from disk in order to satisfy requests from peers. On Linux, this is done by passing `POSIX_FADV_WILLNEED` to [posix_fadvise()](http://www.kernel.org/doc/man-pages/online/pages/man2/posix_fadvise.2.html). On OS X, this is done by passing `F_RDADVISE` to [fcntl()](http://developer.apple.com/library/IOS/#documentation/System/Conceptual/ManPages_iPhoneOS/man2/fcntl.2.html). This defaults to false if configured with --enable-lightweight.
* **pex-enabled:** Boolean (default = true) Enable [https://en.wikipedia.org/wiki/Peer_exchange Peer Exchange (PEX)].
* **prefetch-enabled:** Boolean (default = true). When enabled, Transmission will hint to the OS which piece data it's about to read from disk in order to satisfy requests from peers. On Linux, this is done by passing `POSIX_FADV_WILLNEED` to [posix_fadvise()](https://www.kernel.org/doc/man-pages/online/pages/man2/posix_fadvise.2.html). On OS X, this is done by passing `F_RDADVISE` to [fcntl()](https://developer.apple.com/library/IOS/#documentation/System/Conceptual/ManPages_iPhoneOS/man2/fcntl.2.html). This defaults to false if configured with --enable-lightweight.
* **scrape-paused-torrents-enabled:** Boolean (default = true)
* **script-torrent-added-enabled:** Boolean (default = false) Run a script when a torrent is added to Transmission. Environmental variables are passed in as detailed on the [Scripts](./Scripts.md) page
* **script-torrent-added-filename:** String (default = "") Path to script.
@ -88,28 +76,25 @@ Here is a sample of the three basic types, respectively Boolean, Number and Stri
* **script-torrent-done-filename:** String (default = "") Path to script.
* **script-torrent-done-seeding-enabled:** Boolean (default = false) Run a script when a torrent is done seeding. Environmental variables are passed in as detailed on the [Scripts](./Scripts.md) page
* **script-torrent-done-seeding-filename:** String (default = "") Path to script.
* **utp-enabled:** Boolean (default = true) Enable [Micro Transport Protocol (µTP)](http://en.wikipedia.org/wiki/Micro_Transport_Protocol)
* **utp-enabled:** Boolean (default = true) Enable [Micro Transport Protocol (µTP)](https://en.wikipedia.org/wiki/Micro_Transport_Protocol)
#### Peers
* **bind-address-ipv4:** String (default = "0.0.0.0") Where to listen for peer connections.
* **bind-address-ipv6:** String (default = "::") Where to listen for peer connections.
* **peer-congestion-algorithm:** String. This is documented on http://www.pps.jussieu.fr/~jch/software/bittorrent/tcp-congestion-control.html.
* **peer-congestion-algorithm:** String. This is documented on https://www.pps.jussieu.fr/~jch/software/bittorrent/tcp-congestion-control.html.
* **peer-id-ttl-hours:** Number (default = 6) Recycle the peer id used for public torrents after N hours of use.
* **peer-limit-global:** Number (default = 240)
* **peer-limit-per-torrent:** Number (default = 60)
* **peer-socket-tos:** String (default = "default") Set the [Type-Of-Service (TOS)](http://en.wikipedia.org/wiki/Type_of_Service) parameter for outgoing TCP packets. Possible values are "default", "lowcost", "throughput", "lowdelay" and "reliability". The value "lowcost" is recommended if you're using a smart router, and shouldn't harm in any case.
* **peer-socket-tos:** String (default = "default") Set the [Type-Of-Service (TOS)](https://en.wikipedia.org/wiki/Type_of_Service) parameter for outgoing TCP packets. Possible values are "default", "lowcost", "throughput", "lowdelay" and "reliability". The value "lowcost" is recommended if you're using a smart router, and shouldn't harm in any case.
#### Peer Port
* **peer-port:** Number (default = 51413)
* **peer-port-random-high:** Number (default = 65535)
* **peer-port-random-low:** Number (default = 1024)
* **peer-port-random-on-start:** Boolean (default = false)
* **port-forwarding-enabled:** Boolean (default = true) Enable [UPnP](http://en.wikipedia.org/wiki/Universal_Plug_and_Play) or [NAT-PMP](http://en.wikipedia.org/wiki/NAT_Port_Mapping_Protocol).
* **port-forwarding-enabled:** Boolean (default = true) Enable [UPnP](https://en.wikipedia.org/wiki/Universal_Plug_and_Play) or [NAT-PMP](https://en.wikipedia.org/wiki/NAT_Port_Mapping_Protocol).
#### Queuing
* **download-queue-enabled:** Boolean (default = true) When true, Transmission will only download `download-queue-size` non-stalled torrents at once.
* **download-queue-size:** Number (default = 5) See download-queue-enabled.
* **queue-stalled-enabled:** Boolean (default = true) When true, torrents that have not shared data for `queue-stalled-minutes` are treated as 'stalled' and are not counted against the `download-queue-size` and `seed-queue-size` limits.
@ -118,7 +103,6 @@ Here is a sample of the three basic types, respectively Boolean, Number and Stri
* **seed-queue-size:** Number (default = 10) See seed-queue-enabled.
#### [RPC](rpc-spec.md)
* **rpc-authentication-required:** Boolean (default = false)
* **rpc-bind-address:** String (default = "0.0.0.0") Where to listen for RPC connections
* **rpc-enabled:** Boolean (default = true)
@ -132,7 +116,6 @@ Here is a sample of the three basic types, respectively Boolean, Number and Stri
* **rpc-whitelist-enabled:** Boolean (default = true)
#### Scheduling
* **alt-speed-time-enabled:** Boolean (default = false)
_Note: When enabled, this will toggle the **alt-speed-enabled** setting._
* **alt-speed-time-begin:** Number (default = 540, in minutes from midnight, 9am)
@ -156,30 +139,23 @@ Here is a sample of the three basic types, respectively Boolean, Number and Stri
* **ratio-limit-enabled:** Boolean (default = false)
### Legacy Options
Only keys that differ from above are listed here. These options have been replaced in newer versions of Transmission.
Only keys that differ from above are listed here. These options have been replaced in newer versions of Transmission.
#### 2.31 (and older)
* **open-file-limit:** Number (default = 32)
#### 1.5x (and older)
##### Bandwidth
* **download-limit:** Number (KB/s, default = 100)
* **download-limit-enabled:** Boolean (default = false)
* **upload-limit:** Number (KB/s, default = 100)
* **upload-limit-enabled:** Boolean (default = false)
##### Peer Port
* **peer-port-random-enabled:** Boolean (default = false)
#### 1.4x (and older)
##### Proxy
* **proxy-authentication** String
* **proxy-authentication-required:** Boolean (default = 0)
* **proxy-port:** Number (default = 80)
@ -189,28 +165,22 @@ Only keys that differ from above are listed here. These options have been repla
* **proxy-username:** String
##### Peers
* **max-peers-global:** Number (default = 240)
* **max-peers-per-torrent:** Number (default = 60)
#### 1.3x (and older)
##### [RPC](rpc-spec.md)
* **rpc-access-control-list:** String (Comma-delimited list of IP addresses prefixed with "+" or "-". Wildcards allowed using '\*'. Example: "+127.0.0.\*,-192.168.\*.\*", Default: "+127.0.0.1")
## Mac OS X
### Overview
Mac OS X has a standardized way of saving user preferences files using [XML](http://en.wikipedia.org/wiki/XML) format. These files are called [plist](http://en.wikipedia.org/wiki/Plist) (short for property list) files. Usually there is no need to modify these files directly, since Apple provided a [command-line tool](http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man1/defaults.1.html) to reliably change settings. You do need to restart Transmission before these have effect.
Mac OS X has a standardized way of saving user preferences files using [XML](https://en.wikipedia.org/wiki/XML) format. These files are called [plist](https://en.wikipedia.org/wiki/Plist) (short for property list) files. Usually there is no need to modify these files directly, since Apple provided a [command-line tool](https://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man1/defaults.1.html) to reliably change settings. You do need to restart Transmission before these have effect.
In short:
* To set a key: `defaults write org.m0k.transmission <key> <value>`
* To reset a key: `defaults delete org.m0k.transmission <key>`
### Options
* **PeerSocketTOS:** Number (Default = 0)
* **RPCHostWhitelist:** String, see "rpc-host-whitelist" above.
* **RPCUseHostWhitelist:** Boolean, see "rpc-host-whitelist-enabled" above.

26
docs/Environment-Variables.md
View File

@ -1,27 +1,23 @@
Users can set environmental variables to override Transmission's default behavior and for debugging.
## Transmission-Specific Variables
* If `TRANSMISSION_HOME` is set, Transmission will look there for its settings instead of in the [default location](Configuration-Files.md#Locations).
* If `TRANSMISSION_WEB_HOME` is set, Transmission will look there for the [Web Interface](Web-Interface.md) files, such as the javascript, html, and graphics files.
* If `TR_CURL_VERBOSE` is set, debugging information for libcurl will be enabled. More information about libcurl's debugging mode [is available here](http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTVERBOSE).
* If `TR_DEBUG_FD` is set to an integer, that integer is treated as a [file descriptor](http://en.wikipedia.org/wiki/File_descriptor) and very verbose debugging information is written to it. For example, here is how to turn on debugging and save it to a file named "runlog" when running Transmission from a bash shell:
* If `TRANSMISSION_WEB_HOME` is set, Transmission will look there for the [Web Interface](Web-Interface.md) files, such as the JavaScript, HTML, and graphics files.
* If `TR_CURL_VERBOSE` is set, debugging information for libcurl will be enabled. More information about libcurl's debugging mode [is available here](https://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTVERBOSE).
* If `TR_DEBUG_FD` is set to an integer, that integer is treated as a [file descriptor](https://en.wikipedia.org/wiki/File_descriptor) and very verbose debugging information is written to it. For example, here is how to turn on debugging and save it to a file named "runlog" when running Transmission from a bash shell:
```console
$ export TR_DEBUG_FD=2
$ transmission 2>runlog
```
* If `TR_DHT_VERBOSE` is set, then Transmission will log all of the DHT's activities in excruciating detail to standard error.
* If `TR_DHT_VERBOSE` is set, Transmission will log all of the DHT's activities in excruciating detail to standard error.
## Standard Variables Used By Transmission
* If `TRANSMISSION_WEB_HOME` is _not_ set, non-Mac platforms will look for the [Web Interface](Web-Interface.md) files in `XDG_DATA_HOME` and in `XDG_DATA_DIRS` as described in [the XDG Base Directory Specification](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html#variables). `XDG_DATA_HOME` has a default value of `$HOME/.local/share/`.
## Standard Variables Used by Transmission
* If `TRANSMISSION_WEB_HOME` is _not_ set, non-Mac platforms will look for the [Web Interface](Web-Interface.md) files in `XDG_DATA_HOME` and in `XDG_DATA_DIRS` as described in [the XDG Base Directory Specification](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html#variables). `XDG_DATA_HOME` has a default value of `$HOME/.local/share/`.
* If `TRANSMISSION_HOME` is _not_ set, Unix-based versions of Transmission will look for their settings in `$XDG_CONFIG_HOME/transmission/`. `XDG_CONFIG_HOME` has a default value of `$HOME/.config/`.
* If `HOME` is set, it's used in three ways:
1. by the `XDG` variables, as described above
2. If `TRANSMISSION_HOME` is _not_ set, Mac-based versions of Transmission will look for their settings in `$HOME/Library/Application Support/Transmission`
* If `HOME` is set, it is used in three ways:
1. By the `XDG` variables, as described above.
2. If `TRANSMISSION_HOME` is _not_ set, Mac-based versions of Transmission will look for their settings in `$HOME/Library/Application Support/Transmission`.
3. `$HOME/Downloads` is the default download directory.
## Standard Variables Used By Other Tools
* Transmission uses the [libcurl](http://curl.haxx.se/libcurl/) library for http- and https-based tracker announces and scrapes. Transmission doesn't support proxies, but libcurl itself honors [a handful of environment variables](http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTPROXY) to customize _its_ proxy behavior.
## Standard Variables Used by Other Tools
* Transmission uses the [libcurl](https://curl.haxx.se/libcurl/) library for HTTP- and HTTPS-based tracker announces and scrapes. Transmission does not support proxies, but libcurl itself honors [a handful of environment variables](https://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTPROXY) to customize _its_ proxy behavior.

12
docs/Peer-ID-and-User-Agent.md
View File

@ -1,17 +1,15 @@
## Peer-Id
From version 0.80 onward, Transmission's peer-id is formatted Azureus style with one digit for the major version, two digits for the minor version, and one character to denote a stable release (`0`), nightly build (`Z`), or prerelease beta (`X`). For example:
## Peer-ID
From version 0.80 onward, Transmission's peer-id is formatted in Azureus' style with one digit for the major version, two digits for the minor version and one character to denote a stable release (`0`), nightly build (`Z`) or prerelease beta (`X`). For example:
* `-TR1330-` &mdash; Official 1.33 release
* `-TR133Z-` &mdash; Nightly build between 1.33 and 1.34
* `-TR133X-` &mdash; Beta release of 1.34
Rationale: This differentiates between official and unofficial releases in a way easy for trackers to detect with simple string comparison. An official release (`-TR1330-`) is lexicographically smaller than its post-release unsupported versions (`-TR133Z-` and `-TR133X-`), which in turn are lexicographically smaller than the next official release (`-TR1340-`).
Rationale: This differentiates between official and unofficial releases in a way which is easy for trackers to detect with simple string comparison. An official release (`-TR1330-`) is lexicographically smaller than its post-release unsupported versions (`-TR133Z-` and `-TR133X-`), which in turn are lexicographically smaller than the next official release (`-TR1340-`).
Before 0.80, versions of Transmission used two digits for the major version and two for the minor. For example, `-TR0072-` was Transmission 0.72.
Before 0.80, versions of Transmission used two digits for the major version and two for the minor version. For example, `-TR0072-` was Transmission 0.72.
## User-Agent
Its User-Agent header follows a similar format, plus the VCS revision in parenthesis:
Its User-Agent header follows a similar format, plus the VCS revision in parentheses:
* Transmission/1.30X (6416) &mdash; Beta release leading up to version 1.30
* Transmission/1.32 (6455) &mdash; Official 1.32 release
* Transmission/1.32+ (6499) &mdash; Nightly build between 1.32 and 1.33

10
docs/Peer-Status-Text.md
View File

@ -1,13 +1,13 @@
The cryptic 'peer status' is shown in transmission-remote's `--peers` argument and in the Peers tab of the GTK+ Client's Details dialog. It's explained in a tooltip if you have GTK+ 2.12 or higher, and here if you don't:
The cryptic "peer status" is shown in transmission-remote's `--peers` argument and in the peers tab of the GTK+ client's details dialog. It is explained in a tooltip if you have GTK+ 2.12 or higher, and here if you do not:
<table>
<tr><td><tt>O</tt></td><td>Optimistic unchoke</td></tr>
<tr><td><tt>D</tt></td><td>Downloading from this peer</td></tr>
<tr><td><tt>d</tt></td><td>We would download from this peer if they'd let us</td></tr>
<tr><td><tt>d</tt></td><td>We would download from this peer if they would let us</td></tr>
<tr><td><tt>U</tt></td><td>Uploading to peer</td></tr>
<tr><td><tt>u</tt></td><td>We would upload to this peer if they'd ask</td></tr>
<tr><td><tt>K</tt></td><td>Peer has unchoked us, but we're not interested</td></tr>
<tr><td><tt>?</tt></td><td>We unchoked this peer, but they're not interested</td></tr>
<tr><td><tt>u</tt></td><td>We would upload to this peer if they would ask</td></tr>
<tr><td><tt>K</tt></td><td>Peer has unchoked us, but we are not interested</td></tr>
<tr><td><tt>?</tt></td><td>We unchoked this peer, but they are not interested</td></tr>
<tr><td><tt>E</tt></td><td>Encrypted Connection</td></tr>
<tr><td><tt>H</tt></td><td>Peer was discovered through Distributed Hash Table (DHT)</td></tr>
<tr><td><tt>X</tt></td><td>Peer was discovered through Peer Exchange (PEX)</td></tr>

175
docs/Port-Forwarding-Guide.md
View File

@ -1,94 +1,81 @@
# Port Forwarding Guide
[BitTorrent](http://en.wikipedia.org/wiki/BitTorrent_protocol) is a peer-to-peer protocol which allows users to send and receive bits of files without the need of it being hosted on a centralized server.
For this to be possible, it is required to be accessible from the internet. However, this isn't always as straight forward as it may seem. Because of the nature of the internet and security reasons, routers create a local network that makes your computer invisible to the internet. This technology is called [NAT](http://en.wikipedia.org/wiki/Network_address_translation).
## Open your local Firewall
To allow other peers to communicate with Transmission, you have to open your local firewall.
However, if you're behind a NAT (a router or DSL 'modem'), it is safe disable the firewall.
### On Mac OS X
Upon opening Transmission for the first time, a Mac OS X dialogue box should appear asking if you will allow Transmission to receive incoming connections. Click Accept.
If this doesn't happen, you can add Transmission to Leopard's firewall manually:
1. Open System Prefs >> Security >> Firewall. Make sure "Set access for specific services and applications" is selected.
1. Click the "+" button and select Transmission from you Applications folder.
1. Make sure the pull down menu is set to "Allow incoming connections".
### On Mac OS X 10.4 and Older
1. Open Transmission, go to Preferences >> Network and and note down the number for the port. Then quit Transmission.
1. Open System Prefs >> Sharing >> Firewall. Click "New." In the "Port Name" pop-up menu, select Other, and fill in the settings as follows:
* TCP Port Number(s): the port you chose in step 1 - (default is 51413).
* Description: Transmission
3. Click OK.
### On Unix
* For instructions on how to use it, open a Terminal open the man page of your Firewall. (e.g. 'man ufw, man firewalld')
* You need to ensure that Transmission's port (displayed in Preferences) is opened in the firewall.
### Windows
1. Navigate to the Control Panel.
1. Click "Windows Defender Firewall"
1. Choose "Advanced Settings" on the left panel. This will prompt for administrator access.
1. On the left panel click "Inbound Rules".
1. Once you have the Inbound Rules list showing you want to click on "New Rule" under the "Actions" panel on the right.
1. This will bring up a new window titled "New Inbound Rule Wizard". Whilst there are a couple ways to go about things from here, here we will only cover opening just the port alone for TCP/UDP. With that being said, check the button next to "Port" and click "Next".
1. In "Protocols and Ports" select either TCP (for BT protocol) or UDP (for μTP) for which one you want to open (to open both you must now choose one and go back later and created another rule to select the other). Underneath that you choose what port to open. 51413 is the default but you can set it to any port you like as long as it correlates with the port you have set in Transmission. Once you have your port click on "Next".
1. Here in "Actions" you choose to either "Allow the connection", "Allow the connection if it is secure" (only allow packets using [IPsec](https://en.wikipedia.org/wiki/IPsec)), choose based on personal preference here then click "Next".
1. Choose the profile accordingly to the type of network you are connected to and hit "Next".
1. The last thing is to give the rule a name. It can be whatever just make sure it's something you can read and remember exactly what it's for.
* Note this only opens the port in Windows and has no effect on the router
## Open ports & forwarding
To allow other peers to connect to you, you'll need to forward a port from the router to your computer.
### NAT-PMP / UPnP
By default Transmission will try to forward this port for you, using [UPnP]([http://en.wikipedia.org/wiki/UPnP) or [NAT-PMP](http://en.wikipedia.org/wiki/NAT-PMP).
Most routers manufactured since 2001 have either the UPnP or NAT-PMP feature.
* Open Transmission.
* Go to Preferences >> Network >> Ports, and check 'Forward port from router'.
* If Transmission reports that the 'Port is open' then you have successfully port forwarded!
### Forward manually through a Router
1. Find out what your IP address is.
* *On Mac OS X*- Go to System Preferences >> Network, double-clicking on your connection (for instance, Built-in Ethernet), and clicking the TCP/IP tab. The address is probably something like 192.168.1.100, or 10.0.1.2. The IP of your router is here too.
* *On Unix*- In Ubuntu, right click the Network Manager applet in the menu bar, and select 'Connection Information'. The address is probably something like 192.168.1.2, or 10.0.1.2.
* If you don't have Network Manager, open a Terminal and type 'ifconfig'. It will list information for each of your network devices. Find the one you are using, and use the number after 'inet addr:'.
* Using the command "ip a" will achieve the same results in a different format.
2. Open Transmission, go to preferences, and enter a number for the port. It is recommended you pick a random number between 49152 and 65535. The default is 51413. Then quit Transmission.
3. Go into your router configuration screen. Normally this is done via your web browser using the address 192.168.0.1 etc.
4. Find the port forwarding (sometimes called port mapping) screen. While the page will be different for each router generally you will enter something similar to the following:
5. For 'Application' type 'Trans'.
6. For 'Start Port' and 'End port' type in the port you chose in Step 2. (e.g. 51413).
7. For Protocol, choose Both.
8. For IP address, type in your IP address you found in Step 1. (e.g. 192.168.1.2).
9. Check Enable.
10. Click save settings.
For more comprehensive instructions specific to your router, visit [portforward.com](http://www.portforward.com/english/routers/port_forwarding/routerindex.htm) and choose your router from the list.
* Please note that port mapping changes might not take effect until the router is rebooted
#### Verify
1. Go to [CanYouSeeMe.org](http://www.canyouseeme.org/)
1. Enter the Port Transmission uses
1. If Transmission reports that the 'Port is open' then you have successfully forwarded the port!
#### Common Problems
Go to the [Why is my port closed?](Why-is-my-port-closed.md) page.
# Port forwarding guide
[BitTorrent](https://en.wikipedia.org/wiki/BitTorrent_protocol) is a peer-to-peer protocol which allows users to send and receive bits of files without the need of it being hosted on a centralized server.
For this to be possible, it is required to be accessible from the Internet. However, this is not always as straightforward as it may seem. Because of the nature of the Internet and security reasons, routers create a local network that makes your computer invisible to the Internet. This technology is called [NAT](https://en.wikipedia.org/wiki/Network_address_translation).
## Open your local firewall
To allow other peers to communicate with your Transmission instance, you have to forward a port through your firewall.
### On Mac OS X
Upon opening Transmission for the first time, a Mac OS X dialog box should appear asking if you will allow Transmission to receive incoming connections. Click Accept.
If this does not happen, you can add Transmission to Leopard's firewall manually:
1. Open System Prefs >> Security >> Firewall. Make sure "Set access for specific services and applications" is selected.
1. Click the "+" button and select Transmission from you applications folder.
1. Make sure the pull down menu is set to "Allow incoming connections".
### On Mac OS X 10.4 and older
1. Open Transmission, go to Preferences >> Network and and note down the number for the port. Then quit Transmission.
1. Open System Prefs >> Sharing >> Firewall. Click "New." In the "Port Name" pop-up menu, select Other, and fill in the settings as follows:
* TCP Port Number(s): the port you chose in step 1 - (default is 51413).
* Description: Transmission
3. Click OK.
### On Unix
* For instructions on how to use it, open a Terminal and open the man page of your firewall. (e.g. 'man ufw, man firewalld')
* You need to ensure that Transmission's port (displayed in preferences) is forwarded in the firewall.
### Windows
1. Navigate to the control panel.
1. Click "Windows Defender Firewall"
1. Choose "Advanced Settings" on the left panel. This will prompt for administrator access.
1. On the left panel click "Inbound Rules".
1. Once you have the Inbound Rules list showing you want to click on "New Rule" under the "Actions" panel on the right.
1. This will bring up a new window titled "New Inbound Rule Wizard". Whilst there are a couple ways to go about things from here, here we will only cover opening just the port alone for TCP/UDP. With that being said, check the button next to "Port" and click "Next".
1. In "Protocols and Ports" select either TCP (for BT protocol) or UDP (for μTP) for which one you want to open (to open both you must now choose one and go back later and created another rule to select the other). Underneath that you choose what port to open. 51413 is the default but you can set it to any port you like as long as it correlates with the port you have set in Transmission. Once you have your port click on "Next".
1. Here in "Actions" you choose to either "Allow the connection", "Allow the connection if it is secure" (only allow packets using [IPsec](https://en.wikipedia.org/wiki/IPsec)), choose based on personal preference here then click "Next".
1. Choose the profile according to the type of network you are connected to and hit "Next".
1. The last thing is to give the rule a name. It can be whatever just make sure it's something you can read and remember exactly what it's for.
* Note this only opens the port in Windows and has no effect on the router.
## Open ports & forwarding
To allow other peers to connect to you, you will need to forward a port from the router to your computer.
### NAT-PMP / UPnP
By default Transmission will try to forward this port for you, using [UPnP]([https://en.wikipedia.org/wiki/UPnP) or [NAT-PMP](https://en.wikipedia.org/wiki/NAT-PMP).
Most routers manufactured since 2001 have either the UPnP or NAT-PMP feature.
* Open Transmission.
* Go to Preferences >> Network >> Ports, and check 'Forward port from router'.
* If Transmission reports that the 'Port is open' then you have successfully port forwarded!
### Forward manually through a router
1. Find out what your IP address is.
* *On Mac OS X*- Go to System Preferences >> Network, double-clicking on your connection (for instance, Built-in Ethernet), and clicking the TCP/IP tab. The address is probably something like 192.168.1.100, or 10.0.1.2. The IP of your router is here too.
* *On Unix*- In Ubuntu, right click the Network Manager applet in the menu bar, and select 'Connection Information'. The address is probably something like 192.168.1.2, or 10.0.1.2.
* If you don't have Network Manager, open a Terminal and type 'ifconfig'. It will list information for each of your network devices. Find the one you are using, and use the number after 'inet addr:'.
* Using the command "ip a" will achieve the same results in a different format.
2. Open Transmission, go to preferences, and enter a number for the port. It is recommended you pick a random number between 49152 and 65535. The default is 51413. Then quit Transmission.
3. Go into your router configuration screen. Normally this is done via your web browser using the address 192.168.0.1 etc.
4. Find the port forwarding (sometimes called port mapping) screen. While the page will be different for each router generally you will enter something similar to the following:
5. For 'Application' type 'Trans'.
6. For 'Start Port' and 'End port' type in the port you chose in Step 2. (e.g. 51413).
7. For Protocol, choose Both.
8. For IP address, type in your IP address you found in Step 1. (e.g. 192.168.1.2).
9. Check Enable.
10. Click save settings.
For more comprehensive instructions specific to your router, visit [portforward.com](https://www.portforward.com/english/routers/port_forwarding/routerindex.htm) and choose your router from the list.
* Please note that port mapping changes might not take effect until the router is rebooted
#### Verify
1. Go to [CanYouSeeMe.org](https://www.canyouseeme.org/).
1. Enter the port Transmission uses.
1. If Transmission reports that the 'Port is open' then you have successfully forwarded the port.
#### Common problems
Go to the [Why is my port closed?](Why-is-my-port-closed.md) page.

2
docs/Previous-Releases.md
View File

@ -21,4 +21,4 @@ If you have a legacy operating system version, this table shows the best Transmi
Latest version: [Transmission 0.6.1](https://github.com/transmission/transmission-releases/raw/master/Transmission-0.6.1.dmg)
SHA256 hash: [`1bc2cbdfb3df814e8e4b8e2f74b3063eca55a5b0fb08f6dc6e567dfb449398b8`](https://www.virustotal.com/en/file/1bc2cbdfb3df814e8e4b8e2f74b3063eca55a5b0fb08f6dc6e567dfb449398b8/analysis/)
A complete collection of earlier releases can be found [here](https://github.com/transmission/transmission-releases).
A complete collection of earlier releases can be found [here](https://github.com/transmission/transmission-releases).

44
docs/README.md
View File

@ -1,50 +1,44 @@
# 1. General Help #
# 1. General help #
New to Transmission?
* Try the Help in Transmission's "Help" menu.
* simplehelp.net has an introduction for [Transmission on Macs](http://www.simplehelp.net/2008/07/17/how-to-use-transmission-as-your-bittorrent-client-os-x/).
* Jun Azua has an introduction for [Transmission GUI on Linux](http://www.junauza.com/2009/01/how-to-use-bittorrent-in-linux.html).
* Try the help in Transmission's "Help" menu.
* simplehelp.net has an introduction for [Transmission on Macs](https://www.simplehelp.net/2008/07/17/how-to-use-transmission-as-your-bittorrent-client-os-x/).
* Jun Azua has an introduction for [Transmission GUI on Linux](https://www.junauza.com/2009/01/how-to-use-bittorrent-in-linux.html).
* Running Transmission [without a GUI](HeadlessUsage)
* Using Transmission [from a web browser](Web Interface)
Want to learn more?
* Visit our [forums](https://forum.transmissionbt.com)
* Visit our [IRC](https://en.wikipedia.org/wiki/IRC) channel: [#transmission on Libera](http://irc.libera.chat/transmission)
* Follow us on [twitter](https://twitter.com/transmissionbt)
* Visit our [IRC](https://en.wikipedia.org/wiki/IRC) channel: [#transmission on Libera.Chat](https://irc.libera.chat/transmission)
* Follow us on [Twitter](https://twitter.com/transmissionbt)
Want to contribute?
Much of this documentation is out-of-date or could be improved. Pull requests are greatly appreciated!
# 2. More Documentation #
* [Configuration Files](./Configuration-Files.md)
* [Editing Configuration Files](./Editing-Configuration-Files.md)
* [Environment Variables](Environment-Variables.md)
* [Extending Transmission using Scripts](./Scripts.md)
# 2. More documentation #
* [Configuration files](./Configuration-Files.md)
* [Editing configuration files](./Editing-Configuration-Files.md)
* [Environment variables](Environment-Variables.md)
* [Extending Transmission using scripts](./Scripts.md)
* [Blocklists](./Blocklists.md)
* [How to build Transmission](Building-Transmission.md)
* [RPC Protocol Specification](rpc-spec.md)
* [RPC protocol specification](rpc-spec.md)
* [Transmisson's Peer ID and User-Agent headers](Peer-ID-and-User-Agent.md)
* [Peer Status Text explained](Peer-Status-Text.md)
* [Peer status text explained](Peer-Status-Text.md)
# 3. Report a problem / request a feature #
* [Check](https://github.com/transmission/transmission/issues) whether the problem has already been reported.
* If you don't see a ticket matching your problem or feature, read [this post](https://forum.transmissionbt.com/viewtopic.php?f=1&t=3274) about what to write, then [add a new ticket](https://github.com/transmission/transmission/issues/new).
* If you _do_ see an existing ticket, please add a comment there. The more users interested in a ticket, the higher priority it's given.
# 4. For Contributors #
* If you do not see a ticket matching your problem or feature, read [this post](https://forum.transmissionbt.com/viewtopic.php?f=1&t=3274) about what to write, then [add a new ticket](https://github.com/transmission/transmission/issues/new).
* If you _do_ see an existing ticket, please add a comment there. The more users are interested in a ticket, the higher its priority.
# 4. For contributors #
Transmission is a volunteer project and welcomes help.
Please contact us if you are interested in supporting Transmission in any of the following ways:
* Code contribution
* Testing
* [Language Translations](Translating)
* [Language translations](Translating)
* Bug and request management
* Documentation and Wiki Editing
* Documentation and Wiki editing
* [Donations](https://transmissionbt.com/donate/)
* If you want to alert us to a security vulnerability, please email security@transmissionbt.com. Please note that general support questions belong on the forum, and will be ignored if sent to this email.
* If you want to alert us of a security vulnerability, please email security@transmissionbt.com. Please note that general support questions belong on the forum, and will be ignored if sent to this email address.

24
docs/Release-Notes.md
View File

@ -1,4 +1,4 @@
# Release Notes #
# Release Notes #
### Transmission 2.92 (2016/03/06) ###
[http://trac.transmissionbt.com/query?milestone#2.92&group#component&order#severity All tickets closed by this release]
#### Mac Client ####
@ -53,7 +53,7 @@
#### Mac Client ####
* UI fixes for OS X 10.9+
* Trim potential URIs from clipboard
* Allow downloading files from http servers (not https) on OS X 10.11+
* Allow downloading files from HTTP servers (not HTTPS) on OS X 10.11+
* Change Sparkle Update URL to use HTTPS instead of HTTP (addresses Sparkle vulnerability)
* Fix global options popover layout
* Fix building with Xcode 7+
@ -176,7 +176,7 @@
#### Daemon ####
* Change the systemd script to start Transmission after the network's initialized
#### Web Client ####
* Slightly better compression of png files
* Slightly better compression of PNG files
### Transmission 2.80 (2013/06/25) ###
[http://trac.transmissionbt.com/query?milestone#2.80&group#component&order#severity All tickets closed by this release]
@ -251,7 +251,7 @@
#### Qt Client ####
* Add magnet link support to transmission-qt.desktop
* Fix notification area bug that inhibited logouts & desktop hibernation
* Use the "video" icon when the torrent is an mkv or mp4 file
* Use the "video" icon when the torrent is an MKV or mp4 file
* Toggling the "Append '.part' to incomplete files' names" had no effect
* Fix display of the torrent name in the Torrent Options dialog
* Fix cursor point bug in the filterbar's entry field
@ -335,7 +335,7 @@
* Control speed limit from the icon tray
* Improved behavior when clicking on torrents in the torrent list
* Fix bug where torrent files were not deleted
* Fix bug with unicode characters in the default location
* Fix bug with Unicode characters in the default location
#### Web Client ####
* The file inspector tab displays files nested under directories
* Improved scrolling on iPad
@ -768,7 +768,7 @@
* Fix filename errors for torrents whose files are encoded in ISO-8859-1
* Fix rare crash on shutdown
* Fix the RPC server's redirect URL to allow HTTPS proxies like stunnel
* Replace less-portable calls with posix nanosleep()
* Replace less-portable calls with POSIX nanosleep()
#### Mac ####
* Use F_NOCACHE to keep "inactive memory" in check
#### GTK+ ####
@ -1054,8 +1054,8 @@ This is a huge listen-to-the-users release -- it uses 103 ideas from users, incl
* Fix crash on exit when a torrent's Properties dialog is open
* Fix tracker address display error in the torrent Properties dialog
* Fix tray menu's main window status when Transmission is started minimized
* Fix broken SIGINT (ctrl-c) handling
* Fix 1.61 build failure on systems with new versions of glib but older versions of gtk
* Fix broken SIGINT (Ctrl-C) handling
* Fix 1.61 build failure on systems with new versions of glib but older versions of GTK
#### Qt ####
* Fix crash when removing expired torrents from the display
* Fix client from closing, rather than closing to the system tray, when clicking X
@ -1119,7 +1119,7 @@ This is a huge listen-to-the-users release -- it uses 103 ideas from users, incl
* Fix bug where user-configured peer limits could be exceeded
* Use less memory in some high-peer situations
* Better estimation of time left to download
* Support supportcrypto and requirecrypto flags in http tracker announces
* Support supportcrypto and requirecrypto flags in HTTP tracker announces
* Update to newer snapshots of libnatpmp and miniupnpc
* Make DHT a compile-time option
#### GTK+ ####
@ -1273,7 +1273,7 @@ This is a huge listen-to-the-users release -- it uses 103 ideas from users, incl
* Use the new blocklist URL when updating the blocklist
#### Web Client ####
* On the server, better filtering of bad URLs
* On the server, faster json serialization
* On the server, faster JSON serialization
* Fix minor web client 301 redirect error
* Better Internet Explorer support
@ -1309,7 +1309,7 @@ This is a huge listen-to-the-users release -- it uses 103 ideas from users, incl
#### Daemon ####
* Lots of new options added to transmission-remote
* Fix 1.42 whitelist bug
* Make i18n support optional for cli and daemon clients
* Make i18n support optional for CLI and daemon clients
#### CLI ####
* Support session.json settings, just as the Daemon and GTK+ clients do
#### Web Client ####
@ -1491,7 +1491,7 @@ This is a huge listen-to-the-users release -- it uses 103 ideas from users, incl
### Transmission 1.20 (2008/05/09) ###
[http://trac.transmissionbt.com/query?milestone#1.20&group#component&order#severity All tickets closed by this release]
#### All Platforms ####
* Support https tracker connections
* Support HTTPS tracker connections
* IP blocking using the Bluetack Level1 blocklist
* Better support of multitracker torrents
* Faster UPnP port mapping on startup

30
docs/Scripts.md
View File

@ -1,13 +1,10 @@
# Transmission Scripts
# Transmission scripts
## Introduction
Thanks to the powerful [RPC](./rpc-spec.md), `transmission-remote` can talk to any client that has the RPC enabled. This means that a script written using `transmission-remote` or [RPC](./rpc-spec.md) can, without rewrite, communicate with all the Transmission clients: Mac, Linux, Windows, and headless.
Mac OS users may wonder whether there will be Applescript scripts, the answer is ''no''. Although Applescript is a nice technology, it's a pain to implement. However, Mac OS X is a Unix after all, so any script you find here will also work on the Mac. Even from within Applescript, you can run these scripts by typing: `do shell script "path/to/script"`.
Mac OS users may wonder whether there will be AppleScript scripts, the answer is ''no''. Although AppleScript is a nice technology, it's a pain to implement. However, Mac OS X is a Unix after all, so any script you find here will also work on the Mac. Even from within AppleScript, you can run these scripts by typing: `do shell script "path/to/script"`.
## How-To
If you are interested at writing scripts for Transmission, have a look at the following pages:
* [wiki:man Transmission man pages]
* [wiki:ConfigFiles Configuration Files]
@ -19,14 +16,11 @@ For those who need more information how to use the scripts, have a look at the f
* [https://help.ubuntu.com/community/CronHowto Cron How-To]: Run scripts at a regular interval
## Scripts
### Start/Stop
* [wiki:Scripts/initd init.d script] (Debian, Ubuntu and BSD derivatives)
* [wiki:Scripts/runscript runscript] (Gentoo and other `runscript`-compatible systems)
### On Torrent Completion
### On torrent completion
Transmission can be set to invoke a script when downloads complete. The environment variables supported are:
* `TR_APP_VERSION` - Transmission's short version string, e.g. `4.0.0`
@ -41,8 +35,7 @@ Transmission can be set to invoke a script when downloads complete. The environm
[https://trac.transmissionbt.com/browser/trunk/extras/send-email-when-torrent-done.sh Here is an example script] that sends an email when a torrent finishes.
### Obsoleted
### Obsolete
Functionality of these scripts has been implemented in libtransmission and is thus available in all clients.
* [wiki:Scripts/EmailNotifier Email Notification Script]
@ -51,19 +44,14 @@ Functionality of these scripts has been implemented in libtransmission and is th
* [wiki:Scripts/Scheduler Bandwidth Scheduler]
## contrib/scripts
Tomas Carnecky (aka wereHamster) is maintaining a set of scripts in his [https://github.com/wereHamster/transmission/tree/master/contrib/scripts/ GitHub repository].
Tomas Carnecky (aka wereHamster) is maintaining a set of scripts in his [http://github.com/wereHamster/transmission/tree/master/contrib/scripts/ GitHub repository].
Falk Husemann (aka hxgn) is maintaining scripts in his [https://falkhusemann.de/category/tcp_ip/transmission-tcp_ip/ blog].
Falk Husemann (aka hxgn) is maintaining scripts in his [http://falkhusemann.de/blog/category/tcp_ip/transmission-tcp_ip/ blog].
oguz wrote [http://oguzarduc.blogspot.com/2012/05/transmission-quit-script-in-php.html on his blog] a PHP script to stop Transmission after it finishes downloading and seeding.
Oguz wrote [https://oguzarduc.blogspot.com/2012/05/transmission-quit-script-in-php.html on his blog] a PHP script to stop Transmission after it finishes downloading and seeding.
Scripts which have not yet been ported and may not work with the latest version:
* http://pastie.org/338556: Python - Fetch new torrents from tvrss
* http://pastie.org/338555: PHP - Stop finished torrents
* http://pastie.org/443058: Perl - Network traffic graph, based on rrdtool (example: http://skitch.com/werehamster/bmjg8/bittorrent-traffic)
* http://transmission.pastebin.com/QzVxQDtM: Bash - (cron)script to keep a maximum number of torrents running; starting and pausing torrents as necessary
* https://pastebin.com/QzVxQDtM: Bash - (cron)script to keep a maximum number of torrents running; starting and pausing torrents as necessary
* https://github.com/jaboto/Transmission-script - (cron)script set network limits according to the number of clients in the network
## Security on systemd
## Security with systemd
`transmission-daemon`'s packaging has many permissions disabled as a standard safety measure. If your script needs more permissions than are provided by the default, users have [reported](https://github.com/transmission/transmission/issues/1951) that it can be resolved by changing to `NoNewPrivileges=false` in `/lib/systemd/system/transmission-daemon.service`.

8
docs/Translating.md
View File

@ -4,12 +4,10 @@ As with any other project, we expect you to be familiar with particular Transmis
General rule is that new localizations are only included in next release if they are at least 95% complete. Transifex (see below) offers a review functionality, so if you feel like it and are not afraid of responsibility — don't hesitate to ask and we could then have a different deal based on reviewed percentage instead (nothing is set in stone as of now).
## Qt and GTK+ Clients
## Qt and GTK+ clients
Translations for Qt and GTK+ clients are managed on Transifex. To help localize, or add your new localization, you'll need to [register on Transifex and join the translation team](https://docs.transifex.com/getting-started/translators) for [Transmission project](https://www.transifex.com/transmissionbt/transmissionbt).
_GTK+ client translations were previously managed on [Launchpad](https://translations.launchpad.net/transmission/trunk/+pots/transmission), but this is no longer the case. No phrases will be updated there, and none of your translations made there will be integrated back into Transmission._
## Mac Client
Parts of Mac client translations have been recently uploaded to Transifex as well. We are still in the process of making all of the translations accessible there, including plural forms support and phrases currently only present in .xib files. It will all be there prior to next major release, so stay tuned. You could start localizing now (follow the same steps as above), but be prepared for some inconveniences along the way.
## Mac client
Parts of Mac client translations have been recently uploaded to Transifex as well. We are still in the process of making all of the translations accessible there, including plural forms support and phrases currently only present in .xib files. It will all be there prior to next major release, so stay tuned. You could start localizing now (follow the same steps as above), but be prepared for some inconveniences along the way.

28
docs/Transmission-Architecture.md
View File

@ -1,27 +1,27 @@
Transmission is fundamentally a Bit Torrent client and communicates with other Bit Torrent peers.
In addition to this Transmission supports network-based remote control, whereby an authorised user may control the Transmission core from another machine via the [Transmission JSON RPC protocol](rpc-spec.md).
To make remote control easier from an arbitrary machine, Transmission Core can also serve a javascript web application to any browser and which in turn makes JSON RPC calls back to the Transmission core.
Transmission is fundamentally a BitTorrent client and communicates with other BitTorrent peers.
In addition to this Transmission supports network-based remote control, whereby an authorised user may control the Transmission core from the same or another machine via the [Transmission JSON RPC protocol](rpc-spec.md).
To make remote control easier from an arbitrary machine, Transmission core can also serve a JavaScript web application to any browser and which in turn makes JSON RPC calls back to the Transmission core.
The Core components and methods of control are shown below:
The core components and methods of control are shown below:
![Architecture](https://transmission.github.io/wiki-images/Transmission_Architecture.gif)
From the above diagram it can be seen that a Transmission Core may be controlled by the following:
From the above diagram it can be seen that a Transmission core may be controlled by the following:
* _Local_ directly linked GUI (OS X, GTK+)
* _Local_ or _Remote_ Qt GUI
* _Local_ or _Remote_ Command Line Utility
* _Local_ or _Remote_ Transmission Web Application running in a web browser
* _Local_ or _remote_ Qt GUI
* _Local_ or _remote_ command line utility
* _Local_ or _remote_ Transmission web application running in a web browser
The multiple methods of controlling Transmission and the various native GUIs available result in several different Transmission products as shown in the figure below:
![Products](https://transmission.github.io/wiki-images/Transmission_Products.gif)
The products are:
* Transmission Desktop - OS X
* Transmission Desktop - Windows, Linux/Qt
* Transmission Desktop - Linux/GTK+
* Transmission Daemon (headless)
* Transmission Command Line
* Transmission desktop - OS X
* Transmission desktop - Windows, Linux/Qt
* Transmission desktop - Linux/GTK+
* Transmission daemon (headless)
* Transmission command line
The Transmission packages available on various distributions may include one or more of these components.
Note. Although the diagram shows "Transmission Desktop Qt" as being Qt GUI + Transmission Core, the Qt component may be packaged on its own as a purely remote tool.
Note. Although the diagram shows "Transmission Desktop Qt" as being a Qt GUI with Transmission core, the Qt component may be packaged on its own as a purely remote tool.

4
docs/Transmission-Resume-Files.md
View File

@ -3,7 +3,6 @@ Transmission keeps working information on each torrent in a "resume" file. This
Filename: `<torrent file name>.<hash?>.resume`
The file contains the following **per-torrent** properties:
<table>
<tr><th>Property</th><th>Description</th></tr>
<tr><td><tt>activity-date</tt></td><td>Date we last uploaded/downloaded a piece of data</td></tr>
@ -39,7 +38,6 @@ The file contains the following **per-torrent** properties:
</table>
## Constants
<table>
<tr><td>Maximum number of remembered peers</td><td><tt>MAX_REMEMBERED_PEERS</tt></td><td>200</td></tr>
</table>
</table>

10
docs/Transmission-is-Downloading-Files-I-Asked-It-To-Not-Download.md
View File

@ -1,11 +1,9 @@
## Summary ##
BitTorrent content is grouped into pieces that are typically somewhere between 64 KiB and 1 MiB in size. The .torrent file comes with a checksum for each piece, and every byte in that piece needs to be downloaded before the checksum can be compared for correctness.
BitTorrent content is grouped into pieces that are typically somewhere between 64 KiB and 1 MiB in size. The .torrent file comes with a checksum for each piece, and every byte in that piece needs to be downloaded before the checksum can be compared for correctness.
So the problem arises when a piece overlaps two (or more) files, one of which you've flagged for download and the other you've flagged to ''not'' download. In order to run verify the checksum for the file you want, Transmission has to download the fragment of the other file where the piece overlaps.
So the problem arises when a piece overlaps two (or more) files, one of which you've flagged for download and the other you've flagged to ''not'' download. In order to run verify the checksum for the file you want, Transmission has to download the fragment of the other file where the piece overlaps.
This is what causes chunks of unwanted files to show up sometimes. Transmission only downloads the chunks needed to complete the piece and run the checksum tests.
This is what causes chunks of unwanted files to show up sometimes. Transmission only downloads the chunks needed to complete the piece and run the checksum tests.
## Future ##
There is a [http://trac.transmissionbt.com/ticket/532 trac ticket] for this to collect all the unwanted fragments into a single file to avoid clutter.
There is a [https://trac.transmissionbt.com/ticket/532 trac ticket] for this to collect all the unwanted fragments into a single file to avoid clutter.

11
docs/Web-Interface.md
View File

@ -1,10 +1,9 @@
A Web Interface is built into all Transmission flavours, enabling them to be controlled remotely.
A web interface is built into all Transmission flavors, enabling them to be controlled remotely.
## Enabling the Web Interface ##
## Enabling the web interface ##
Refer to the **Remote management** links in the [User Documentation](User-Documentation.md) for your client to find out how to enable the web interface.
Refer to the **Remote Management** links in the [User Documentation](User-Documentation.md) for your client to find out how to enable the Web Interface.
## Accessing the Web Interface ##
## Accessing the web interface ##
Once enabled, open a web browser and direct it to http://ip_address_of_machine_running_transmission:9091/
If web browser and Transmission Daemon are on the machine you can use http\://127.0.0.1:9091/
If the web browser and the Transmission daemon are on the machine you can use http\://127.0.0.1:9091/
9091 is the default remote control port specified in [Transmission configuration](Editing-Configuration-Files.md).

48
docs/Why-Are-My-Speeds-So-Slow.md
View File

@ -1,61 +1,51 @@
This checklist helps to diagnose the most common reasons for bad speeds &mdash; or no speed at all &mdash; and tells where to find more help if the checklist doesn't find the problem.
This checklist helps to diagnose the most common reasons for bad speeds &mdash; or no speed at all &mdash; and tells where to find more help if the checklist does not find the problem.
Please go through the _entire checklist_ before asking for more help! Otherwise the forum helpers will likely just point you back here. ;)
Please go through the _entire checklist_ before asking for more help! Otherwise the forum helpers will likely just point you back here.
## 1. Is it your network?
If you are not sure whether the problem is a specific torrent or your network, it is easy to get a point of reference &mdash; add a fast torrent for benchmarking. Many users visit [the Ubuntu torrent page](https://torrent.ubuntu.com:6969/), scan down the page for the line with the most seeders and downloaders, and join the swarm for a few minutes to see what speeds they will reach.
If you're not sure whether the problem is a specific torrent or your network, it's easy to get a point of reference &mdash; add a fast torrent for benchmarking. Many users visit [the Ubuntu torrent page](http://torrent.ubuntu.com:6969/), scan down the page for the line with the most seeders and downloaders, and join the swarm for a few minutes to see what speeds they'll reach.
More generally, you can also measure your bandwidth at [speedtest.net](http://www.speedtest.net/). However, this is not as good a Bittorrent benchmark as the previous approach.
More generally, you can also measure your bandwidth at [speedtest.net](https://www.speedtest.net/). However, this is not as good a BitTorrent benchmark as the previous approach.
## 2. Is your tracker responding?
Trackers are the primary source of finding other peers. When your tracker goes down, finding peers to share with is slower.
Look at the Tracker tab of the torrent dialog and see what it says about the last announce. Did the tracker respond "OK" or was there an error message?
## 3. Are there too many (or not enough) seeders?
In the inspector's tracker tab, you will see how many seeders and downloaders each tracker knows of.
In the inspector's tracker tab, you'll see how many seeders and downloaders each tracker knows of.
If you are seeding and so are most of the other participants, your speeds will be slow because all the seeders are competing for the downloaders' limited bandwidth.
If you're seeding and so are most of the other participants, your speeds will be slow because all the seeds are competing for the downloaders' limited bandwidth.
If you're downloading, things are a little better because you can download from everyone, not just seeds. But even so, it will still be slow if there aren't enough seeds in the swarm. All the downloaders will get stuck at the same completeness percentage as each other as they wait for more data to trickle down from the seeds. In practice this often looks like near-zero download speeds punctuated by bursts of fast downloading.
If you are downloading, things are a little better because you can download from everyone, not just seeders. But even so, it will still be slow if there are not enough seeders in the swarm. All the downloaders will get stuck at the same completion percentage as each other as they wait for more data to trickle down from the seeders. In practice this often looks like near-zero download speeds punctuated by bursts of fast downloading.
## 4. Is it your speed limits?
This falls into the are-you-sure-it-is-plugged-in category, but don't be embarrassed: lots of people have been bitten by this. Note: remember that there are both per-torrent and overall speed limits. :)
This falls into the are-you-sure-it-is-plugged-in category, but do not be embarrassed: lots of people have been bitten by this. Note: remember that there are both per-torrent and overall speed limits.
## 5. Is it a small swarm?
Even if you're the only downloader and there are four or five seeds ready to send you information, things can still be slow sometimes. Often what happens is the seeds' upload bandwidth is being shared between you and other peers in another torrent.
Even if you are the only downloader and there are four or five seeders ready to send you information, things can still be slow sometimes. Often what happens is the seeder's upload bandwidth is being shared between you and other peers in another torrent.
## 6. Are you uploading too fast?
If you try to upload to the limit of your connection bandwidth you may block your own downloads (which also use a little bit of upload bandwidth). It's best to limit uploads to no more than around 80% of nominal upload bandwidth. Remember many network connections are asymmetric &mdash; which in practice means that upload speeds may only be a fraction of download speeds. If your upload bandwidth is say 25KBytes/sec then a good value for torrent upload limits might be 20KBytes/sec.
If you try to upload to the limit of your connection bandwidth you may block your own downloads (which also use a little bit of upload bandwidth). It is best to limit uploads to no more than around 80% of your nominal upload bandwidth. Remember many network connections are asymmetric &mdash; which in practice means that upload speeds may only be a fraction of download speeds. If your upload bandwidth is say 25KBytes/sec then a good value for torrent upload limits might be 20KBytes/sec.
## 7. Is it your ISP?
If your ISP is one of those that manipulates BitTorrent packets &mdash; and even if it is not &mdash; it is often a good idea to enable the [Blocklist](./Blocklist.md) and also to tell Transmission to "Ignore Unencrypted Peers" to give your sessions slightly better privacy.
If your ISP is one of those that manipulates Bittorrent packets &mdash; and even if it isn't &mdash; it's often a good idea to enable the [Blocklist](./Blocklist.md) and also to tell Transmission to "Ignore Unencrypted Peers" to give your sessions slightly better privacy.
Update: Google now has [a free online tool](http://broadband.mpi-sws.org/transparency/bttest.php) to test what your ISP is doing. Follow that link and go down to the "Start testing" button.
Update: Google now has [a free online tool](https://broadband.mpi-sws.org/transparency/bttest.php) to test what your ISP is doing. Follow that link and go down to the "Start testing" button.
## 8. Is it an old version of Transmission?
Work is constantly being done to improve performance and behavior. If you're using an old version, consider upgrading.
Work is constantly being done to improve performance and behavior. If you are using an old version, consider upgrading.
## 9. Is it your router or firewall making your "port closed"?
Connecting to a peer is like a telephone call: either you call up the peer, or the peer calls you. When Transmission says your "Port is Closed" it is like having a phone that does not allow incoming calls: you can still call peers, but they cannot call you.
Connecting to a peer is like telephone calls: either you call up the peer, or the peer calls you. When Transmission says your "Port is Closed" it's like having a phone that doesn't allow incoming calls: you can still call peers, but they can't call you.
Many people do not want to mess with their firewall and/or router, so they decide that dialing out is good enough and leave their port closed. Other people panic and worry too much about getting their port open even if they have a troublesome router. The truth is in the middle &mdash; you _can_ get by with a closed port, but on average you will get much faster speeds if peers can connect to you.
Many people don't want to mess with their firewall and/or router, so they decide that dialing out is good enough and leave their port closed. Other people panic and worry too much about getting their port open even if they have a troublesome router. The truth is in the middle &mdash; you _can_ get by with a closed port, but on average you'll get much faster speeds if peers can connect to you.
Opening a closed port is often the most frustrating task in BitTorrent. The good news is that the Transmission wiki has two pages dedicated to this topic: the [Port Forwarding Guide](Port-Forwarding-Guide.md) and the [Why is my port closed](Why-is-my-port-closed.md) page.
Opening a closed port is often the most frustrating task in Bittorrent. The good news is that the Transmission wiki has two pages dedicated to this topic: the [Port Forwarding Guide](Port-Forwarding-Guide.md) and the [Why is my port closed](Why-is-my-port-closed.md) page.
You can also test your port status at [canyouseeme.org](http://www.canyouseeme.org/).
You can also test your port status at [canyouseeme.org](https://www.canyouseeme.org/).
## 10. Is it a Transmission Bug?
If you have looked at all the reasons above and none of them fit &mdash; Ubuntu downloaded quickly, and you got the latest version of Transmission, and there are plenty of seeds _and_ downloaders in your torrent, yet things are _still_ slow &mdash; then maybe you have found a Transmission bug. Go [read this post](https://forum.transmissionbt.com/viewtopic.php?f=1&t=3274) about what information the developers need to diagnose the problem, and then post a message describing your situation.
If you've looked at all the reasons above and none of them fit &mdash; Ubuntu downloaded quickly, and you've got the latest version of Transmission, and there are plenty of seeds _and_ downloaders in your torrent, yet things are _still_ slow &mdash; then maybe you've found a Transmission bug. Go [read this post](http://forum.transmissionbt.com/viewtopic.php?f=1&t=3274) about what information the developers need to diagnose the problem, and then post a message describing your situation.
Make sure to give enough information! Vague bug reports waste everyone's time and will probably just get you referred back to this page. :)
Make sure to give enough information! Vague bug reports waste everyone's time and will probably just get you referred back to this page.

35
docs/Why-is-my-port-closed.md
View File

@ -1,48 +1,41 @@
Transmission needs an open port to communicate. You can open one manually or let transmission try to acquire one using NAT PMP or UPnP. If both automatic port mapping and manual forwarding failed
## Open ports & forwarding
Transmission needs an open port to communicate. You can open one manually or let Transmission try to acquire one using NAT PMP or UPnP, if both automatic port mapping and manual forwarding failed.
## Open ports and port forwarding
For guide on how to open and forward your Transmission port, read the [Port Forwarding](Port-Forwarding-Guide.md) guide.
## Possible Problems
If you get the Message 'Port is closed'/'Port is Stealth' in the 'Ports' section of Transmission's preferences.
If you get the message "Port is closed"/"Port is Stealth" in the "Ports" section of Transmission's preferences.
### Port check website is down
Transmission needs an external site to check whether the port is open. However, if that site is down, Transmission has no way to check whether the port is open or not. If you suspect this is the case, go to [CanYouSeeMe.org](http://www.canyouseeme.org/).
Transmission needs an external site to check whether the port is open. However, if that site is down, Transmission has no way to check whether the port is open or not. If you suspect this is the case, go to [CanYouSeeMe.org](https://www.canyouseeme.org/).
### UPnP / NAT-PMP
For UPnP/NAT-PMP compatible routers, make sure:
* UPnP/NAT-PMP is enabled. Consult your router's documentation for instructions. If your router doesn't support UPnP/NAT-PMP, you will have to forward manually.
* UPnP/NAT-PMP is enabled. Consult your router's documentation for instructions. If your router does not support UPnP/NAT-PMP, you will have to forward manually.
* DMZ mode is disabled.
* The port has not already been forwarded manually.
* The port is not taken by another application
* The port has been released properly by Transmission. In some rare situations Transmission won't be able to release the port so it can't be acquired by Transmission afterwards.
* The port has been released properly by Transmission. In some rare situations Transmission will not be able to release the port so it cannot be acquired by another instance of Transmission afterwards.
Note: NAT-PMP is only for Apple Airport routers.
### Double NAT
Another possible reason your port remains closed could be because your router is not the only device on the network which needs to be configured.
For example, your network might resemble the following: ADSL modem/router &rarr; Netgear Router &rarr; Laptop.
For example, your network might resemble the following: ADSL modem/router &rarr; Netgear router &rarr; laptop.
If you have multiple routers in your home network (such as in the example above), you have two options. The easiest way is to turn one of the routers into 'Bridge mode' which means you then only have to configure one device rather than all of them. So, in our above example, we would set the Netgear router to 'Bridge'. See your router's help documentation for instructions.
The second way is to map Transmission's port on all of the devices on your network. Transmission can only automatically port map the router the computer is directly connected to. Any others in between this router and your modem will have to be forwarded manually. For detailed instructions, visit [portforward.com](http://www.portforward.com/help/doublerouterportforwarding.htm).
The second way is to map Transmission's port on all of the devices on your network. Transmission can only automatically port map the router the computer is directly connected to. Any others in between this router and your modem will have to be forwarded manually. For detailed instructions, visit [portforward.com](https://www.portforward.com/help/doublerouterportforwarding.htm).
Finally make sure your firewall is either disabled, or you have allowed Transmission's port. The firewall can cause the port to remain closed, even if it has been successfully mapped by the router(s).
Finally make sure your firewall is either disabled or you have allowed Transmission's port. The firewall can cause the port to remain closed, even if it has been successfully mapped by the router(s).
### ISP Blocking Port
Though initially this was done to "combat viruses and spam", it is sometimes used to keep out "bandwidth hogs". Normally the default (51413) port is fine. However, it might be that an ISP does decide to block that port. In such a case it is recommended to pick a random number between 49152 and 65535. If you can't find a port that's open (check with [CanYouSeeMe.org](http://www.canyouseeme.org/)), you have a different issue.
### ISP blocking ports
Though initially this was done to "combat viruses and spam", it is sometimes used to keep out "bandwidth hogs". Normally the default (51413) port is fine. However, it might be that an ISP does decide to block that port. In such a case it is recommended to pick a random number between 49152 and 65535. If you cannot find a port that is open (check with [CanYouSeeMe.org](https://www.canyouseeme.org/)), you have a different issue.
### LAN ISP
E.g. universities, Wi-Fi hotspots, RV parks and some "true" ISPs (common in Rome, Italy).
e.g. Universities, Wifi hotspots, RV parks and some 'true' ISPs (common in Rome, Italy).
Although these ISPs are often very interesting, offering high speeds, unlimited bandwidth (sometimes) and low prizes, this is because they do not buy IP addresses for their clients and provide the (local) network themselves.
Though these ISPs are often very interesting, offering high speeds, unlimited bandwidth (sometimes) and low prizes. This because they don't buy IP addresses for their clients and provide the (local) network themselves.
Basically the only thing you can do, is to ''politely'' ask for them to open (forward) a port for you.
Basically the only thing you can do, is to ''politely'' ask for them to forward a port for you.

92
docs/rpc-spec.md
View File

@ -1,28 +1,23 @@
# Transmission RPC Specification
# Transmission's RPC specification
This document describes a protocol for interacting with Transmission sessions remotely.
### 1.1 Terminology
The [JSON](https://www.json.org/) terminology in [RFC 4627](https://datatracker.ietf.org/doc/html/rfc4627) is used.
RPC requests and responses are formatted in JSON.
### 1.2 Tools
If `transmission-remote` is called with a `--debug` argument, its RPC traffic to the Transmission server will be dumped to the terminal. This can be useful when you want to compare requests in your application to another for reference.
If `transmission-qt` is run with an environment variable `TR_RPC_VERBOSE` set, it too will dump the RPC requests and responses to the terminal for inspection.
Lastly, using devtools in the Transmission web client is always an option.
## 2. Message Format
## 2 Message format
Messages are formatted as objects. There are two types: requests (described in 2.1) and responses (described in 2.2).
All text **must** be UTF-8 encoded.
### 2.1. Requests
### 2.1 Requests
Requests support three keys:
1. A required `method` string telling the name of the method to invoke
@ -42,8 +37,7 @@ Requests support three keys:
```
### 2.2. Responses
### 2.2 Responses
Responses to a request will include:
1. A required `result` string whose value MUST be `success` on success, or an error string on failure.
@ -60,8 +54,7 @@ Responses to a request will include:
}
```
### 2.3. Transport Mechanism
### 2.3 Transport mechanism
HTTP POSTing a JSON-encoded request is the preferred way of communicating
with a Transmission RPC server. The current Transmission implementation
has the default URL as `http://host:9091/transmission/rpc`. Clients
@ -69,8 +62,7 @@ may use this as a default, but should allow the URL to be reconfigured,
since the port and path may be changed to allow mapping and/or multiple
daemons to run on a single server.
#### 2.3.1. CSRF Protection
#### 2.3.1 CSRF protection
Most Transmission RPC servers require a X-Transmission-Session-Id
header to be sent with requests, to prevent CSRF attacks.
@ -82,8 +74,7 @@ right `X-Transmission-Session-Id` in its own headers.
So, the correct way to handle a 409 response is to update your
`X-Transmission-Session-Id` and to resend the previous request.
#### 2.3.2. DNS Rebinding Protection
#### 2.3.2 DNS rebinding protection
Additional check is being made on each RPC request to make sure that the
client sending the request does so using one of the allowed hostnames by
which RPC server is meant to be available.
@ -97,8 +88,7 @@ addresses are always implicitly allowed.
For more information on configuration, see settings.json documentation for
`rpc-host-whitelist-enabled` and `rpc-host-whitelist` keys.
#### 2.3.3. Authentication
#### 2.3.3 Authentication
Enabling authentication is an optional security feature that can be enabled
on Transmission RPC servers. Authentication occurs by method of HTTP Basic
Access Authentication.
@ -109,10 +99,8 @@ of this HTTP header is expected to be [`Basic <b64 credentials>`](https://develo
where <b64 credentials> is equal to a base64 encoded string of the
username and password (respectively), separated by a colon.
## 3. Torrent Requests
### 3.1. Torrent Action Requests
## 3 Torrent requests
### 3.1 Torrent action requests
| Method name | libtransmission function
|:--|:--
| `torrent-start` | tr_torrentStart
@ -126,13 +114,12 @@ All torrents are used if the `ids` argument is omitted.
`ids` should be one of the following:
1. an integer referring to a torrent id
2. a list of torrent id numbers, sha1 hash strings, or both
2. a list of torrent id numbers, SHA1 hash strings, or both
3. a string, `recently-active`, for recently-active torrents
Response arguments: none
### 3.2. Torrent Mutator: `torrent-set`
### 3.2 Torrent mutator: `torrent-set`
Method name: `torrent-set`
Request arguments:
@ -171,8 +158,7 @@ for `files-wanted`, `files-unwanted`, `priority-high`, `priority-low`, or
Response arguments: none
### 3.3. Torrent Accessor: `torrent-get`
### 3.3 Torrent accessor: `torrent-get`
Method name: `torrent-get`.
Request arguments:
@ -439,8 +425,7 @@ Response:
}
```
### 3.4. Adding a Torrent
### 3.4 Adding a torrent
Method name: `torrent-add`
Request arguments:
@ -471,8 +456,7 @@ Response arguments:
* When attempting to add a duplicate torrent, a `torrent-duplicate` object in the same form is returned, but the response's `result` value is still `success`.
### 3.5. Removing a Torrent
### 3.5 Removing a torrent
Method name: `torrent-remove`
| Key | Value Type | Description
@ -482,8 +466,7 @@ Method name: `torrent-remove`
Response arguments: none
### 3.6. Moving a Torrent
### 3.6 Moving a torrent
Method name: `torrent-set-location`
Request arguments:
@ -496,8 +479,7 @@ Request arguments:
Response arguments: none
### 3.7. Renaming a Torrent's Path
### 3.7 Renaming a torrent's path
Method name: `torrent-rename-path`
For more information on the use of this function, see the transmission.h
@ -515,10 +497,8 @@ Request arguments:
Response arguments: `path`, `name`, and `id`, holding the torrent ID integer
## 4. Session Requests
### 4.1. Session Arguments
## 4 Session requests
### 4.1 Session arguments
| Key | Value Type | Description
|:--|:--|:--
| `alt-speed-down` | number | max global download speed (KBps)
@ -597,8 +577,7 @@ It is changes when a new version of Transmission changes the RPC interface
in a way that is not backwards compatible. There are no plans for this
to be common behavior.
#### 4.1.1. Mutators
#### 4.1.1 Mutators
Method name: `session-set`
Request arguments: one or more of 4.1's arguments, except: `blocklist-size`,
@ -607,8 +586,7 @@ Request arguments: one or more of 4.1's arguments, except: `blocklist-size`,
Response arguments: none
#### 4.1.2. Accessors
#### 4.1.2 Accessors
Method name: `session-get`
Request arguments: an optional `fields` array of keys (see 4.1)
@ -616,8 +594,7 @@ Request arguments: an optional `fields` array of keys (see 4.1)
Response arguments: key/value pairs matching the request's `fields`
argument if present, or all supported fields (see 4.1) otherwise.
### 4.2. Session Statistics
### 4.2 Session statistics
Method name: `session-stats`
Request arguments: none
@ -644,16 +621,14 @@ A stats object contains:
| sessionCount | number | tr_session_stats
| secondsActive | number | tr_session_stats
### 4.3. Blocklist
### 4.3 Blocklist
Method name: `blocklist-update`
Request arguments: none
Response arguments: a number `blocklist-size`
### 4.4. Port Checking
### 4.4 Port checking
This method tests to see if your incoming peer port is accessible
from the outside world.
@ -663,8 +638,7 @@ Request arguments: none
Response arguments: a bool, `port-is-open`
### 4.5. Session shutdown
### 4.5 Session shutdown
This method tells the transmission session to shut down.
Method name: `session-close`
@ -673,8 +647,7 @@ Request arguments: none
Response arguments: none
### 4.6. Queue Movement Requests
### 4.6 Queue movement requests
| Method name | transmission.h source
|:--|:--
| `queue-move-top` | tr_torrentQueueMoveTop()
@ -690,8 +663,7 @@ Request arguments:
Response arguments: none
### 4.7. Free Space
### 4.7 Free space
This method tests how much free space is available in a
client-specified folder.
@ -712,9 +684,7 @@ Response arguments:
| `total_size` | number | the total capacity, in bytes, of that directory
### 4.8 Bandwidth groups
#### 4.8.1 Bandwidth group Mutator: `group-set`
#### 4.8.1 Bandwidth group mutator: `group-set`
Method name: `group-set`
Request parameters:
@ -730,8 +700,7 @@ Request parameters:
Response arguments: none
#### 4.8.2 Bandwidth group Accessor: `group-get`
#### 4.8.2 Bandwidth group accessor: `group-get`
Method name: `group-get`
Request arguments: An optional argument `group`.
@ -756,8 +725,7 @@ A bandwidth group description object has:
| `speed-limit-up-enabled` | boolean | true means enabled
| `speed-limit-up` | number | max global upload speed (KBps)
## 5. Protocol Versions
## 5 Protocol versions
This section lists the changes that have been made to the RPC protocol.
There are two ways to check for API compatibility. Since most developers know