Configuration

Configuration files

There are two places for configuration: one that is system-wide were the default configuration is stored, and one that is specific for the current user.

On linux : * system location: /etc * user location: $XDG_CONFIG_HOME/torrenttools (defaults to: $HOME/.config/torrenttools)

On macOS: * system location: /Library/torrenttools/etc/ * user location: $HOME/Library/Application Support/torrenttools/

On windows: * system location: inside the install prefix (defaults to: C:Program Filestorrenttools) * user location: %APPDATA%torrenttools (defaults to: C:Users{username}AppDataRoamingtorrenttools)==

If there are files found in the user location these will be used first. Only if there is no user configuration, the files in the system location will be used. The files found in the system location will then be copied to the user location.

This behavior ensures that global configuration default are updates with new packages/installers and that user-local configuration persists between installations.

Named trackers

“Named trackers” are trackers which are declared in the trackers.json configuration file.

Announce url substitution

When a tracker is defined in the trackers.json file you can specify the full name or abbreviation to the -a|--announce option in the create or edit command. The tracker name will be replaced by the announce url in the BitTorrent metafile. Some private trackers have unique identifiers per user in the tracker announce url. These are supported as well by defining announce-url parameters between curly brackets in the announce-url. The announce-url parameter will be replaced by the value defined in the config.yml configuration file.

Declaration of a private tracker with parameter pid in trackers.json.

{
    "name": "PrivateTracker",
    "abbreviation": "PT",
    "announce_url": "http://private-tracker.org:8600/{pid}/announce",
    "private": true
  }

Definition of the pid parameter in config.yml

tracker-parameters:
  PrivateTracker:
    pid: 01qwqwdlc922_sample_pid_d93fqd6fji9

Private flag selection

When passing the full name or abbreviation to the -a|--announce parameter, the private flag will be set according to the value specified in the tracker database. The user can always override this value by explicitly passing a different value to the -p|-private option.

Source field

When passing the full name or abbreviation to the -a|--announce parameter, the source field will be set to the full name of the tracker if the tracker is marked as a private tracker. The source tag can be overridden on the commandline or removed by passing the -s|--source|-s option with an empty string.

BitTorrent metafile default filename

Named trackers will prefix the abbreviation between square brackets to the default filename of the generated BitTorrent metafile. For a tracker named PrivateTracker and abbreviation PT the default filename for a target directory “content” would be: [PT]example.torrent.

Tracker groups

A tracker group is an alias that refers to a group of trackers. Instead of having to pass each tracker on the commandline, the name of the alias can be used to add all trackers in the group to a BitTorrent metafile.

Definition of “public-trackers” tracker group containing three trackers.

tracker-groups:
  public-trackers:
    - http://tracker.opentrackr.org:1337/announce
    - udp://tracker.openbittorrent.com:6969/announce
    - udp://exodus.desync.com:6969/announce

Named trackers can be used inside the definition of the tracker group. A list with 20 public trackers named “public-trackers” is included in the default configuration file.

Profiles

Profiles are a way to store a set of commandline options in the configuration file and apply them using a single commandline argument.

Profiles are defined under the profiles key.

Following options can be used for create profiles:

announce announce-group checksum collection comment created-by creation-date dht-node

exclude http-seed include include-hidden io-block-size name output piece-size

private protocol set-created-by set-creation-date similar source threads web-sees

Following options can be used for edit profiles:

announce announce-group collection comment created-by creation-date

dht-node http-seed list-mode name output private

set-created-by set-creation-date similar source web-seed

For the behaviour of each flag we refer to the documentation on the commandline arguments for the respective subcommand.

Schema for a profile.

profiles:
    <profile_name>:
        command: [create|edit]
        options:
            <option> : <value>
            ...

Example of a profile for the create command.

profiles:
  public:
    command: "create"
    options:
      announce-group: [ public-trackers ]
      private: false
      protocol: 1