#Torrentmap

Torrentmap is a CLI tool used to generate a world heatmap of torrent popularity.

It maintains an internal database of known torrents and known peers , which is then used to geolocate the peers and draw a colored map of the world.

#Installation

To install trmp into currently active Python environment run pip install . in the project root.

For development use Poetry with poetry install.

#Usage

usage: trmp [-h] [-d DIR] [-ll LOGLEVEL] [-lf LOGFILE] {list,update,add,remove,map} ...

Torrent mapping utility.

Analyzes popularity of known torrents by country/genre.

positional arguments:
  {list,update,add,remove,map}

options:
  -h, --help            show this help message and exit
  -d DIR, --dir DIR     Path to working directory (default ~/.local/share/trmp)
  -ll LOGLEVEL, --loglevel LOGLEVEL
                        Logging vebosity (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  -lf LOGFILE, --logfile LOGFILE
                        Log file (defaul /dev/stderr)

In order to add *.torrent files to storage directory run trmp add:

usage: trmp add [-h] FILE [FILE ...]

Add new torrent files to the database. Note that peers will only be obtained after an
update is issued.

positional arguments:
  FILE        Torrent file(s) to add to the database

  options:
    -h, --help  show this help message and exit

Once the torrents are added their summary will be printed to standard output. Note that no peers will be shown at this point - run trmp update to announce to trackers and get peers.

usage: trmp update [-h] [-g] [HASH ...]

Update torrent peer list and geolocate unknown peers. This command
requires network connectivity.

positional arguments:
  HASH             Torrent infohash(es) to update (default all)

options:
  -h, --help       show this help message and exit
  -g, --geolocate  Do not ask for new peers, only geolocate existing ones.

View the torrent details, including peers, with trmp list. It uses JSON as output format and can be easily saved to a file.

usage: trmp list [-h] [-p] [-t] [HASH ...]

List known torrents in a JSON format. By default all torrents and all
peers are listed - use appropriate switches to list only peers or torrents
without peers.

positional arguments:
  HASH            Torrent infohash(es) to use when listing (default all)

options:
  -h, --help      show this help message and exit
  -p, --peers     List only peers, without torrents
  -t, --torrents  List only torrents, without peers

At any point you may remove one of the torrents with trmp remove

usage: trmp remove [-h] HASH [HASH ...]

Remove torrents with given hashes. This may or may not be equivalent to
removing infohash files from the working directory. All associated peers
will be fogotten, unless they participate in another known torrent.

positional arguments:
  HASH        Torrent infohash(es) to remove from the database ('ALL' to
              remove all)

options:
  -h, --help  show this help message and exit

To visualize the peer distribution use trmp map. By default the generated map will be saved to a PDF file in $PWD.

usage: trmp map [-h] [-f FILENAME] [-t] [HASH ...]

Draw the heatmap of known torrents using GeoPandas.

positional arguments:
  HASH                  Torrent infohash(es) to map (default all)

options:
  -h, --help            show this help message and exit
  -f FILENAME, --filename FILENAME
                        Map file name override (default 'map-{ISO
                        datetime}.pdf'
  -t, --torrents        Annotate the map with a list of used torrents.

See below for an example map, generated with some popular Linux ISO torrents.

#Feature wishlist

• [x] CLI interface
• [x] obtaining IPs from HTTP trackers
• [x] obtaining IPs from UDP trackers
• [x] geolocating IPs
• [x] generating a map of torrent popularity
• [ ] sane error handling

#Author

Copyright 2023 Piotr Machura

Source code repository: https://git.sr.ht/~piotr-machura/torrentmap

Distributed under GNU General Public License version 2.