From 214d670fd7a583dd99e5aab5a3f9eec53bc239d6 Mon Sep 17 00:00:00 2001
From: Sergey Matveev <stargrave@stargrave.org>
Date: Sun, 27 Nov 2022 15:25:41 +0300
Subject: [PATCH] Basic documentation

---
 README            |  1 +
 cmd/btrtrc/README | 38 ++++++++++++++-----------
 cmd/btrtrc/USAGE  | 72 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 94 insertions(+), 17 deletions(-)
 create mode 120000 README
 create mode 100644 cmd/btrtrc/USAGE

diff --git a/README b/README
new file mode 120000
index 00000000..a4787965
--- /dev/null
+++ b/README
@@ -0,0 +1 @@
+cmd/btrtrc/README
\ No newline at end of file
diff --git a/cmd/btrtrc/README b/cmd/btrtrc/README
index a10226bf..89c20ad8 100644
--- a/cmd/btrtrc/README
+++ b/cmd/btrtrc/README
@@ -1,18 +1,22 @@
-Peer's status string:
+btrtrc -- better BitTorrent client
 
-* i -- am interested
-* c -- am chocking
-* -
-* E -- RC4 encryption
-* e -- header encryption
-* discovery source:
-  * Tr -- tracker
-  * I  -- incoming
-  * Hg -- DHT get_peers
-  * Ha -- DHT announce_peer
-  * X  -- PEX
-  * M  -- direct (through magnet:)
-* U -- UTP
-* -
-* i -- he interested
-* c -- he chocking
+This is a fork of https://github.com/anacrolix/torrent BitTorrent
+library with own cmd/btrtrc client implementation. Comparing to
+cmd/torrent it has much less configuration options, mainly hardcoding
+the most of them. Also it lacks various features like ability to select
+the file to delete. But what advantages does it have?
+
+* Ability to specify both IPv4 and IPv6 addresses to announce
+* Ability to specify DHT bootstrap nodes
+* Dynamic addition and removing of the torrents
+* Much richer and nicer coloured status output
+* Ability to calculate seed ratio, by remembering outgoing traffic amount
+* Simpler piece completion database per each torrent in separate files
+* Ability to sequentially create/verify torrent's piece completion database
+* Optional commit disables any WebTorrent/WebRTC/WebSocket usage,
+  because those technologies suck
+
+Look at USAGE file further.
+
+btrtrc is free software: see the file LICENSE in the root of the
+repository for copying conditions.
diff --git a/cmd/btrtrc/USAGE b/cmd/btrtrc/USAGE
new file mode 100644
index 00000000..eec41551
--- /dev/null
+++ b/cmd/btrtrc/USAGE
@@ -0,0 +1,72 @@
+You have to specify correct -bind, -4 and -6 addresses. If -4/-6 is
+empty, then it won't be announced.
+
+Each second the current time, overall downloaded/uploaded traffic
+amount, number of active peers and current download/upload speed in
+KiB/sec will be shown.
+
+fifos subdirectory will be created with following FIFO files:
+
+* fifos/add -- expects newline delimited paths to .torrent files or
+  magnet: links
+* fifos/del -- expects torrent's info hashes to remove torrents from the
+  client
+* fifos/list -- prints coloured output of all registered torrents in the
+  client. It shows:
+  * info hash (that you can use in all other FIFOs)
+  * name (name of the file or root directory as a rule)
+  * total size
+  * completion percentage
+  * seed ratio
+  * download/upload speeds in KiB/sec
+  * number of: total/pending/active/seeder peers
+  * (optionally) estimated completion time
+* fifos/dht -- prints DHT server statistics
+* fifos/files/HASH -- prints torrent's file list with completion ratio
+* fifos/peers/HASH -- prints torrent's connected peers information:
+  * peer's ID
+  * status flags, that are concatenated string of:
+    i -- am interested
+    c -- am chocking
+      -
+    E -- RC4 encryption
+    e -- header encryption
+      Tr -- tracker
+      I  -- incoming
+      Hg -- DHT get_peers
+      Ha -- DHT announce_peer
+      X  -- PEX
+      M  -- direct (through magnet:)
+    U -- UTP
+      -
+    i -- he interested
+    c -- he chocking
+  * number of completed pieces
+  * download/upload speeds in KiB/sec during current session
+  * amount of downloaded/uploaded traffic during current session
+  * remote address with port
+  * client's name
+
+For each torrent, corresponding HASH.torrent file will be created.
+Additional symbolic link with torrent's name will lead to HASH.torrent.
+HASH.bf file is piece completion database. HASH.tx contains overall
+outgoing payload traffic amount and it is updated each 10sec.
+
+If you massively add a bunch of unverified torrents, then
+github.com/anacrolix/torrent will deal with them in parallel. That means
+hash verification is done in random order from HDD's point of view, that
+is rather slow. If you are going to seed many torrents, then it is
+highly advisable to pre-verify them in advance, by using -verify option
+with path to all .torrent files.
+
+Example usage for starting torrents seeding:
+
+    $ cat > seedfile <<EOF
+    big_buck_bunny.torrent
+    exodos.torrent
+    [...]
+    EOF
+    $ btrtrc -verify `cat seedfile`
+    $ btrtrc [...]
+    $ cat seedfile > fifos/add
+    $ cat fifos/list
-- 
2.48.1