The (gnu services file-sharing) module provides services that assist
with transferring files over peer-to-peer file-sharing networks.
Transmission is a flexible BitTorrent
client that offers a variety of graphical and command-line interfaces. A
transmission-daemon-service-type service provides Transmission’s
headless variant, transmission-daemon, as a system service,
allowing users to share files via BitTorrent even when they are not logged
in.
The service type for the Transmission Daemon BitTorrent client. Its value
must be a transmission-daemon-configuration object as in this
example:
(service transmission-daemon-service-type (transmission-daemon-configuration ;; Restrict access to the RPC ("control") interface (rpc-authentication-required? #t) (rpc-username "transmission") (rpc-password (transmission-password-hash "transmission" ; desired password "uKd1uMs9")) ; arbitrary salt value ;; Accept requests from this and other hosts on the ;; local network (rpc-whitelist-enabled? #t) (rpc-whitelist '("::1" "127.0.0.1" "192.168.0.*")) ;; Limit bandwidth use during work hours (alt-speed-down (* 1024 2)) ; 2 MB/s (alt-speed-up 512) ; 512 kB/s (alt-speed-time-enabled? #t) (alt-speed-time-day 'weekdays) (alt-speed-time-begin (+ (* 60 8) 30)) ; 8:30 am (alt-speed-time-end (+ (* 60 (+ 12 5)) 30)))) ; 5:30 pm
Once the service is started, users can interact with the daemon through its
Web interface (at http://localhost:9091/) or by using the
transmission-remote command-line tool, available in the
transmission package. (Emacs users may want to also consider the
emacs-transmission package.) Both communicate with the daemon
through its remote procedure call (RPC) interface, which by default is
available to all users on the system; you may wish to change this by
assigning values to the rpc-authentication-required?,
rpc-username and rpc-password settings, as shown in the
example above and documented further below.
The value for rpc-password must be a password hash of the type
generated and used by Transmission clients. This can be copied verbatim
from an existing settings.json file, if another Transmission client
is already being used. Otherwise, the transmission-password-hash and
transmission-random-salt procedures provided by this module can be
used to obtain a suitable hash value.
Returns a string containing the result of hashing password together
with salt, in the format recognized by Transmission clients for their
rpc-password configuration setting.
salt must be an eight-character string. The
transmission-random-salt procedure can be used to generate a suitable
salt value at random.
Returns a string containing a random, eight-character salt value of the type
generated and used by Transmission clients, suitable for passing to the
transmission-password-hash procedure.
These procedures are accessible from within a Guile REPL started with the
guix repl command (see Invoking guix repl). This is useful
for obtaining a random salt value to provide as the second parameter to
‘transmission-password-hash‘, as in this example session:
$ guix repl scheme@(guix-user)> ,use (gnu services file-sharing) scheme@(guix-user)> (transmission-random-salt) $1 = "uKd1uMs9"
Alternatively, a complete password hash can generated in a single step:
scheme@(guix-user)> (transmission-password-hash "transmission"
(transmission-random-salt))
$2 = "{c8bbc6d1740cd8dc819a6e25563b67812c1c19c9VtFPfdsX"
The resulting string can be used as-is for the value of rpc-password,
allowing the password to be kept hidden even in the operating-system
configuration.
Torrent files downloaded by the daemon are directly accessible only to users
in the “transmission” user group, who receive read-only access to the
directory specified by the download-dir configuration setting (and
also the directory specified by incomplete-dir, if
incomplete-dir-enabled? is #t). Downloaded files can be moved
to another directory or deleted altogether using
transmission-remote with its --move and
--remove-and-delete options.
If the watch-dir-enabled? setting is set to #t, users in the
“transmission” group are able also to place .torrent files in the
directory specified by watch-dir to have the corresponding torrents
added by the daemon. (The trash-original-torrent-files? setting
controls whether the daemon deletes these files after processing them.)
Some of the daemon’s configuration settings can be changed temporarily by
transmission-remote and similar tools. To undo these changes, use
the service’s reload action to have the daemon reload its settings
from disk:
# herd reload transmission-daemon
The full set of available configuration settings is defined by the
transmission-daemon-configuration data type.
The data type representing configuration settings for Transmission Daemon. These correspond directly to the settings recognized by Transmission clients in their settings.json file.
Available transmission-daemon-configuration fields are:
transmission-daemon-configuration parameter: package transmission ¶The Transmission package to use.
transmission-daemon-configuration parameter: non-negative-integer stop-wait-period ¶The period, in seconds, to wait when stopping the service for
transmission-daemon to exit before killing its process. This
allows the daemon time to complete its housekeeping and send a final update
to trackers as it shuts down. On slow hosts, or hosts with a slow network
connection, this value may need to be increased.
Defaults to ‘10’.
transmission-daemon-configuration parameter: string download-dir ¶The directory to which torrent files are downloaded.
Defaults to ‘"/var/lib/transmission-daemon/downloads"’.
transmission-daemon-configuration parameter: boolean incomplete-dir-enabled? ¶If #t, files will be held in incomplete-dir while their
torrent is being downloaded, then moved to download-dir once the
torrent is complete. Otherwise, files for all torrents (including those
still being downloaded) will be placed in download-dir.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: maybe-string incomplete-dir ¶The directory in which files from incompletely downloaded torrents will be
held when incomplete-dir-enabled? is #t.
Defaults to ‘disabled’.
transmission-daemon-configuration parameter: umask umask ¶The file mode creation mask used for downloaded files. (See the
umask man page for more information.)
Defaults to ‘18’.
transmission-daemon-configuration parameter: boolean rename-partial-files? ¶When #t, “.part” is appended to the name of partially downloaded
files.
Defaults to ‘#t’.
transmission-daemon-configuration parameter: preallocation-mode preallocation ¶The mode by which space should be preallocated for downloaded files, one of
none, fast (or sparse) and full. Specifying
full will minimize disk fragmentation at a cost to file-creation
speed.
Defaults to ‘fast’.
transmission-daemon-configuration parameter: boolean watch-dir-enabled? ¶If #t, the directory specified by watch-dir will be watched
for new .torrent files and the torrents they describe added
automatically (and the original files removed, if
trash-original-torrent-files? is #t).
Defaults to ‘#f’.
transmission-daemon-configuration parameter: maybe-string watch-dir ¶The directory to be watched for .torrent files indicating new
torrents to be added, when watch-dir-enabled is #t.
Defaults to ‘disabled’.
transmission-daemon-configuration parameter: boolean trash-original-torrent-files? ¶When #t, .torrent files will be deleted from the watch
directory once their torrent has been added (see
watch-directory-enabled?).
Defaults to ‘#f’.
transmission-daemon-configuration parameter: boolean speed-limit-down-enabled? ¶When #t, the daemon’s download speed will be limited to the rate
specified by speed-limit-down.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: non-negative-integer speed-limit-down ¶The default global-maximum download speed, in kilobytes per second.
Defaults to ‘100’.
transmission-daemon-configuration parameter: boolean speed-limit-up-enabled? ¶When #t, the daemon’s upload speed will be limited to the rate
specified by speed-limit-up.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: non-negative-integer speed-limit-up ¶The default global-maximum upload speed, in kilobytes per second.
Defaults to ‘100’.
transmission-daemon-configuration parameter: boolean alt-speed-enabled? ¶When #t, the alternate speed limits alt-speed-down and
alt-speed-up are used (in place of speed-limit-down and
speed-limit-up, if they are enabled) to constrain the daemon’s
bandwidth usage. This can be scheduled to occur automatically at certain
times during the week; see alt-speed-time-enabled?.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: non-negative-integer alt-speed-down ¶The alternate global-maximum download speed, in kilobytes per second.
Defaults to ‘50’.
transmission-daemon-configuration parameter: non-negative-integer alt-speed-up ¶The alternate global-maximum upload speed, in kilobytes per second.
Defaults to ‘50’.
transmission-daemon-configuration parameter: boolean alt-speed-time-enabled? ¶When #t, the alternate speed limits alt-speed-down and
alt-speed-up will be enabled automatically during the periods
specified by alt-speed-time-day, alt-speed-time-begin and
alt-time-speed-end.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: day-list alt-speed-time-day ¶The days of the week on which the alternate-speed schedule should be used,
specified either as a list of days (sunday, monday, and so on)
or using one of the symbols weekdays, weekends or all.
Defaults to ‘all’.
transmission-daemon-configuration parameter: non-negative-integer alt-speed-time-begin ¶The time of day at which to enable the alternate speed limits, expressed as a number of minutes since midnight.
Defaults to ‘540’.
transmission-daemon-configuration parameter: non-negative-integer alt-speed-time-end ¶The time of day at which to disable the alternate speed limits, expressed as a number of minutes since midnight.
Defaults to ‘1020’.
transmission-daemon-configuration parameter: string bind-address-ipv4 ¶The IP address at which to listen for peer connections, or “0.0.0.0” to listen at all available IP addresses.
Defaults to ‘"0.0.0.0"’.
transmission-daemon-configuration parameter: string bind-address-ipv6 ¶The IPv6 address at which to listen for peer connections, or “::” to listen at all available IPv6 addresses.
Defaults to ‘"::"’.
transmission-daemon-configuration parameter: boolean peer-port-random-on-start? ¶If #t, when the daemon starts it will select a port at random on
which to listen for peer connections, from the range specified (inclusively)
by peer-port-random-low and peer-port-random-high. Otherwise,
it listens on the port specified by peer-port.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: port-number peer-port-random-low ¶The lowest selectable port number when peer-port-random-on-start? is
#t.
Defaults to ‘49152’.
transmission-daemon-configuration parameter: port-number peer-port-random-high ¶The highest selectable port number when peer-port-random-on-start is
#t.
Defaults to ‘65535’.
transmission-daemon-configuration parameter: port-number peer-port ¶The port on which to listen for peer connections when
peer-port-random-on-start? is #f.
Defaults to ‘51413’.
transmission-daemon-configuration parameter: boolean port-forwarding-enabled? ¶If #t, the daemon will attempt to configure port-forwarding on an
upstream gateway automatically using UPnP and NAT-PMP.
Defaults to ‘#t’.
transmission-daemon-configuration parameter: encryption-mode encryption ¶The encryption preference for peer connections, one of
prefer-unencrypted-connections, prefer-encrypted-connections
or require-encrypted-connections.
Defaults to ‘prefer-encrypted-connections’.
transmission-daemon-configuration parameter: maybe-string peer-congestion-algorithm ¶The TCP congestion-control algorithm to use for peer connections, specified
using a string recognized by the operating system in calls to
setsockopt. When left unspecified, the operating-system default is
used.
Note that on GNU/Linux systems, the kernel must be configured to allow processes to use a congestion-control algorithm not in the default set; otherwise, it will deny these requests with “Operation not permitted”. To see which algorithms are available on your system and which are currently permitted for use, look at the contents of the files tcp_available_congestion_control and tcp_allowed_congestion_control in the /proc/sys/net/ipv4 directory.
As an example, to have Transmission Daemon use
the TCP Low Priority
congestion-control algorithm, you’ll need to modify your kernel
configuration to build in support for the algorithm, then update your
operating-system configuration to allow its use by adding a
sysctl-service-type service (or updating the existing one’s
configuration) with lines like the following:
(service sysctl-service-type
(sysctl-configuration
(settings
("net.ipv4.tcp_allowed_congestion_control" .
"reno cubic lp"))))
The Transmission Daemon configuration can then be updated with
(peer-congestion-algorithm "lp")
and the system reconfigured to have the changes take effect.
Defaults to ‘disabled’.
transmission-daemon-configuration parameter: tcp-type-of-service peer-socket-tos ¶The type of service to request in outgoing TCP packets, one of
default, low-cost, throughput, low-delay and
reliability.
Defaults to ‘default’.
transmission-daemon-configuration parameter: non-negative-integer peer-limit-global ¶The global limit on the number of connected peers.
Defaults to ‘200’.
transmission-daemon-configuration parameter: non-negative-integer peer-limit-per-torrent ¶The per-torrent limit on the number of connected peers.
Defaults to ‘50’.
transmission-daemon-configuration parameter: non-negative-integer upload-slots-per-torrent ¶The maximum number of peers to which the daemon will upload data simultaneously for each torrent.
Defaults to ‘14’.
transmission-daemon-configuration parameter: non-negative-integer peer-id-ttl-hours ¶The maximum lifespan, in hours, of the peer ID associated with each public torrent before it is regenerated.
Defaults to ‘6’.
transmission-daemon-configuration parameter: boolean blocklist-enabled? ¶When #t, the daemon will ignore peers mentioned in the blocklist it
has most recently downloaded from blocklist-url.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: maybe-string blocklist-url ¶The URL of a peer blocklist (in P2P-plaintext or eMule .dat
format) to be periodically downloaded and applied when
blocklist-enabled? is #t.
Defaults to ‘disabled’.
transmission-daemon-configuration parameter: boolean download-queue-enabled? ¶If #t, the daemon will be limited to downloading at most
download-queue-size non-stalled torrents simultaneously.
Defaults to ‘#t’.
transmission-daemon-configuration parameter: non-negative-integer download-queue-size ¶The size of the daemon’s download queue, which limits the number of
non-stalled torrents it will download at any one time when
download-queue-enabled? is #t.
Defaults to ‘5’.
transmission-daemon-configuration parameter: boolean seed-queue-enabled? ¶If #t, the daemon will be limited to seeding at most
seed-queue-size non-stalled torrents simultaneously.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: non-negative-integer seed-queue-size ¶The size of the daemon’s seed queue, which limits the number of non-stalled
torrents it will seed at any one time when seed-queue-enabled? is
#t.
Defaults to ‘10’.
transmission-daemon-configuration parameter: boolean queue-stalled-enabled? ¶When #t, the daemon will consider torrents for which it has not
shared data in the past queue-stalled-minutes minutes to be stalled
and not count them against its download-queue-size and
seed-queue-size limits.
Defaults to ‘#t’.
transmission-daemon-configuration parameter: non-negative-integer queue-stalled-minutes ¶The maximum period, in minutes, a torrent may be idle before it is
considered to be stalled, when queue-stalled-enabled? is #t.
Defaults to ‘30’.
transmission-daemon-configuration parameter: boolean ratio-limit-enabled? ¶When #t, a torrent being seeded will automatically be paused once it
reaches the ratio specified by ratio-limit.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: non-negative-rational ratio-limit ¶The ratio at which a torrent being seeded will be paused, when
ratio-limit-enabled? is #t.
Defaults to ‘2.0’.
transmission-daemon-configuration parameter: boolean idle-seeding-limit-enabled? ¶When #t, a torrent being seeded will automatically be paused once it
has been idle for idle-seeding-limit minutes.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: non-negative-integer idle-seeding-limit ¶The maximum period, in minutes, a torrent being seeded may be idle before it
is paused, when idle-seeding-limit-enabled? is #t.
Defaults to ‘30’.
transmission-daemon-configuration parameter: boolean dht-enabled? ¶Enable the distributed hash table (DHT) protocol, which supports the use of trackerless torrents.
Defaults to ‘#t’.
transmission-daemon-configuration parameter: boolean lpd-enabled? ¶Enable local peer discovery (LPD), which allows the discovery of peers on the local network and may reduce the amount of data sent over the public Internet.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: boolean pex-enabled? ¶Enable peer exchange (PEX), which reduces the daemon’s reliance on external trackers and may improve its performance.
Defaults to ‘#t’.
transmission-daemon-configuration parameter: boolean utp-enabled? ¶Enable the micro transport protocol (uTP), which aims to reduce the impact of BitTorrent traffic on other users of the local network while maintaining full utilization of the available bandwidth.
Defaults to ‘#t’.
transmission-daemon-configuration parameter: boolean rpc-enabled? ¶If #t, enable the remote procedure call (RPC) interface,
which allows remote control of the daemon via its Web interface, the
transmission-remote command-line client, and similar tools.
Defaults to ‘#t’.
transmission-daemon-configuration parameter: string rpc-bind-address ¶The IP address at which to listen for RPC connections, or “0.0.0.0” to listen at all available IP addresses.
Defaults to ‘"0.0.0.0"’.
transmission-daemon-configuration parameter: port-number rpc-port ¶The port on which to listen for RPC connections.
Defaults to ‘9091’.
transmission-daemon-configuration parameter: string rpc-url ¶The path prefix to use in the RPC-endpoint URL.
Defaults to ‘"/transmission/"’.
transmission-daemon-configuration parameter: boolean rpc-authentication-required? ¶When #t, clients must authenticate (see rpc-username and
rpc-password) when using the RPC interface. Note this has
the side effect of disabling host-name whitelisting (see
rpc-host-whitelist-enabled?.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: maybe-string rpc-username ¶The username required by clients to access the RPC interface when
rpc-authentication-required? is #t.
Defaults to ‘disabled’.
transmission-daemon-configuration parameter: maybe-transmission-password-hash rpc-password ¶The password required by clients to access the RPC interface when
rpc-authentication-required? is #t. This must be specified
using a password hash in the format recognized by Transmission clients,
either copied from an existing settings.json file or generated using
the transmission-password-hash procedure.
Defaults to ‘disabled’.
transmission-daemon-configuration parameter: boolean rpc-whitelist-enabled? ¶When #t, RPC requests will be accepted only when they
originate from an address specified in rpc-whitelist.
Defaults to ‘#t’.
transmission-daemon-configuration parameter: string-list rpc-whitelist ¶The list of IP and IPv6 addresses from which RPC requests will be
accepted when rpc-whitelist-enabled? is #t. Wildcards may be
specified using ‘*’.
Defaults to ‘("127.0.0.1" "::1")’.
transmission-daemon-configuration parameter: boolean rpc-host-whitelist-enabled? ¶When #t, RPC requests will be accepted only when they are
addressed to a host named in rpc-host-whitelist. Note that requests
to “localhost” or “localhost.”, or to a numeric address, are always
accepted regardless of these settings.
Note also this functionality is disabled when
rpc-authentication-required? is #t.
Defaults to ‘#t’.
transmission-daemon-configuration parameter: string-list rpc-host-whitelist ¶The list of host names recognized by the RPC server when
rpc-host-whitelist-enabled? is #t.
Defaults to ‘()’.
transmission-daemon-configuration parameter: message-level message-level ¶The minimum severity level of messages to be logged (to
/var/log/transmission.log) by the daemon, one of none (no
logging), error, info and debug.
Defaults to ‘info’.
transmission-daemon-configuration parameter: boolean start-added-torrents? ¶When #t, torrents are started as soon as they are added; otherwise,
they are added in “paused” state.
Defaults to ‘#t’.
transmission-daemon-configuration parameter: boolean script-torrent-done-enabled? ¶When #t, the script specified by script-torrent-done-filename
will be invoked each time a torrent completes.
Defaults to ‘#f’.
transmission-daemon-configuration parameter: maybe-file-object script-torrent-done-filename ¶A file name or file-like object specifying a script to run each time a
torrent completes, when script-torrent-done-enabled? is #t.
Defaults to ‘disabled’.
transmission-daemon-configuration parameter: boolean scrape-paused-torrents-enabled? ¶When #t, the daemon will scrape trackers for a torrent even when the
torrent is paused.
Defaults to ‘#t’.
transmission-daemon-configuration parameter: non-negative-integer cache-size-mb ¶The amount of memory, in megabytes, to allocate for the daemon’s in-memory cache. A larger value may increase performance by reducing the frequency of disk I/O.
Defaults to ‘4’.
transmission-daemon-configuration parameter: boolean prefetch-enabled? ¶When #t, the daemon will try to improve I/O performance by hinting to
the operating system which data is likely to be read next from disk to
satisfy requests from peers.
Defaults to ‘#t’.