README.md

   1 # torrent
   2
   3 [![Join the chat at https://gitter.im/anacrolix/torrent](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/anacrolix/torrent?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
   4 [![GoDoc](https://godoc.org/github.com/anacrolix/torrent?status.svg)](https://godoc.org/github.com/anacrolix/torrent)
   5
   6 This repository implements BitTorrent-related packages and command-line utilities in Go. The emphasis is on use as a library from other projects. It's been used 24/7 in production by a downstream, private service since late 2014.
   7
   8 There is support for protocol encryption, [DHT](https://github.com/anacrolix/dht), PEX, [uTP](https://github.com/anacrolix/utp), and various extensions. See the package documentation for a more complete list. There are several data storage backends provided: blob, file, and mmap, and you can write your own, such as to store data on S3, or in a database. You can use the provided binaries in `./cmd`, or use `torrent` as a library for your own applications.
   9
  10 Many of the sub-packages can be used for other purposes: [bencode](https://godoc.org/github.com/anacrolix/torrent/bencode), and [tracker](https://godoc.org/github.com/anacrolix/torrent/tracker), in particular.
  11
  12 ## Installation
  13
  14 Install the library package with `go get github.com/anacrolix/torrent`, or the provided cmds with `go get github.com/anacrolix/torrent/cmd/...`.
  15
  16 ## Library example
  17
  18 There is a small example in the [package documentation](https://godoc.org/github.com/anacrolix/torrent).
  19
  20 ## Other public projects using torrent
  21
  22  * [Go Peerflix](https://github.com/Sioro-Neoku/go-peerflix)
  23  * [Cloud Torrent](https://github.com/jpillora/cloud-torrent)
  24  * [Android Torrent Client](https://gitlab.com/axet/android-torrent-client)
  25  * [Android libtorrent](https://gitlab.com/axet/libtorrent)
  26  * [Trickl - Torrent Client](https://play.google.com/store/apps/details?id=com.shwifty.tex)
  27  * [Confluence](https://github.com/anacrolix/confluence)
  28
  29 ## Mobile
  30
  31 There's a branch called `mobile` that supports binding to torrent with the [gomobile](https://github.com/golang/go/wiki/Mobile) tool. It has some API changes as required by `gomobile`. Checkout the [`mobile` branch](https://github.com/anacrolix/torrent/tree/mobile), and bind as usual.
  32
  33 ## Commands
  34
  35 Here I'll describe what some of the provided commands in `./cmd` do.
  36
  37 Note that the [`godo`](https://github.com/anacrolix/godo) command which is invoked in the following examples builds and executes a Go import path, like `go run`. It's easier to use this convention than to spell out the install/invoke cycle for every single example.
  38
  39 ### torrent
  40
  41 Downloads torrents from the command-line. This first example does not use `godo`.
  42
  43         $ go get github.com/anacrolix/torrent/cmd/torrent
  44     # Now 'torrent' should be in $GOPATH/bin, which should be in $PATH.
  45         $ torrent 'magnet:?xt=urn:btih:KRWPCX3SJUM4IMM4YF5RPHL6ANPYTQPU'
  46     ubuntu-14.04.2-desktop-amd64.iso [===================================================================>]  99% downloading (1.0 GB/1.0 GB)
  47     2015/04/01 02:08:20 main.go:137: downloaded ALL the torrents
  48     $ md5sum ubuntu-14.04.2-desktop-amd64.iso
  49     1b305d585b1918f297164add46784116  ubuntu-14.04.2-desktop-amd64.iso
  50     $ echo such amaze
  51     wow
  52
  53 ### torrentfs
  54
  55 torrentfs mounts a FUSE filesystem at `-mountDir`. The contents are the torrents described by the torrent files and magnet links at `-torrentPath`. Data for read requests is fetched only as required from the torrent network, and stored at `-downloadDir`.
  56
  57     $ mkdir mnt torrents
  58     $ godo github.com/anacrolix/torrent/cmd/torrentfs -mountDir mnt -torrentPath torrents &
  59     $ cd torrents
  60     $ wget http://releases.ubuntu.com/14.04.2/ubuntu-14.04.2-desktop-amd64.iso.torrent
  61     $ cd ..
  62     $ ls mnt
  63     ubuntu-14.04.2-desktop-amd64.iso
  64     $ pv mnt/ubuntu-14.04.2-desktop-amd64.iso | md5sum
  65     996MB 0:04:40 [3.55MB/s] [========================================>] 100%
  66     1b305d585b1918f297164add46784116  -
  67
  68 ### torrent-magnet
  69
  70 Creates a magnet link from a torrent file. Note the extracted trackers, display name, and info hash.
  71
  72     $ godo github.com/anacrolix/torrent/cmd/torrent-magnet < ubuntu-14.04.2-desktop-amd64.iso.torrent
  73         magnet:?xt=urn:btih:546cf15f724d19c4319cc17b179d7e035f89c1f4&dn=ubuntu-14.04.2-desktop-amd64.iso&tr=http%3A%2F%2Ftorrent.ubuntu.com%3A6969%2Fannounce&tr=http%3A%2F%2Fipv6.torrent.ubuntu.com%3A6969%2Fannounce
  74
  75 ### dht-ping
  76
  77 Pings DHT nodes with the given network addresses.
  78
  79     $ godo ./cmd/dht-ping router.bittorrent.com:6881 router.utorrent.com:6881
  80     2015/04/01 17:21:23 main.go:33: dht server on [::]:60058
  81     32f54e697351ff4aec29cdbaabf2fbe3467cc267 (router.bittorrent.com:6881): 648.218621ms
  82     ebff36697351ff4aec29cdbaabf2fbe3467cc267 (router.utorrent.com:6881): 873.864706ms
  83     2/2 responses (100.000000%)
  84