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 [![CircleCI](https://circleci.com/gh/anacrolix/torrent.svg?style=shield)](https://circleci.com/gh/anacrolix/torrent)
   6 [![Astronomer Rating](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fastronomer.ullaakut.eu%2Fshields%3Fowner%3Danacrolix%26name%3Dtorrent)](https://github.com/ullaakut/astronomer)
   7 [![GitHub Release](https://img.shields.io/github/release/anacrolix/torrent.svg)](https://github.com/anacrolix/torrent/releases)
   8 [![PkgGoDev](https://pkg.go.dev/badge/github.com/anacrolix/torrent)](https://pkg.go.dev/github.com/anacrolix/torrent)
   9
  10 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 downstream services since late 2014. The implementation was specifically created to explore Go's concurrency capabilities, and to include the ability to stream data directly from the BitTorrent network. To this end it [supports seeking, readaheads and other features](https://godoc.org/github.com/anacrolix/torrent#Reader) exposing torrents and their files with the various Go idiomatic `io` package interfaces. This is also demonstrated through [torrentfs](#torrentfs).
  11
  12 There is [support for protocol encryption, DHT, PEX, uTP, and various extensions](https://godoc.org/github.com/anacrolix/torrent). There are [several data storage backends provided](https://godoc.org/github.com/anacrolix/torrent/storage): blob, file, bolt, mmap, and sqlite, to name a few. You can [write your own](https://godoc.org/github.com/anacrolix/torrent/storage#ClientImpl) to store data for example on S3, or in a database.
  13
  14 Some noteworthy package dependencies that can be used for other purposes include:
  15
  16  * [go-libutp](https://github.com/anacrolix/go-libutp)
  17  * [dht](https://github.com/anacrolix/dht)
  18  * [bencode](https://godoc.org/github.com/anacrolix/torrent/bencode)
  19  * [tracker](https://godoc.org/github.com/anacrolix/torrent/tracker)
  20
  21 ## Installation
  22
  23 Install the library package with `go get github.com/anacrolix/torrent`, or the provided cmds with `go get github.com/anacrolix/torrent/cmd/...`.
  24
  25 ## Library examples
  26
  27 There are some small [examples](https://godoc.org/github.com/anacrolix/torrent#pkg-examples) in the package documentation.
  28
  29 ## Downstream projects
  30
  31 There are several web-frontends and Android clients among the known public projects:
  32
  33  * [Torrent.Express](https://torrent.express/)
  34  * [Confluence](https://github.com/anacrolix/confluence)
  35  * [Trickl](https://github.com/arranlomas/Trickl)
  36  * [Elementum](http://elementum.surge.sh/)
  37  * [goTorrent](https://github.com/deranjer/goTorrent)
  38  * [Go Peerflix](https://github.com/Sioro-Neoku/go-peerflix)
  39  * [Cloud Torrent](https://github.com/jpillora/cloud-torrent)
  40  * [Android Torrent Client](https://gitlab.com/axet/android-torrent-client)
  41  * [libtorrent](https://gitlab.com/axet/libtorrent)
  42  * [Remote-Torrent](https://github.com/BruceWangNo1/remote-torrent)
  43  * [ANT-Downloader](https://github.com/anatasluo/ant)
  44  * [Go-PeersToHTTP](https://github.com/WinPooh32/peerstohttp)
  45  * [CortexFoundation/torrentfs](https://github.com/CortexFoundation/torrentfs): P2P file system of cortex full node
  46
  47 ## Help
  48
  49 Communication about the project is primarily through [Gitter](https://gitter.im/anacrolix/torrent) and the [issue tracker](https://github.com/anacrolix/torrent/issues).
  50
  51 ## Command packages
  52
  53 Here I'll describe what some of the packages in `./cmd` do.
  54
  55 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.
  56
  57 ### torrent
  58
  59 Downloads torrents from the command-line. This first example does not use `godo`.
  60
  61     $ go get github.com/anacrolix/torrent/cmd/torrent
  62     # Now 'torrent' should be in $GOPATH/bin, which should be in $PATH.
  63     $ torrent download 'magnet:?xt=urn:btih:KRWPCX3SJUM4IMM4YF5RPHL6ANPYTQPU'
  64     ubuntu-14.04.2-desktop-amd64.iso [===================================================================>]  99% downloading (1.0 GB/1.0 GB)
  65     2015/04/01 02:08:20 main.go:137: downloaded ALL the torrents
  66     $ md5sum ubuntu-14.04.2-desktop-amd64.iso
  67     1b305d585b1918f297164add46784116  ubuntu-14.04.2-desktop-amd64.iso
  68     $ echo such amaze
  69     wow
  70
  71 ### torrentfs
  72
  73 torrentfs mounts a FUSE filesystem at `-mountDir`. The contents are the torrents described by the torrent files and magnet links at `-metainfoDir`. Data for read requests is fetched only as required from the torrent network, and stored at `-downloadDir`.
  74
  75     $ mkdir mnt torrents
  76     $ godo github.com/anacrolix/torrent/cmd/torrentfs -mountDir=mnt -metainfoDir=torrents &
  77     $ cd torrents
  78     $ wget http://releases.ubuntu.com/14.04.2/ubuntu-14.04.2-desktop-amd64.iso.torrent
  79     $ cd ..
  80     $ ls mnt
  81     ubuntu-14.04.2-desktop-amd64.iso
  82     $ pv mnt/ubuntu-14.04.2-desktop-amd64.iso | md5sum
  83     996MB 0:04:40 [3.55MB/s] [========================================>] 100%
  84     1b305d585b1918f297164add46784116  -
  85
  86 ### torrent-magnet
  87
  88 Creates a magnet link from a torrent file. Note the extracted trackers, display name, and info hash.
  89
  90     $ godo github.com/anacrolix/torrent/cmd/torrent-magnet < ubuntu-14.04.2-desktop-amd64.iso.torrent
  91     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