Debian Codegraph @

UserGuide

raw
1
2 Enhanced CTorrent User's Guide
3
4 This guide is presented to offer additional information related to
5 using [1]Enhanced CTorrent.
6
7 This document is not an introduction to BitTorrent--for that, try
8 [2]this, [3]this, or an Internet search.
9
10 Contents
11
12 * Options
13 + [4]General
14 + [5]Downloading
15 + [6]Create Torrent
16 * [7]Examples
17 * [8]Runtime Commands
18 + [9]Operator Menu
19 * Usage Notes
20 + [10]Bandwidth Limits
21 + [11]Startup
22 + [12]Status Line
23 + [13]Stopping CTorrent
24
25 Options Index
26 [14]-a [15]-A [16]-b [17]-c [18]-c [19]-C [20]-d [21]-D [22]-e [23]-E
27 [24]-f [25]-i [26]-I [27]-l [28]-m [29]-M [30]-n [31]-p [32]-p [33]-P
28 [34]-s [35]-s [36]-S [37]-t [38]-T [39]-u [40]-u [41]-U [42]-v [43]-x
29 [44]-X [45]-z
30 _________________________________________________________________
31
32 Options
33 ___________________________________
34
35 General Options
36
37
38 -x Decode metainfo (torrent) file only, don't download
39
40 Displays the torrent information and contents from the metainfo
41 (.torrent) file. No piece checking or downloading is performed.
42 This option is normally used alone.
43
44
45 -c Check pieces only, don't download
46
47 Hash-checks all pieces of the torrent to verify completion
48 status and exits. Use this when you want to verify that you've
49 successfully downloaded the complete torrent, or to make sure
50 the files are intact after a system crash. This option is
51 normally used alone, but can be used with -X for an automated
52 completion check.
53
54
55 -v Verbose output (for debugging)
56
57 Generates [a lot of] extra output while CTorrrent is running.
58 ___________________________________
59
60 Downloading Options
61
62
63 -e int Exit while seed <int> hours later (default 72 hours)
64
65 Indicate how long (in hours) you want to "seed" (continue
66 uploading) after download has completed. It is considered
67 polite and fair (and required by some tracker sites) to seed
68 for some time after downloading.
69
70
71 -E num Exit after seeding to <num> ratio (UL:DL)
72
73 Specify a desired "seed ratio". After downloading completes,
74 the client will continue seeding (uploading) until your total
75 upload volume divided by your download volume equals this
76 number. Fractional values (such as 1.5) are allowed. It is
77 considered polite and fair (and required by some tracker sites)
78 to seed until your ratio is at least 1:1.
79
80
81 -i ip Listen for connections on specific IP address (default all/any)
82
83 Specify the IP address on which you want to listen for incoming
84 connections. This is only useful if your system has multiple
85 network interfaces and you want to restrict access or run
86 multiple clients on different interfaces.
87
88
89 -p port Listen port (default 2706 -> 2106)
90
91 Specify the TCP port number on which to listen for incoming
92 connections. By default, CTorrent starts at 2706 and searches
93 for an available port in decreasing order until it finds one or
94 exhausts all ports down through 2106. The behavior with this
95 option is similar, but starting at the specified port number.
96
97
98 -I ip Specify public/external IP address for peer connections
99
100 Specify the IP address which the tracker should give out to
101 peer clients in order to connect to you. This is normally
102 needed only if you are behind a NAT and on the tracker's local
103 network.
104
105
106 -u num or URL Alternate announce (tracker) URL
107
108 Specify an alternate tracker announce URL. The parameter can be
109 the actual URL or the number from the list of alternates
110 printed when starting the client or using -x.
111
112
113 -s filename Download ("save as") to a different file or directory
114
115 Download to a different filename or top-level directory name
116 than what is given in the metainfo file.
117
118
119 -C cache_size Cache size, unit MB (default 16MB)
120
121 Specify the maximum amount of memory to use for caching
122 downloaded slices. The program may use less than this; the
123 cache size is dynamically tuned based on the download and
124 upload rates. You may need to use this option if running on a
125 memory-constrained system such as a router or SAN device. If
126 you use a value of 0, no memory cache will be used but the
127 process will be more disk-intensive.
128
129
130 -f Force saved bitfield or seed mode (skip hash check at startup)
131
132 Perform a fast startup by skipping the initial (or background)
133 hash verification of the files. This option is not generally
134 recommended since the client now performs initial hash checking
135 in the background. Use this option only if CTorrent was shut
136 down cleanly when last downloading this torrent and you are
137 absolutely certain that the bitfield (if download is not
138 complete) and data files are intact and correct. To emulate the
139 old behavior of hash-checking all pieces before beginning
140 download or seeding, use -f along with the -c option.
141
142
143 -b filename Specify bitfield save file (default is torrent+".bf")
144
145 Piece completion status is saved to a bitfield file on exit if
146 download has not completed. On startup the file is read to
147 determine (and check) available pieces. The -b option can be
148 used to specify a filename other than the default. Be
149 consistent and careful with this option; it is generally not
150 needed.
151
152
153 -M max_peers Max peers count (default 100)
154
155 Set the maximum allowable number of peer connections. If this
156 number is reached, no new connections will be initiated or
157 accepted. If memory or upload bandwidth are constrained, you
158 may want to use this option to specify a lower value.
159
160
161 -m min_peers Min peers count (default 1)
162
163 Set the desired minimum number of peer connections. If the
164 number falls below this value, the client will contact the
165 tracker to request more peers.
166
167
168 -z slice_size Download slice/block size, unit KB (default 16, max 128)
169
170 Sets the size of the basic unit of download. For greatest
171 compatibility with other peer clients, use the default. This
172 value can also affect the precision with which bandwidth is
173 managed.
174
175
176 -n file_list Specify file number(s) to download
177
178 Specify a priority order for downloading files in the torrent.
179 A comma-separated list of file numbers and groups can be
180 specified; the file numbers can be seen with the -x option. The
181 client will preferentially request pieces of the
182 highest-priority files, requesting a piece from a
183 lower-priority group if a peer has no such pieces.
184 A group may consist of:
185
186 + a file number
187 + a range of file numbers (x-y)
188 + a combination of file numbers and ranges separated with plus
189 (+) signs
190 + an asterisk (*) or 3-dot ellipsis (...)
191
192 If an asterisk (remember to quote it on the command line!) or
193 ellipsis is used, the client will download and seed the
194 remainder of the torrent once the prioritized files are
195 completed; this is similar to the previous behavior of the
196 option. If no such specification is given, the client will
197 download and seed only the indicated files.
198 Examples:
199
200 -n 3
201 Download and seed only file 3.
202
203 -n 3+5+7,8-11
204 Download files 3, 5, and 7 simultaneously, then download
205 files 8 through 11 simultaneously, then stop downloading
206 and seed all downloaded files.
207
208 -n 3-4,...
209 Download files 3 and 4 simultaneously, then download and
210 seed all remaining content.
211
212
213 -D rate Max bandwidth down (unit KB/s)
214
215 Specify a download bandwidth limit for this torrent. The client
216 will maintain its short-term average download rate at or below
217 this value.
218
219
220 -U rate Max bandwidth up (unit KB/s)
221
222 Specify an upload bandwidth limit for this torrent. The client
223 will maintain its short-term average upload rate at or below
224 this value.
225
226
227 -P peer_id Set Peer ID prefix. (default "-CD0301-")
228
229 Specify an alternate peer ID prefix. This can be useful if a
230 tracker is set up to only allow client programs that it
231 recognizes. (The admin may not even realize it, so you may want
232 to try contacting them to request that they change their
233 configuration or add Enhanced CTorrent to the list.) If you
234 receive a tracker warning message that your client is out of
235 date, try using this option with the prefix of another
236 well-known client program (such as "-AZ2304-").
237
238
239 -A user_agent Set User-Agent header. (default "Enhanced-CTorrent/dnh3.1")
240
241 Specify an alternate user-agent header. This can be useful if a
242 tracker is set up to only allow client programs that it
243 recognizes.
244
245
246 -S host:port Use CTCS server at host:port
247
248 Maintain a connection to CTCS for status reporting, bandwidth
249 control, and client management. Using a colon at the end of the
250 parameter (as in "-S localhost:2780:") will cause the client to
251 prompt for a password to send to CTCS when connecting.
252
253
254 -a Preallocate files on disk
255
256 Use this if you are concerned about file fragmentation or
257 out-of-order block storage. This option is only effective when
258 initially creating the files and will cause startup to take
259 longer as each entire file is written in order to reserve
260 physical disk space. Note that all files will be created and
261 preallocated even if the "-n" option is used to download a
262 particular file.
263
264
265 -T Convert foreign filenames to printable text
266
267 Substitutes a hex representation of any non-printable
268 characters in filenames; an underscore will be inserted between
269 any such sequences and regular text. This applies to printing
270 the name of the file as well as accessing it on disk, so you
271 need to use it (or not) consistently across multiple runs of
272 the same torrent. It does not apply to names specified with the
273 "-s" option.
274
275
276 -X command Run command upon download completion ("user exit")
277
278 Specifies a "user exit" command to run upon download
279 completion. The string parameter will be passed to the sh shell
280 for execution; see the system() man page for further
281 clarification. You will need to quote this string on the
282 command line in order to identify it as a single parameter and
283 prevent special characters from being interpreted. Some
284 substitution sequences beginning with ampersand (&) are
285 available; note that it's a good idea to quote the sequence
286 within the string so that the substituted names will be quoted
287 in the final command.
288
289 + &d will be replaced by the name of the directory or filename
290 that contains the downloaded data.
291 + &t will be replaced by the name of the torrent metainfo file
292 (with path, if it was specified that way to ctorrent).
293 + &w will be replaced by the client's working directory.
294
295 Note that the fork() and system() system/library functions are
296 used for best portability. As a result, significant extra
297 memory may be used while the specified command is running. Be
298 advised to use this feature as a trigger mechanism to update a
299 file or run a short script that kicks off a background task
300 rather than for executing a longer task directly.
301 This option can also be used together with -c as an automated
302 completion check. Normally the completion command will be run
303 only if data has been downloaded; this case is the exception.
304
305
306 -d Daemon mode (fork to background)
307
308 The client will detach itself from the terminal session and
309 become a background process, closing stdin, stdout, and stderr.
310 There is no way to bring it back into the foreground of a
311 session later; if you want to monitor or manage the client then
312 either use the CTCS option (-S) as well or run the client under
313 [46]screen instead of using -d.
314 If this option is specified twice (-dd) then redirected
315 standard I/O descriptors will not be closed.
316 ___________________________________
317
318 Options for Creating a New Torrent
319
320
321 -t Create a new torrent file
322
323 Indicates that you want to create a new torrent. This must be
324 the first option specified when creating a torrent.
325
326
327 -s filename Specify metainfo file name
328
329 (Required) Give the name of the file to be created.
330
331
332 -u URL Tracker's URL
333
334 (Required) Specify the tracker's announce URL. This usually
335 looks similar to "http://tracker.example.com:port/announce".
336
337
338 -l piece_len Piece length (default 262144)
339
340 Specify the piece size for your torrent. This will also
341 determine the number of pieces in the torrent.
342
343
344 -p Private (disable peer exchange)
345
346 Disable the use of DHT, PEX, or other trackerless peer-exchange
347 methods by other clients when sharing this torrent.
348
349
350 -c comment Include a comment/description
351
352 Include a comment field in the torrent file.
353 _________________________________________________________________
354
355 Examples
356
357 List the contents of a torrent:
358
359 ctorrent -x example.torrent
360
361 Verify download completion status (takes a little time):
362
363 ctorrent -c example.torrent
364
365 Download or seed a torrent using default options:
366
367 ctorrent example.torrent
368
369 Download with a limit of 100KB/s, upload limit of 10KB/s, and seed
370 until a ratio of 1.5:1 is achieved:
371
372 ctorrent -D 100 -U 10 -E 1.5 example.torrent
373
374 Create a torrent:
375
376 ctorrent -t -u "http://tracker.example.com:6969/announce" -s example.torrent fi
377 le_or_dir_to_upload
378 _________________________________________________________________
379
380 Runtime Commands
381
382 Several commands are available during upload/download; a list is
383 available by pressing ? or h:
384 Available commands:
385 [Esc/0] Operator menu m[+/-] Adjust min peers count
386 d[+/-] Adjust download limit M[+/-] Adjust max peers count
387 u[+/-] Adjust upload limit C[+/-] Adjust max cache size
388 n Download specific file S Set/change CTCS server
389 e[+/-] Adjust seed exit time v Toggle verbose mode
390 E[+/-] Adjust seed exit ratio Q Quit
391 X Completion command
392
393 Command keys are case-sensitive. When a command key is pressed, a
394 prompt or current value is displayed. Prompts will suspend display of
395 the status line while waiting for input, though the client continues
396 to run normally. Toggle and numeric commands briefly suspend the
397 status line display.
398
399 Commands shown with [+/-] following the key are numeric options and
400 can be adjusted by pressing + or - repeatedly after the command key.
401 The increment is increased after five presses; to reset it, press the
402 command key again.
403
404 Most commands use the same letter as the corresponding command-line
405 option. Note that the bandwidth limit commands use the same letters
406 but opposite case.
407
408 Operator Menu
409
410 The 0 or Esc command key displays an operator menu with more advanced
411 (or less routine) options. All options on and beneath this menu
412 require pressing Enter to submit the input. Pressing Enter alone will
413 exit the menu.
414 Operator Menu
415 Output Channels:
416 1) Normal/status: stdout
417 2) Interactive: stdout
418 3) Error/warning: stderr
419 4) Debug/verbose: stderr
420 5) Input: stdin
421 Status Line Formats:
422 6) \ 0/6/18 [700/700/700] 0MB,11127MB | 0,15K/s | 0,0K E:0,405
423 *7) | S:0/10 L:6/7 C:0 R=15.92 D=0 U=16 K/s seeding 48:57
424 Other options:
425 8) View detailed status
426 9) Pause (suspend upload/download)
427 10) Become daemon (fork to background)
428 11) Update tracker stats & get peers
429 12) Restart (recover) the tracker session
430 Enter selection:
431
432 The first set of options allow redirection of the client's various
433 types of console output (or even input--use carefully!). Of particular
434 use is the debug/verbose channel, which can be directed to a file to
435 create a debug log (be sure to also enable verbose output with the "v"
436 command key or CTCS).
437
438 The second set of options is used to select the status line format.
439 Since the actual client status is used to generate the menu options,
440 the operator menu display can also be used just to view the alternate
441 status information. An asterisk (*) indicates the currently selected
442 format.
443
444 The next two options provide a means to view more detailed current
445 status and statistics or to pause uploading and downloading (more or
446 less immediately, unlike the previous CTCS pause function).
447
448 Note that there is no "recovery" from daemon mode. Use CTCS (with
449 daemon mode) and/or "screen" if you want the client to run in the
450 background but need to manage or monitor it.
451
452 The next two options are the same as the corresponding actions in
453 CTCS. The first performs an early tracker update. The second restarts
454 the tracker session as if you had exited and restarted the client.
455 This can be used to recover if the tracker appears to have suffered a
456 failure and does not recognize your client session.
457 _________________________________________________________________
458
459 Usage Notes
460
461 Bandwidth Limits
462
463 You should always specify an upload bandwidth limit. With the most
464 recent changes in the program, this "option" is not just a limit to
465 stay under, but an advisement to the client as well. Enhanced CTorrent
466 now tunes its upload performance based on the limit. Without a limit,
467 the client has no idea how much bandwidth your line can support and so
468 cannot perform this tuning. It is now possible to achieve better
469 upload rates with a limit than without. Due to the tit-for-tat nature
470 of bittorrent, this can also indirectly increase your download
471 performance. If you just want the client to use as much upload
472 bandwidth as possible, then choose a limit that is 10% or so less than
473 the available upload capacity of your line. ("Available" means not
474 typically in use by other applications.)
475
476 Note that limits are specified in KB/s (kilobytes per second), where
477 1KB = 1024 bytes (8192 bits). Your ISP likely measures in "kilobits"
478 (Kb, where 1Kb = 1000 bits or 125 bytes) or "megabits" (1Mb = 1000000
479 bits or 122KB). Some of that [to the tune of 20% in some cases] is
480 used by the line protocol and thus not available to you at all.
481
482 Startup
483
484 If you have previously started the torrent, CTorrent will perform a
485 hash-check of all pieces (or pieces indicated by the bitfield file if
486 present) while beginning the upload/download process. This does not
487 mean that it is starting over--quite the opposite! This is how the
488 client determines which pieces it already has so that they will not be
489 downloaded again (and can be offered for uploading). This process
490 confirms the pieces that you have even if the files have been altered
491 or recovered after a system crash.
492
493 Status Line
494
495 The status line that is output by the client has changed since the
496 original and deserves some explanation.
497
498 / 0/33/110 [672/672/672] 0MB,1130MB | 0,20K/s | 0,0K E:0,31 P:4/10
499 - - -- --- --- --- --- --- ------ - -- - - - -- ----
500 A B C D E F G H I J K L M N O P
501
502 A: Ticker; this character changes to indicate that the client is
503 running.
504 B: Number of seeders (complete peers) to which you are connected.
505 C: Number of leechers (incomplete peers) to which you are connected.
506 D: Total number of peers in the swarm, as last reported by the
507 tracker.
508 E: Number of pieces of the torrent that you have completed.
509 F: Total number of pieces in the torrent.
510 G: Number of pieces currently available from you and your connected
511 peers.
512 H: Total amount of data you have downloaded.
513 I: Total amount of data you have uploaded.
514 J: Your current download rate (20 second average).
515 K: Your current upload rate (20 second average).
516 L: Amount of data downloaded since the last status line update.
517 M: Amount of data uploaded since the last status line update.
518 N: Number of tracker connection errors.
519 O: Number of successful tracker connections.
520 P: Completion ratio of current fileset (when -n is used).
521
522 Additional information such as tracker connection status may be
523 displayed at the end of the status line when appropriate.
524
525 Alternate Status Line
526
527 A new status line format is also available via the operator menu.
528
529 / S:4/8 L:4/5 C:1 R=5.85 D=42 U=16 K/s 79/100% 49:47 P:40/100% 2:41
530 - - - - - - ---- -- -- -- ---- ----- ------- ----
531 A B C D E F G H I J K L M N
532
533 A: Ticker; this character changes to indicate that the client is
534 running.
535 B: Number of seeders (complete peers) to which you are connected.
536 C: Number of seeders in the swarm (excluding yourself), as last
537 reported by the tracker.
538 D: Number of leechers (incomplete peers) to which you are connected.
539 E: Number of leechers in the swarm (excluding yourself), as last
540 reported by the tracker.
541 F: Number of peer connection attempts in progress.
542 G: Your upload/download ratio.
543 H: Your current download rate (20 second average).
544 I: Your current upload rate (20 second average).
545 J: Percent of the torrent that you have completed.
546 K: Percent of the torrent currently available from you and your
547 connected peers.
548 If you have the complete torrent, "seeding" is displayed instead
549 of these percentages.
550 L: Estimated download or seed time remaining, in hours and minutes.
551 M: Completion and availability of current fileset (when -n is used).
552 N: Time remaining to complete the current fileset (when -n is used).
553
554 Additional information such as tracker connection status may be
555 displayed at the end of the status line when appropriate.
556
557 Stopping CTorrent
558
559 Besides the Q command key (equivalent to Ctrl-C but a nicer user
560 interface), CTorrent can be stopped before completing download or
561 seeding by pressing Ctrl-C or sending the TERM signal ("kill pid").
562 This will tell the client to contact the tracker to send its final
563 statistics and advise that it is leaving the torrent. Note that this
564 could take a couple of minutes if the tracker is down or very busy.
565 (Only one attempt is made, so the client will exit even if the
566 connection fails.)
567
568 If Ctrl-C or kill is used a second time, the client closes all peer
569 connections and exits without waiting for the tracker connection. This
570 means that other peers may still attempt to contact you for a while,
571 and the tracker may not accept you back into the torrent until your
572 original session expires. (This could take up to a couple of hours,
573 depending on the tracker.)
574
575 In either case, this is a clean shutdown of CTorrent. All downloaded
576 data is written to disk before exiting. (Though only complete pieces
577 really count if the torrent is restarted, as there is no way to know
578 which blocks are missing from partial pieces.)
579 _________________________________________________________________
580
581 References
582
583 1. http://www.rahul.net/dholmes/ctorrent/
584 2. http://en.wikipedia.org/wiki/BitTorrent
585 3. http://btfaq.com/
586 4. http://www.rahul.net/dholmes/ctorrent/userguide.html#opt_general
587 5. http://www.rahul.net/dholmes/ctorrent/userguide.html#opt_download
588 6. http://www.rahul.net/dholmes/ctorrent/userguide.html#opt_create
589 7. http://www.rahul.net/dholmes/ctorrent/userguide.html#examples
590 8. http://www.rahul.net/dholmes/ctorrent/userguide.html#commands
591 9. http://www.rahul.net/dholmes/ctorrent/userguide.html#opermenu
592 10. http://www.rahul.net/dholmes/ctorrent/userguide.html#bwlimits
593 11. http://www.rahul.net/dholmes/ctorrent/userguide.html#startup
594 12. http://www.rahul.net/dholmes/ctorrent/userguide.html#status
595 13. http://www.rahul.net/dholmes/ctorrent/userguide.html#stopping
596 14. http://www.rahul.net/dholmes/ctorrent/userguide.html#-a
597 15. http://www.rahul.net/dholmes/ctorrent/userguide.html#-A
598 16. http://www.rahul.net/dholmes/ctorrent/userguide.html#-b
599 17. http://www.rahul.net/dholmes/ctorrent/userguide.html#-c
600 18. http://www.rahul.net/dholmes/ctorrent/userguide.html#-c2
601 19. http://www.rahul.net/dholmes/ctorrent/userguide.html#-C
602 20. http://www.rahul.net/dholmes/ctorrent/userguide.html#-d
603 21. http://www.rahul.net/dholmes/ctorrent/userguide.html#-D
604 22. http://www.rahul.net/dholmes/ctorrent/userguide.html#-e
605 23. http://www.rahul.net/dholmes/ctorrent/userguide.html#-E
606 24. http://www.rahul.net/dholmes/ctorrent/userguide.html#-f
607 25. http://www.rahul.net/dholmes/ctorrent/userguide.html#-i
608 26. http://www.rahul.net/dholmes/ctorrent/userguide.html#-I
609 27. http://www.rahul.net/dholmes/ctorrent/userguide.html#-l
610 28. http://www.rahul.net/dholmes/ctorrent/userguide.html#-m
611 29. http://www.rahul.net/dholmes/ctorrent/userguide.html#-M
612 30. http://www.rahul.net/dholmes/ctorrent/userguide.html#-n
613 31. http://www.rahul.net/dholmes/ctorrent/userguide.html#-p
614 32. http://www.rahul.net/dholmes/ctorrent/userguide.html#-p2
615 33. http://www.rahul.net/dholmes/ctorrent/userguide.html#-P
616 34. http://www.rahul.net/dholmes/ctorrent/userguide.html#-s
617 35. http://www.rahul.net/dholmes/ctorrent/userguide.html#-s2
618 36. http://www.rahul.net/dholmes/ctorrent/userguide.html#-S
619 37. http://www.rahul.net/dholmes/ctorrent/userguide.html#-t
620 38. http://www.rahul.net/dholmes/ctorrent/userguide.html#-T
621 39. http://www.rahul.net/dholmes/ctorrent/userguide.html#-u2
622 40. http://www.rahul.net/dholmes/ctorrent/userguide.html#-u
623 41. http://www.rahul.net/dholmes/ctorrent/userguide.html#-U
624 42. http://www.rahul.net/dholmes/ctorrent/userguide.html#-v
625 43. http://www.rahul.net/dholmes/ctorrent/userguide.html#-x
626 44. http://www.rahul.net/dholmes/ctorrent/userguide.html#-X
627 45. http://www.rahul.net/dholmes/ctorrent/userguide.html#-z
628 46. http://www.gnu.org/software/screen/