Transmission/transmission
1
0
Fork 0
mirror of https://github.com/transmission/transmission.git synced 2026-04-18 16:07:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

(trunk) rename "doc" as "extras", and add transmission-1920.jpg there

Browse Source
This commit is contained in:
Charles Kerr
2010-08-02 02:49:52 +00:00
parent 1477c8909f
commit 068cc733df
9 changed files with 2 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
extras/Makefile.am Normal file
View File

@@ -0,0 +1,2 @@
EXTRA_DIST = rpc-spec.txt \
send-email-when-torrent-done.sh

175
extras/encryption.txt Normal file
View File

@@ -0,0 +1,175 @@
######################################################
### ----- Message Stream Encryption protocol ----- ###
### specification by Ludde/uau/The_8472/Parg/Nolar ###
######################################################
The following protocol describes a transparent wrapper for bidirectional
data streams (e.g. TCP transports) that prevents passive eavesdroping
and thus protocol or content identification.
It is also designed to provide limited protection against active MITM attacks
and portscanning by requiring a weak shared secret to complete the handshake.
You should note that the major design goal was payload and protocol obfuscation,
not peer authentication and data integrity verification. Thus it does not offer
protection against adversaries which already know the necessary data to establish
connections (that is IP/Port/Shared Secret/Payload protocol).
To minimize the load on systems that employ this protocol fast cryptographic
methods have been chosen over maximum-security algorithms.
----------------
- Declarations -
----------------
The entire handshake is in big-endian.
The crypto handshake is transparent to the next upper protocol,
thus the payload endianness doesn't matter.
A is the initiator of the underlying transport (e.g. a TCP connection)
B is the receiver
##### DH Parameters
Prime P is a 768 bit safe prime, "0xFFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E088A67CC74020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B302B0A6DF25F14374FE1356D6D51C245E485B576625E7EC6F44C42E9A63A36210000000000090563"
Generator G is "2"
Xa and Xb are a variable size random integers.
They are the private key for each side and have to be discarded after
the DH handshake is done. Minimum length is 128 bit. Anything beyond 180 bit
is not believed to add any further security and only increases the necessary
calculation time. You should use a length of 160bits whenever possible, lower
values may be used when CPU time is scarce.
Pubkey of A: Ya = (G^Xa) mod P
Pubkey of B: Yb = (G^Xb) mod P
DH secret: S = (Ya^Xb) mod P = (Yb^Xa) mod P
P, S, Ya and Yb are 768bits long
##### Constants/Variables
PadA, PadB: Random data with a random length of 0 to 512 bytes each
PadC, PadD: Arbitrary data with a length of 0 to 512 bytes, can be
used to extend the crypto handshake in future versions.
Current implementations may choose to set them to 0-length.
For padding-only usage in the current version they should be zeroed.
VC is a verification constant that is used to verify whether the other
side knows S and SKEY and thus defeats replay attacks of the SKEY hash.
As of this version VC is a String of 8 bytes set to 0x00.
crypto_provide and crypto_select are a 32bit bitfields.
As of now 0x01 means plaintext, 0x02 means RC4. (see Functions)
The remaining bits are reserved for future use.
The initiating peer A should provide all methods he supports in the bitfield,
but he may choose only to provide higher encryption levels e.g. if plaintext
isn't sufficient for it's security needs.
The responding peer B should set a bit corresponding to the single method
which he selected from the provided ones.
Bits with an unknown meaning in crypto_provide and crypto_select
should be ignored as they might be used in future versions.
SKEY = Stream Identifier/Shared secret used to drop connections early if we
don't have a matching stream. It's additionally used to harden the protocol
against MITM attacks and portscanning.
Protocols w/o unique stream properties may use a constant.
Note: For BitTorrent, the SKEY should be the torrent info hash.
IA = initial payload data from A
may be 0-sized if you want to wait for the encryption negotation.
Peer A may buffer up to 65535 bytes before or during the DH handshake to append
it to the 3rd step. IA is considered as atomic and thus an implementation may
not expect that anything is handed to the upper layer before IA is completely
transmitted. Thus there must be no blocking operations within IA.
Note, Example for Bittorrent:
After \19Bittorrent protocol + the BT handshake a block occurs since A waits
for B to send his handshake before A continues to send his bitfield,
thus IA can only include the prefix + the bt handshake but not the bitfield
###### Functions
len(X) specifies the length of X in 2 bytes.
Thus the maximum length that can be specified is 65535 bytes, this is
important for the IA block.
ENCRYPT() is RC4, that uses one of the following keys to send data:
"HASH('keyA', S, SKEY)" if you're A
"HASH('keyB', S, SKEY)" if you're B
The first 1024 bytes of the RC4 output are discarded.
consecutive calls to ENCRYPT() by one side continue the encryption
stream (no reinitialization, no keychange). They are only used to distinguish
semantically seperate content.
ENCRYPT2() is the negotiated crypto method.
Current options are:
0x01 Plaintext. After the specified length (see IA/IB) each side sends unencrypted payload
0x02 RC4-128. The ENCRYPT() RC4 encoding is continued (no reinitialization, no keychange)
HASH() is SHA1 binary output (20 bytes)
###### The handshake "packet" format
The handshake is seperated into 5 blocking steps.
1 A->B: Diffie Hellman Ya, PadA
2 B->A: Diffie Hellman Yb, PadB
3 A->B: HASH('req1', S), HASH('req2', SKEY) xor HASH('req3', S), ENCRYPT(VC, crypto_provide, len(PadC), PadC, len(IA)), ENCRYPT(IA)
4 B->A: ENCRYPT(VC, crypto_select, len(padD), padD), ENCRYPT2(Payload Stream)
5 A->B: ENCRYPT2(Payload Stream)
Since the length of PadA and PadB are unknown
B will be able to resynchronize on HASH('req1', S)
A will be able to resynchronize on ENCRYPT(VC)
##### Optional early termination conditions
(should verified before the indicated step is started).
If a fail-fast behavior is prefered the following conditions can be used to
disconnect the peer immediately. If less recognizable patterns are preferred
a peer may wait and disconnect at a later point. If any of these conditions
are met the handshake can be considered as invalid.
2 (termination by B)
if A sent less than 96 Bytes within 30 seconds
if A sent more than 608 bytes
3 (termination by A)
if B sent less than 96 Bytes within 30 seconds
if B sent more than 608 bytes
4 (termination by B)
if A didn't send the correct S hash within 628 bytes after the connection start (synchronisation point)
if A didn't send a supported SKEY hash after the S hash
if VC can't be decoded correctly after the SKEY hash
if none of the crypto_provide options are supported or the bitfield is zeroed
from here on it's up to the next protocol layer to terminate the connection
5 (termination by A)
if VC can't be decoded correctly within 616 bytes after the connection start (synchronisation point)
if the selected crypto method wasn't provided
from here on it's up to the next protocol layer to terminate the connection

61
extras/extended-messaging.txt Normal file
View File

@@ -0,0 +1,61 @@
A client that understands extended messages should set the 5th
bit of the 6th byte of the reserved area in the handshake. For
example: reserved[5] = 0x10
If the above bit is set in both peers' handshakes then they may
exchange extended messages, which use id 20. The first byte of an
extended message (after the 4-byte length and 1-byte id, of course) is
the extended message id. The first extended message that should be
sent is a handshake message, which always has an extended id of 0.
The handshake message informs the peer which extended messages are
supported and what their extended id will be. The message payload is
a bencoded dictionary which may have some of the following keys:
e
int, 1 or 0. a flag to denote whether the peer prefers
encrypted connections. This is used in ut_pex's "added.f".
m
dict containing supported extended messages and the extended id used
p
int, tcp port for incoming peer connections
v
string, client name and version. eg: Transmission 0.7
A peer may re-send the handshake message at any time to add new
extended message, or to disable previous messages by sending 0 as
their extended id.
uTorrent peer exchange messages use the key "ut_pex" in the m
dictionary. If the uTorrent peer has pex disabled, this key
will not be present. Exchanges messages should be sent approximately
once every minute when peers have been added or dropped.
If peers have not been added or dropped, uTorrent does not send
the periodic PEX message. If uTorrent 1.8.1 recieves an "empty"
pex message from Transmission 1.40, it appears to interpret this
as an invalid message and disconnect from Transmission.
The payload of a peer exchange message is a
bencoded dictionary with the following keys:
added
string, contains peers in the compact tracker format
(ie: 6 bytes for IPv4 address and port in network byte order)
added since the last peer exchange message
added.f
string, one byte of flags for each peer in the above added string.
according to libtorrent's ut_pex.c:
1: encryption
2: seed/upload_only
4: uTP support
8: holepunch support
16: outgoing connection (implies peer is connectible)
dropped
same format as added, contains peers dropped since last peer exchange
In contrast to Azureus' maximum of 50 peers per pex burst, uTorrent will
hold up to 200. alus reports: "uT stores max 200 from other peers, but it
will send everything it has."

5
extras/properties.txt Normal file
View File

@@ -0,0 +1,5 @@
This file is here because I can never remember these commands...
svn propset svn:keywords 'Date Rev Author Id' filename
find . -type f \! -path \*.svn\* | xargs grep '\$Id\$'

629
extras/rpc-spec.txt Normal file
View File

@@ -0,0 +1,629 @@
1. Introduction
This document describes a protocol for interacting with Transmission
sessions remotely.
1.1 Terminology
The JSON terminology in RFC 4627 is used.
In benc terms, a JSON "array" is equivalent to a benc list,
a JSON "object" is equivalent to a benc dictionary,
and a JSON object's "keys" are the dictionary's string keys.
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
Requests support three keys:
(1) A required "method" string telling the name of the method to invoke
(2) An optional "arguments" object of key/value pairs
(3) An optional "tag" number used by clients to track responses.
If provided by a request, the response MUST include the same tag.
2.2. Responses
Reponses support three keys:
(1) A required "result" string whose value MUST be "success" on success,
or an error string on failure.
(2) An optional "arguments" object of key/value pairs
(3) An optional "tag" number as described in 2.1.
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
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.
In addition to POSTing, there's also a simple notation for sending
requests in the query portion of a URL. This is not as robust, but can
be useful for debugging and simple tasks. The notation works as follows:
(1) Any key not "tag" or "method" is treated as an argument.
(2) The "arguments" key isn't needed, since data isn't nested.
(3) If the value in a key/value pair can be parsed as a number, then it is.
Otherwise if it can be parsed as an array of numbers, then it is.
Otherwise, it's parsed as a string.
Examples:
?method=torrent-start&ids=1,2
?method=session-set&speed-limit-down=50&speed-limit-down-enabled=1
3. Torrent Requests
3.1. Torrent Action Requests
Method name | libtransmission function
---------------------+-------------------------------------------------
"torrent-start" | tr_torrentStart
"torrent-stop" | tr_torrentStop
"torrent-verify" | tr_torrentVerify
"torrent-reannounce" | tr_torrentManualUpdate ("ask tracker for more peers")
Request arguments: "ids", which specifies which torrents to use.
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
(3) a string, "recently-active", for recently-active torrents
Response arguments: none
3.2. Torrent Mutators
Method name: "torrent-set"
Request arguments:
string | value type & description
----------------------+-------------------------------------------------
"bandwidthPriority" | number this torrent's bandwidth tr_priority_t
"downloadLimit" | number maximum download speed (KBps)
"downloadLimited" | boolean true if "downloadLimit" is honored
"files-wanted" | array indices of file(s) to download
"files-unwanted" | array indices of file(s) to not download
"honorsSessionLimits" | boolean true if session upload limits are honored
"ids" | array torrent list, as described in 3.1
"location" | string new location of the torrent's content
"peer-limit" | number maximum number of peers
"priority-high" | array indices of high-priority file(s)
"priority-low" | array indices of low-priority file(s)
"priority-normal" | array indices of normal-priority file(s)
"seedIdleLimit" | number torrent-level number of minutes of seeding inactivity
"seedIdleMode" | number which seeding inactivity to use. See tr_inactvelimit
"seedRatioLimit" | double torrent-level seeding ratio
"seedRatioMode" | number which ratio to use. See tr_ratiolimit
"trackerAdd" | array strings of URLs to add
"trackerRemove" | array strings of URLs to remove
"trackerReplace" | array pairs of old/new announce URLs
"uploadLimit" | number maximum upload speed (KBps)
"uploadLimited" | boolean true if "uploadLimit" is honored
Just as an empty "ids" value is shorthand for "all ids", using an empty array
for "files-wanted", "files-unwanted", "priority-high", "priority-low", or
"priority-normal" is shorthand for saying "all files".
Response arguments: none
3.3. Torrent Accessors
Method name: "torrent-get".
Request arguments:
(1) An optional "ids" array as described in 3.1.
(2) A required "fields" array of keys. (see list below)
Response arguments:
(1) A "torrents" array of objects, each of which contains
the key/value pairs matching the request's "fields" argument.
(2) If the request's "ids" field was "recently-active",
a "removed" array of torrent-id numbers of recently-removed
torrents.
Note: For more information on what these fields mean, see the comments
in libtransmission/transmission.h. The "source" column here
corresponds to the data structure there.
key | type | source
----------------------------+-----------------------------+---------
activityDate | number | tr_stat
addedDate | number | tr_stat
bandwidthPriority | number | tr_priority_t
comment | string | tr_info
corruptEver | number | tr_stat
creator | string | tr_info
dateCreated | number | tr_info
desiredAvailable | number | tr_stat
doneDate | number | tr_stat
downloadDir | string | tr_torrent
downloadedEver | number | tr_stat
downloadLimit | number | tr_torrent
downloadLimited | boolean | tr_torrent
error | number | tr_stat
errorString | string | tr_stat
eta | number | tr_stat
files | array (see below) | n/a
fileStats | array (see below) | n/a
hashString | string | tr_info
haveUnchecked | number | tr_stat
haveValid | number | tr_stat
honorsSessionLimits | boolean | tr_torrent
id | number | tr_torrent
isFinished | boolean | tr_stat
isPrivate | boolean | tr_torrent
leftUntilDone | number | tr_stat
magnetLink | number | n/a
manualAnnounceTime | number | tr_stat
maxConnectedPeers | number | tr_torrent
metadataPercentComplete | double | tr_stat
name | string | tr_info
peer-limit | number | tr_torrent
peers | array (see below) | n/a
peersConnected | number | tr_stat
peersFrom | object (see below) | n/a
peersGettingFromUs | number | tr_stat
peersKnown | number | tr_stat
peersSendingToUs | number | tr_stat
percentDone | double | tr_stat
pieces | string (see below) | tr_torrent
pieceCount | number | tr_info
pieceSize | number | tr_info
priorities | array (see below) | n/a
rateDownload (KBps) | double | tr_stat
rateUpload (KBps) | double | tr_stat
recheckProgress | double | tr_stat
seedIdleLimit | number | tr_torrent
seedIdleMode | number | tr_inactvelimit
seedRatioLimit | double | tr_torrent
seedRatioMode | number | tr_ratiolimit
sizeWhenDone | number | tr_stat
startDate | number | tr_stat
status | number | tr_stat
trackers | array (see below) | n/a
trackerStats | array (see below) | n/a
totalSize | number | tr_info
torrentFile | string | tr_info
uploadedEver | number | tr_stat
uploadLimit | number | tr_torrent
uploadLimited | boolean | tr_torrent
uploadRatio | double | tr_stat
wanted | array (see below) | n/a
webseeds | array (see below) | n/a
webseedsSendingToUs | number | tr_stat
| |
| |
-------------------+--------+-----------------------------+
files | array of objects, each containing: |
+-------------------------+------------+
| key | type |
| bytesCompleted | number | tr_torrent
| length | number | tr_info
| name | string | tr_info
-------------------+--------------------------------------+
fileStats | a file's non-constant properties. |
| array of tr_info.filecount objects, |
| each containing: |
+-------------------------+------------+
| bytesCompleted | number | tr_torrent
| wanted | boolean | tr_info
| priority | number | tr_info
-------------------+--------------------------------------+
peers | array of objects, each containing: |
+-------------------------+------------+
| address | string | tr_peer_stat
| clientName | string | tr_peer_stat
| clientIsChoked | boolean | tr_peer_stat
| clientIsInterested | boolean | tr_peer_stat
| flagStr | string | tr_peer_stat
| isDownloadingFrom | boolean | tr_peer_stat
| isEncrypted | boolean | tr_peer_stat
| isIncoming | boolean | tr_peer_stat
| isUploadingTo | boolean | tr_peer_stat
| peerIsChoked | boolean | tr_peer_stat
| peerIsInterested | boolean | tr_peer_stat
| port | number | tr_peer_stat
| progress | double | tr_peer_stat
| rateToClient (KBps) | double | tr_peer_stat
| rateToPeer (KBps) | double | tr_peer_stat
-------------------+--------------------------------------+
peersFrom | an object containing: |
+-------------------------+------------+
| fromCache | number | tr_stat
| fromDht | number | tr_stat
| fromIncoming | number | tr_stat
| fromLtep | number | tr_stat
| fromPex | number | tr_stat
| fromTracker | number | tr_stat
-------------------+--------------------------------------+
pieces | A bitfield holding pieceCount flags | tr_torrent
| which are set to 'true' if we have |
| the piece matching that position. |
| JSON doesn't allow raw binary data, |
| so this is a base64-encoded string. |
-------------------+--------------------------------------+
priorities | an array of tr_info.filecount | tr_info
| numbers. each is the tr_priority_t |
| mode for the corresponding file. |
-------------------+--------------------------------------+
trackers | array of objects, each containing: |
+-------------------------+------------+
| announce | string | tr_tracker_info
| scrape | string | tr_tracker_info
| tier | number | tr_tracker_info
| id | number | tr_tracker_info
-------------------+--------------------------------------+
trackerStats | array of objects, each containing: |
+-------------------------+------------+
| announce | string | tr_tracker_stat
| announceState | number | tr_tracker_stat
| downloadCount | number | tr_tracker_stat
| hasAnnounced | boolean | tr_tracker_stat
| hasScraped | boolean | tr_tracker_stat
| host | string | tr_tracker_stat
| id | number | tr_tracker_stat
| isBackup | boolean | tr_tracker_stat
| lastAnnouncePeerCount | number | tr_tracker_stat
| lastAnnounceResult | string | tr_tracker_stat
| lastAnnounceStartTime | number | tr_tracker_stat
| lastAnnounceSucceeded | boolean | tr_tracker_stat
| lastAnnounceTime | number | tr_tracker_stat
| lastAnnounceTimedOut | boolean | tr_tracker_stat
| lastScrapeResult | string | tr_tracker_stat
| lastScrapeStartTime | number | tr_tracker_stat
| lastScrapeSucceeded | boolean | tr_tracker_stat
| lastScrapeTime | number | tr_tracker_stat
| lastScrapeTimedOut | boolean | tr_tracker_stat
| leecherCount | number | tr_tracker_stat
| nextAnnounceTime | number | tr_tracker_stat
| nextScrapeTime | number | tr_tracker_stat
| scrapeState | number | tr_tracker_stat
| seederCount | number | tr_tracker_stat
| tier | number | tr_tracker_stat
-------------------+-------------------------+------------+
wanted | an array of tr_info.fileCount | tr_info
| 'booleans' true if the corresponding |
| file is to be downloaded. |
-------------------+--------------------------------------+
webseeds | an array of strings: |
+-------------------------+------------+
| webseed | string | tr_info
+-------------------------+------------+
Example:
Say we want to get the name and total size of torrents #7 and #10.
Request:
{
"arguments": {
"fields": [ "id", "name", "totalSize" ],
"ids": [ 7, 10 ]
},
"method": "torrent-get",
"tag": 39693
}
Response:
{
"arguments": {
"torrents": [
{
"id": 10,
"name": "Fedora x86_64 DVD",
"totalSize": 34983493932,
},
{
"id": 7,
"name": "Ubuntu x86_64 DVD",
"totalSize", 9923890123,
}
]
},
"result": "success",
"tag": 39693
}
3.4. Adding a Torrent
Method name: "torrent-add"
Request arguments:
key | value type & description
---------------------+-------------------------------------------------
"download-dir" | string path to download the torrent to
"filename" | string filename or URL of the .torrent file
"metainfo" | string base64-encoded .torrent content
"paused" | boolean if true, don't start the torrent
"peer-limit" | number maximum number of peers
"bandwidthPriority" | number torrent's bandwidth tr_priority_t
"files-wanted" | array indices of file(s) to download
"files-unwanted" | array indices of file(s) to not download
"priority-high" | array indices of high-priority file(s)
"priority-low" | array indices of low-priority file(s)
"priority-normal" | array indices of normal-priority file(s)
Either "filename" OR "metainfo" MUST be included.
All other arguments are optional.
Response arguments: on success, a "torrent-added" object in the
form of one of 3.3's tr_info objects with the
fields for id, name, and hashString.
3.5. Removing a Torrent
Method name: "torrent-remove"
Request arguments:
string | value type & description
---------------------------+-------------------------------------------------
"ids" | array torrent list, as described in 3.1
"delete-local-data" | boolean delete local data. (default: false)
Response arguments: none
3.6. Moving a Torrent
Method name: "torrent-set-location"
Request arguments:
string | value type & description
---------------------------+-------------------------------------------------
"ids" | array torrent list, as described in 3.1
"location" | string the new torrent location
"move" | boolean if true, move from previous location.
| otherwise, search "location" for files
Response arguments: none
4. Session Requests
4.1. Session Arguments
string | value type & description
---------------------------------+-------------------------------------------------
"alt-speed-down" | number max global download speed (KBps)
"alt-speed-enabled" | boolean true means use the alt speeds
"alt-speed-time-begin" | number when to turn on alt speeds (units: minutes after midnight)
"alt-speed-time-enabled" | boolean true means the scheduled on/off times are used
"alt-speed-time-end" | number when to turn off alt speeds (units: same)
"alt-speed-time-day" | number what day(s) to turn on alt speeds (look at tr_sched_day)
"alt-speed-up" | number max global upload speed (KBps)
"blocklist-enabled" | boolean true means enabled
"blocklist-size" | number number of rules in the blocklist
"cache-size" | number maximum size of the disk cache (MB)
"config-dir" | string location of transmission's configuration directory
"download-dir" | string default path to download torrents
"dht-enabled" | boolean true means allow dht in public torrents
"encryption" | string "required", "preferred", "tolerated"
"inactive-seeding-limit" | number the default seed inactivity limit for torrents to use
"inactive-seeding-limit-enabled" | boolean true if the seeding inactivity limit is honored by default
"incomplete-dir" | string path for incomplete torrents, when enabled
"incomplete-dir-enabled" | boolean true means keep torrents in incomplete-dir until done
"lpd-enabled" | boolean true means allow Local Peer Discovery in public torrents
"peer-limit-global" | number maximum global number of peers
"peer-limit-per-torrent" | number maximum global number of peers
"pex-enabled" | boolean true means allow pex in public torrents
"peer-port" | number port number
"peer-port-random-on-start" | boolean true means pick a random peer port on launch
"port-forwarding-enabled" | boolean true means enabled
"rename-partial-files" | boolean true means append ".part" to incomplete files
"rpc-version" | number the current RPC API version
"rpc-version-minimum" | number the minimum RPC API version supported
"script-torrent-done-filename" | string filename of the script to run
"script-torrent-done-enabled" | boolean whether or not to call the "done" script
"seedRatioLimit" | double the default seed ratio for torrents to use
"seedRatioLimited" | boolean true if seedRatioLimit is honored by default
"speed-limit-down" | number max global download speed (KBps)
"speed-limit-down-enabled" | boolean true means enabled
"speed-limit-up" | number max global upload speed (KBps)
"speed-limit-up-enabled" | boolean true means enabled
"start-added-torrents" | boolean true means added torrents will be started right away
"trash-original-torrent-files" | boolean true means the .torrent file of added torrents will be deleted
"version" | string long version string "$version ($revision)"
"rpc-version" indicates the RPC interface version supported by the RPC server.
It is incremented when a new version of Transmission changes the RPC interface.
"rpc-version-minimum" indicates the oldest API supported by the RPC server.
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
Method name: "session-set"
Request arguments: one or more of 4.1's arguments, except: "blocklist-size",
"config-dir", "rpc-version", "rpc-version-minimum",
and "version"
Response arguments: none
4.1.2. Accessors
Method name: "session-get"
Request arguments: none
Response arguments: all of 4.1's arguments
4.2. Session Statistics
Method name: "session-stats"
Request arguments: none
Response arguments:
string | value type
---------------------------+-------------------------------------------------
"activeTorrentCount" | number
"downloadSpeed" | number
"pausedTorrentCount" | number
"torrentCount" | number
"uploadSpeed" | number
---------------------------+-------------------------------+
"cumulative-stats" | object, containing: |
+------------------+------------+
| uploadedBytes | number | tr_session_stats
| downloadedBytes | number | tr_session_stats
| filesAdded | number | tr_session_stats
| sessionCount | number | tr_session_stats
| secondsActive | number | tr_session_stats
---------------------------+-------------------------------+
"current-stats" | object, containing: |
+------------------+------------+
| uploadedBytes | number | tr_session_stats
| downloadedBytes | number | tr_session_stats
| filesAdded | number | tr_session_stats
| sessionCount | number | tr_session_stats
| secondsActive | number | tr_session_stats
4.3. Blocklist
Method name: "blocklist-update"
Request arguments: none
Response arguments: a number "blocklist-size"
4.4. Port Checking
This method tests to see if your incoming peer port is accessible
from the outside world.
Method name: "port-test"
Request arguments: none
Response arguments: a bool, "port-is-open"
5.0. Protocol Versions
The following changes have been made to the RPC interface:
RPC | Release | Backwards | |
Vers. | Version | Compat? | Method | Description
------+---------+-----------+----------------+-------------------------------
1 | 1.30 | n/a | n/a | Initial version
------+---------+-----------+----------------+-------------------------------
2 | 1.34 | yes | torrent-get | new arg "peers"
------+---------+-----------+----------------+-------------------------------
3 | 1.41 | yes | torrent-get | added "port" to "peers"
| | yes | torrent-get | new arg "downloaders"
| | yes | session-get | new arg "version"
| | yes | torrent-remove | new method
------+---------+-----------+----------------+-------------------------------
4 | 1.50 | yes | session-get | new arg "rpc-version"
| | yes | session-get | new arg "rpc-version-minimum"
| | yes | session-stats | added "cumulative-stats"
| | yes | session-stats | added "current-stats"
| | yes | torrent-get | new arg "downloadDir"
------+---------+-----------+----------------+-------------------------------
5 | 1.60 | yes | | new method "torrent-reannounce"
| | yes | | new method "blocklist-update"
| | yes | | new method "port-test"
| | | |
| | yes | session-get | new arg "alt-speed-begin"
| | yes | session-get | new arg "alt-speed-down"
| | yes | session-get | new arg "alt-speed-enabled"
| | yes | session-get | new arg "alt-speed-end"
| | yes | session-get | new arg "alt-speed-time-enabled"
| | yes | session-get | new arg "alt-speed-up"
| | yes | session-get | new arg "blocklist-enabled"
| | yes | session-get | new arg "blocklist-size"
| | yes | session-get | new arg "peer-limit-per-torrent"
| | yes | session-get | new arg "seedRatioLimit"
| | yes | session-get | new arg "seedRatioLimited"
| | NO | session-get | renamed "pex-allowed" to "pex-enabled"
| | NO | session-get | renamed "port" to "peer-port"
| | NO | session-get | renamed "peer-limit" to "peer-limit-global"
| | | |
| | yes | torrent-add | new arg "files-unwanted"
| | yes | torrent-add | new arg "files-wanted"
| | yes | torrent-add | new arg "priority-high"
| | yes | torrent-add | new arg "priority-low"
| | yes | torrent-add | new arg "priority-normal"
| | | |
| | yes | torrent-set | new arg "bandwidthPriority"
| | yes | torrent-set | new arg "honorsSessionLimits"
| | yes | torrent-set | new arg "seedRatioLimit"
| | yes | torrent-set | new arg "seedRatioLimited"
| | NO | torrent-set | renamed "speed-limit-down" to "downloadLimit"
| | NO | torrent-set | renamed "speed-limit-down-enabled" to "downloadLimited"
| | NO | torrent-set | renamed "speed-limit-up" to "uploadLimit"
| | NO | torrent-set | renamed "speed-limit-up-enabled" to "uploadLimited"
| | | |
| | yes | torrent-get | new arg "bandwidthPriority"
| | yes | torrent-get | new arg "fileStats"
| | yes | torrent-get | new arg "honorsSessionLimits"
| | yes | torrent-get | new arg "percentDone"
| | yes | torrent-get | new arg "pieces"
| | yes | torrent-get | new arg "seedRatioLimit"
| | yes | torrent-get | new arg "seedRatioMode"
| | yes | torrent-get | new arg "torrentFile"
| | yes | torrent-get | new ids option "recently-active"
| | NO | torrent-get | removed arg "downloadLimitMode"
| | NO | torrent-get | removed arg "uploadLimitMode"
------+---------+-----------+----------------+-------------------------------
6 | 1.70 | yes | | new "method torrent-set-location"
------+---------+-----------+----------------+-------------------------------
7 | 1.80 | NO | torrent-get | removed arg "announceResponse"
| | NO | torrent-get | removed arg "announceURL"
| | NO | torrent-get | removed arg "downloaders"
| | NO | torrent-get | removed arg "lastAnnounceTime"
| | NO | torrent-get | removed arg "lastScrapeTime"
| | NO | torrent-get | removed arg "leechers"
| | NO | torrent-get | removed arg "nextAnnounceTime"
| | NO | torrent-get | removed arg "nextScrapeTime"
| | NO | torrent-get | removed arg "scrapeResponse"
| | NO | torrent-get | removed arg "scrapeURL"
| | NO | torrent-get | removed arg "seeders"
| | NO | torrent-get | removed arg "timesCompleted"
| | NO | torrent-get | removed arg "swarmSpeed"
| | yes | torrent-get | new arg "magnetLink"
| | yes | torrent-get | new arg "metadataPercentComplete"
| | yes | torrent-get | new arg "trackerStats"
| | yes | session-set | new arg "incomplete-dir"
| | yes | session-set | new arg "incomplete-dir-enabled"
------+---------+-----------+----------------+-------------------------------
8 | 1.90 | yes | session-set | new arg "rename-partial-files"
| | yes | session-get | new arg "rename-partial-files"
| | yes | session-get | new arg "config-dir"
| | yes | torrent-add | new arg "bandwidthPriority"
| | yes | torrent-get | new trackerStats arg "lastAnnounceTimedOut"
------+---------+-----------+----------------+-------------------------------
8 | 1.92 | yes | torrent-get | new trackerStats arg "lastScrapeTimedOut"
------+---------+-----------+----------------+-------------------------------
9 | 2.00 | yes | session-set | new arg "start-added-torrents"
| | yes | session-set | new arg "trash-original-torrent-files"
| | yes | session-get | new arg "start-added-torrents"
| | yes | session-get | new arg "trash-original-torrent-files"
| | yes | torrent-get | new arg "isFinished"
------+---------+-----------+----------------+-------------------------------
10 | 2.10 | yes | session-get | new arg "cache-size"
| | yes | session-set | new arg "trash-original-torrent-files"
| | yes | session-get | new arg "trash-original-torrent-files"
| | yes | torrent-get | new arg "isFinished"
| | yes | torrent-set | new arg "trackerAdd"
| | yes | torrent-set | new arg "trackerEdit"
| | yes | torrent-set | new arg "trackerRemove"
| | yes | session-set | new arg "inactive-seeding-limit"
| | yes | session-set | new arg "inactive-seeding-limit-enabled"
| | yes | session-get | new arg "inactive-seeding-limit"
| | yes | session-get | new arg "inactive-seeding-limit-enabled"
| | yes | torrent-set | new arg "seedIdleLimit"
| | yes | torrent-set | new arg "seedIdleMode"

53
extras/send-email-when-torrent-done.sh Executable file
View File

@@ -0,0 +1,53 @@
#!/bin/sh
##
## User-configurable Variables
##
# Where "nail" is installed on your system.
# We need this to actually send the mail, so make sure it's installed
NAIL=/usr/bin/nail
# REQUIRED CHANGE #1: you must set SMTP_SERVER
# http://www.host45.com/resources/ispsmtps.php has a list of ISP's smtp servers
SMTP_SERVER=your.smtp.server
# REQUIRED CHANGE #2: you must set your email address.
# option A: change "yourname@yourmail.com" here and remove the leading '#' to
# use a real email address
#TO_ADDR=yourname@yourmail.com
#
# option B: for an SMS message, set your phone number here and remove the
# leading '#' on the PHONENUM line and your phone provider's TO_ADDR line
#PHONENUM="1234567890"
#TO_ADDR="$PHONENUM@message.alltel.com" # SMS: Alltel
#TO_ADDR="$PHONENUM@txt.att.net" # SMS: AT&T (formerly Cingular)
#TO_ADDR="$PHONENUM@myboostmobile.com" # SMS: Boost Mobile
#TO_ADDR="$PHONENUM@sms.mycricket.com" # SMS: Cricket Wireless
#TO_ADDR="$PHONENUM@messaging.nextel.com" # SMS: Nextel (Sprint Nextel)
#TO_ADDR="$PHONENUM@messaging.sprintpcs.com" # SMS: Sprint (Sprint Nextel)
#TO_ADDR="$PHONENUM@tmomail.net" # SMS: T-Mobile
#TO_ADDR="$PHONENUM@vtext.com" # SMS: Verizon
#TO_ADDR="$PHONENUM@vmobl.com" # SMS: Virgin Mobile USA
#TO_ADDR="$PHONENUM@txt.bellmobility.ca" # SMS: Bell Canada
#TO_ADDR="$PHONENUM@cwemail.com" # SMS: Centennial Wireless
#TO_ADDR="$PHONENUM@csouth1.com" # SMS: Cellular Sout
#TO_ADDR="$PHONENUM@gocbw.com" # SMS: Cincinnati Bell
#TO_ADDR="$PHONENUM@mymetropcs.com" # SMS: Metro PCS 1
#TO_ADDR="$PHONENUM@metropcs.sms.us" # SMS: Metro PCS 2
#TO_ADDR="$PHONENUM@qwestmp.com" # SMS: Quest
#TO_ADDR="$PHONENUM@pcs.rogers.com" # SMS: Rogers
#TO_ADDR="$PHONENUM@tms.suncom.com" # SMS: Suncom
#TO_ADDR="$PHONENUM@msg.telus.com" # SMS: Telus
#TO_ADDR="$PHONENUM@email.uscc.net" # SMS: U.S. Cellular
###
### Send the mail...
###
SUBJECT="Torrent Done!"
FROM_ADDR="transmission@localhost.localdomain"
TMPFILE=`mktemp -t transmission.XXXXXXXXXX`
echo "Transmission finished downloading \"$TR_TORRENT_NAME\" on $TR_TIME_LOCALTIME" >$TMPFILE
$NAIL -v -S from="$FROM_ADDR" -S smtp -s "$SUBJECT" -S smtp=$SMTP_SERVER "$TO_ADDR" < $TMPFILE
rm $TMPFILE

BIN
extras/transmission-1920.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 391 KiB