CW Cyrix's Git Repository Mirror
Browse code

Import from the old rivettracker git repository at sourceforge (amisaph/amisapphire branch)

Clarissa Walker (ami-sapphire) authored on 2014/01/24 14:02:23
Showing 1 changed files
docs/old_phpbttracker_readme.txt
History View file @ 1c8ad06
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,252 @@
1 
+Welcome to my BitTorrent Tracker written in PHP.
2 
+
3 
+Highlights:
4 
++ Provides the same functionality as the offical tracker
5 
++ Runs using MySQL as a database backend
6 
++ Built-in statistics collection with sample summary script
7 
++ Customiztion is pretty easy to implement
8 
+
9 
+Pitfalls
10 
+- PHP has some limitations, so this tracker is not optimal.
11 
+
12 
+This is my first PHP project, and I'm rather happy with the
13 
+result.
14 
+
15 
+UPGRADING
16 
+---------
17 
+
18 
+If you are upgrading from a previous version, then you may be in trouble.
19 
+The database structure was slightly modified to accomidate a change in the
20 
+latest MySQL. The word "hash" became a keyword, and cannot be used as a
21 
+column name. Furthermore, the addition of the "speed" code requires
22 
+table additions and a new table entirely.
23 
+
24 
+The script upgrade.php is provided to carry out these modifications. You do
25 
+not need to run it if you are installing from scratch, and if only needs
26 
+to be done once regardless. Also, running it will not cause any problems
27 
+even if you have the latest version of the database.
28 
+
29 
+
30 
+** New in version 1.5: Peer caching. If you want to use this feature,
31 
+you must execute the makecache.php script to generate the tables from
32 
+your current database.
33 
+
34 
+
35 
+INSTALLATION
36 
+------------
37 
+
38 
+Requirements:
39 
+- Working PHP environment (ideally Apache with PHP built-in or
40 
+  working via module)
41 
+- Working MySQL server
42 
+
43 
+
44 
+Upload tracker.php, funcsv2.php, newtorrents.php, BDecode.php, BEncode.php
45 
+ and install.php to the web site which will be hosting the tracker. Uploading
46 
+index.php is recommended if you want a home page for the tracker. Feel free
47 
+to re-theme it.
48 
+
49 
+Access the install.php script from your web browser. It will
50 
+guide you through the creation of the SQL database. All you need
51 
+is the database's username and password. You may want to let your
52 
+webmaster run through this phase.
53 
+
54 
+If install.php has write access to the installation directory, it will
55 
+write its own config.php file with the database configuration and some
56 
+default settings. If install.php cannot do this, you must modify
57 
+config-sample.php yourself and upload it to the same directory as
58 
+tracker.php and rename it to config.php.
59 
+
60 
+*************************
61 
+************************* Set up config.php !!!
62 
+
63 
+There are two variables named $upload_username and $upload_password.
64 
+These are the values that will be used by the newtorrents.php script
65 
+to authorize submission of new torrents. You must set these, or your
66 
+tracker will not accept new files, making it rather useless.
67 
+
68 
+
69 
+
70 
+OTHER FILES
71 
+-----------
72 
+
73 
+The tracker package also includes some other scripts. Here is a list and a
74 
+description of what they do.
75 
+
76 
+- DumpTorrentCGI.php
77 
+ Originally intended as a demo of the BEncode library, but it became popular
78 
+ pretty quickly. This script allows users to upload a .torrent file to the
79 
+ server (or specify a URL to download) and the script will decode it and
80 
+ display the file's contents to the user in a (hopefully) friendly manner.
81 
+ It also supports other bencoded data, such as /announce and /scrape data,
82 
+ although it is not reliable enough to do /scrape due to a strange quirk
83 
+ in PHP.
84 
+- BEncode.php
85 
+ Used by DumpTorrentCGI.php and newtorrents.php to make bencoded data
86 
+ streams. The primary reason for doing this is calculating info_hash values.
87 
+- BDecode.php
88 
+ The decoding compliment to BEncode.php
89 
+- sanity.php
90 
+ When run, this script will do some simple consistency checks on the
91 
+ tracker's summary page and will forcibly expire peers who have not reported
92 
+ in within double the configured re-announce interval. If it doesn't seem to
93 
+ work, try running it as sanity.php?nolock=on
94 
+- sha1lib.php
95 
+ An SHA1 implementation entirely in PHP. It's not perfect and it's slow, but
96 
+ in a pinch, it works fine. Ignored if PHP version is at least 4.3.0 or if
97 
+ the mhash extension is installed.
98 
+
99 
+
100 
+The rest is documentation and other text documents.
101 
+
102 
+FILE RENAMING AND MOVING
103 
+------------------------
104 
+All PHP files will function properly if renamed, except
105 
+funcsv2.php and config.php. Renaming these files require
106 
+modifying most other .php files.
107 
+
108 
+
109 
+USAGE
110 
+-----
111 
+Create your torrent files as usual. Specify the url to
112 
+tracker.php (or its new name if you renamed it) as the announce
113 
+URL.
114 
+
115 
+***********************************
116 
+If you want /scrape functionality, target announce.php
117 
+instead of tracker.php.
118 
+***********************************
119 
+
120 
+Call up the newtorrents.php URL. Specify all the data you want to
121 
+show up on the statistics page. You must specify at least the
122 
+username, password, and either upload the .torrent or copy the
123 
+info_hash into the indicated field.
124 
+
125 
+The checkbox, when checked (defaults to yes) will cause the script
126 
+to fill in the file's name and a short description. The description is
127 
+the file's size (roughly calculated) and the comment field if present
128 
+in the torrent file.
129 
+
130 
+*New: a PHP implemention of the SHA1 algorithm is included. All users
131 
+can upload directly to the newtorrents.php script now. Note however
132 
+that is may produce wrong hashes and generally run slowly.
133 
+
134 
+
135 
+DELETING TORRENTS
136 
+-----------------
137 
+The script deleter.php allows you to delete torrents from the database.
138 
+The username and password are NOT the same as newtorrnets.php uses.
139 
+Use the login and password that the SQL database itself uses. Of course,
140 
+there's nothing preventing you from making these identical.
141 
+
142 
+Be warned: there is no confirmation of deletion and a torrent
143 
+need not be abandoned to be erased. Changes take effect immediately.
144 
+
145 
+
146 
+
147 
+TORRENTSPY COMPATABILITY (and other /scrape functions)
148 
+------------------------
149 
+Starting with version 1.5, since an official statement has
150 
+been made on /scrape conventions, announce.php and scrape.php
151 
+are provided. announce.php simply executes tracker.php,
152 
+while scrape.php causes tracker.php to output scrape data.
153 
+
154 
+The old style of using http://www.site.com/tracker.php/announce
155 
+is still included (in fact, this is how scrape.php works) but
156 
+is now discouraged since this convention caused more problems
157 
+than it ever really should have.
158 
+
159 
+Any program not capable of figuring out the scrape.php script
160 
+name from announce.php is broken and needs to be fixed.
161 
+
162 
+
163 
+
164 
+STATISTIC COLLECTING (or, "Database Structure")
165 
+--------------------
166 
+
167 
+I tried to make the database information as easy to understand
168 
+as possible. "SELECT * FROM summary" should provide you with
169 
+all the programming information you need, but here is a brief
170 
+rundown of what the fields mean.
171 
+
172 
+Summary:
173 
+	*info_hash - The 40 character hex representation of
174 
+	 the file. It is unique to every torrent.
175 
+
176 
+	*dlbytes - The approximate sum of all the bytes downloaded
177 
+	 by everyone.
178 
+
179 
+	*seeds - The number of connected users who have the
180 
+	 whole file and are uploading.
181 
+
182 
+	*leechers - The number of connected users who are still
183 
+	 downloading the file.
184 
+
185 
+	*finished - The number of users who have fully downloaded
186 
+	 the file. Use this as a measure of how many people
187 
+	 have the file.
188 
+
189 
+	*lastcycle - Used by the trash collector to decide if
190 
+	 it should try to purge users who have timed out.
191 
+
192 
+	*lastSpeedCycle - Used by the speec calculator to decide
193 
+	 if the speed should be updated.
194 
+
195 
+	*speed - in bytes per second. Consider it to be extremely
196 
+	rough.
197 
+
198 
+Namemap:
199 
+  Note that all fields (except hash) are optional and may be "" (but not NULL,
200 
+  those are annoying). A torrent need not have an entry here at all.
201 
+  This is used only by the index.php script.
202 
+	*info_hash - The file's unique 40 character hash.
203 
+
204 
+	*filename - The file that this torrent represents
205 
+
206 
+	*url - A link to where the .torrent file may be grabbed.
207 
+
208 
+	*info - A short text description added after the previous
209 
+	 information is shown. Default is the file size.
210 
+
211 
+timestamps:
212 
+  Used by the speed calculator to contain the sliding window average
213 
+  download rate. This is of little interest to external users, so
214 
+  I'll skip it.
215 
+
216 
+x<hexadecimal string>:
217 
+  Each torrent's user list is stored in a table whose name is the
218 
+  info_hash of the torrent prefixed by an x.
219 
+
220 
+	*peer_id - A 40 character hash that is unique to each client
221 
+
222 
+	*bytes - The number of bytes this peer still needs to download
223 
+	 to have the complete file. Seeders have this set to 0.
224 
+
225 
+	*ip - The client's IP address
226 
+
227 
+	*port - The port the client is listening on (usually 6881)
228 
+
229 
+	*status - Either "seeder" or "leecher" (see above). It's a bit
230 
+	 redundent right now since "bytes==0" is the same as a seeder
231 
+
232 
+	*lastupdate - Unix time of when the client last reported in.
233 
+	 Clients whose time is 2 * report_interval will be deleted.
234 
+
235 
+y<hexadecimal string>:
236 
+  The couterpart to the "x" table, only with the peer caching data.
237 
+  I won't describe it here.
238 
+
239 
+
240 
+CREDITS
241 
+-------
242 
+
243 
+People besides me who deserve credit.
244 
+
245 
+Bram Cohen - Author of BT, and really patient guy.
246 
+KktoMx     - Figured out the "stripslashes" problem.
247 
+bideomex   - Found the dumb thing I did with stripslashes.
248 
+Gottaname  - First real load test.
249 
+"daan" (?) - SHA1 in PHP code. See http://www.php.net/manual/en/function.sha1.php
250 
+             user comments.
251 
+Bak4San    - Provider of torrents with ten thousand peers. On a weekly
252 
+             basis.