(Note: OS X 10.4 users: the version of python supplied with 10.4 is slightly cut down in such a way that btqueue will not run. First install the python 2.4.4 package (or which ever version is current) available via http://pythonmac.org/packages/ then follow this guide).
btqueue uses the standard python setup.py script for installation. Enter the directory in a terminal and type:
python setup.py build
then become root (or using sudo):
python setup.py install
2) Invocation
There are two ways to run btqueue. Firstly:
btqueue.py scheduler
This starts btqueue and leaves you at its standard command prompt.
Secondly:
btqueue.py daemon
This starts btqueue and puts it in the background leaving you at the normal command prompt. To access btqueue's command prompt you can now type:
btqueue.py remote
The beauty of this option is that you can start btqueue on one machine and then check on its progress (or give it new commands) from multiple locations by sshing into the machine.
3) Adding torrents to btqueue
There are two ways to do this. Firstly if btqueue is running as a daemon you can type:
btqueue.py add file.torrent
This will append file.torrent to the end of btqueue's list of files to download.
Secondly, if you are at btqueue's internal command prompt you can issue the command:
add file.torrent
This will also add file.torrent to the end of the queue
4) Functionality whilst running
Most btqueue command prompt commands have a simple explanation within the command prompt. Type 'help' to see the full list of commands, and then 'help command' to see the usage of a specific command.
The most useful ones (for me):
list - prints the current 'queue' of torrents with basic information about each (download rate, number of peers etc). Also of note is the torrent 'ID' which is the first item printed. When performing actions with the other commands on a running/queued torrent you specify the torrent to act on with this ID.
spew ID - prints detailed information on all connected peers for a specific torrent including IP address, client, Local/Remote connection, country, download upload speed.
quit - when controlling btqueue via remote access closes your remote connection, leaving btqueue running.
kill - shuts down btqueue, ending all current downloads.
5) Configuration
Configuration options for btqueue are stored in the file: ~/.btqueue/policy.conf
These are two ways of applying the options. Editing the file directly, or from within btqueue.
Say, for example, you had forwarded port 9991 to use for bittorrent. To make btqueue use this port you would set (in the policy.conf file):
max_port=9991
min_port=9991
use_single_port=1
If you wanted to do this through the btqueue command prompt you would have entered:
gset max_port 9991
gset min_port 9991
gset use_single_port 1
It is best to set these options through btqueue. If you edit the policy.conf file it must be whilst btqueue is not running, or else it will overwrite the settings when it closes. If you set the options using gset btqueue will write them to policy.conf itself when it exits.
To see the list of variable names available to alter either look through policy.conf, or type gget at the btqueue command prompt.
As well as the port number to use, useful options you can set using gset include: dest_path - the 'download' folder and max_upload_rate/max_download_rate which (I believe) is the maximum combined allowed upload/download rate.
It should be noted that many of these commands are taken directly from the bittorrent/bittornado command line options. Running one of their activation files (which are supplied as part of btqueue) without any options will give more detailed information about what each of these options do. For example ./btdownloadcurses.py can tell us:
--alloc_type <arg>
allocation type (may be normal, background, pre-allocate or sparse) (defaults to 'normal')
These options can be specified just for an individual torrent using 'lset' as in 'lset id key value'. For example:
lset 1 max_download_rate 30
6) Queue configuration
When adding torrents to the queue they will be run automatically once the number of currently active torrents falls below 'max_run_job' (which can be set as the other configuration options detailed above).
Manual:
You can manage the queued torrents manually using: pause ID and resume ID.
Automatic:
If max_run_job torrents are not currently running, torrents will keep being loaded from the queue until there are max_run_job torrents running.
If there are torrents waiting to be activated, once a torrent has completed and its min_seed_time and min_share_ratio have been reached it will be stopped and the next queued torrent activated, with the constraint that (if possible) there will be min_seeder torrents still running.
If there are no waiting torrents, max_seeder active torrents, once completed, will continue to seed until max_seed_time or max_share_ratio are reached. They will then be deactivated.
Feature request: I do not believe there is a way to set the queue such that one torrent at a time _downloads_ and there are also a set number of 'seeding slots'. If I feel sufficiently motivated I may look at the code and try to add a 'max_downloader' option which lets you prevent all of the 'max_run_job' slots being downloading torrents.
7) Topics not covered (because I don't know enough about them)
Windows specific configuration/running etc. If there are details relevent for Windows users please add a comment to help them out.
I looked for documentation for a while (finding none) before I found the sourceforge forums which seems to contain the majority of info about this program out there. So if you need more info use the forums. Sugree seems to respond promptly to queries.
Many thanks to Sugree for giving us this excellent program. If I have stated something wrong please correct me. Also, it would be nice to include this (or something like it) in a README file in the main release tarball to give users a shallower learning curve.
stoic
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
btqueue ('BitTorrent Queue Manager') Basic Guide
(Note: OS X 10.4 users: the version of python supplied with 10.4 is slightly cut down in such a way that btqueue will not run. First install the python 2.4.4 package (or which ever version is current) available via http://pythonmac.org/packages/ then follow this guide).
1) Installation (for unix users)
Download the latest btqueue installation package from its sourceforge page at: http://sf.net/projects/btqueue/
Decompress.
btqueue uses the standard python setup.py script for installation. Enter the directory in a terminal and type:
python setup.py build
then become root (or using sudo):
python setup.py install
2) Invocation
There are two ways to run btqueue. Firstly:
btqueue.py scheduler
This starts btqueue and leaves you at its standard command prompt.
Secondly:
btqueue.py daemon
This starts btqueue and puts it in the background leaving you at the normal command prompt. To access btqueue's command prompt you can now type:
btqueue.py remote
The beauty of this option is that you can start btqueue on one machine and then check on its progress (or give it new commands) from multiple locations by sshing into the machine.
3) Adding torrents to btqueue
There are two ways to do this. Firstly if btqueue is running as a daemon you can type:
btqueue.py add file.torrent
This will append file.torrent to the end of btqueue's list of files to download.
Secondly, if you are at btqueue's internal command prompt you can issue the command:
add file.torrent
This will also add file.torrent to the end of the queue
4) Functionality whilst running
Most btqueue command prompt commands have a simple explanation within the command prompt. Type 'help' to see the full list of commands, and then 'help command' to see the usage of a specific command.
The most useful ones (for me):
list - prints the current 'queue' of torrents with basic information about each (download rate, number of peers etc). Also of note is the torrent 'ID' which is the first item printed. When performing actions with the other commands on a running/queued torrent you specify the torrent to act on with this ID.
spew ID - prints detailed information on all connected peers for a specific torrent including IP address, client, Local/Remote connection, country, download upload speed.
quit - when controlling btqueue via remote access closes your remote connection, leaving btqueue running.
kill - shuts down btqueue, ending all current downloads.
5) Configuration
Configuration options for btqueue are stored in the file: ~/.btqueue/policy.conf
These are two ways of applying the options. Editing the file directly, or from within btqueue.
Say, for example, you had forwarded port 9991 to use for bittorrent. To make btqueue use this port you would set (in the policy.conf file):
max_port=9991
min_port=9991
use_single_port=1
If you wanted to do this through the btqueue command prompt you would have entered:
gset max_port 9991
gset min_port 9991
gset use_single_port 1
It is best to set these options through btqueue. If you edit the policy.conf file it must be whilst btqueue is not running, or else it will overwrite the settings when it closes. If you set the options using gset btqueue will write them to policy.conf itself when it exits.
To see the list of variable names available to alter either look through policy.conf, or type gget at the btqueue command prompt.
As well as the port number to use, useful options you can set using gset include: dest_path - the 'download' folder and max_upload_rate/max_download_rate which (I believe) is the maximum combined allowed upload/download rate.
It should be noted that many of these commands are taken directly from the bittorrent/bittornado command line options. Running one of their activation files (which are supplied as part of btqueue) without any options will give more detailed information about what each of these options do. For example ./btdownloadcurses.py can tell us:
--alloc_type <arg>
allocation type (may be normal, background, pre-allocate or sparse) (defaults to 'normal')
These options can be specified just for an individual torrent using 'lset' as in 'lset id key value'. For example:
lset 1 max_download_rate 30
6) Queue configuration
When adding torrents to the queue they will be run automatically once the number of currently active torrents falls below 'max_run_job' (which can be set as the other configuration options detailed above).
Manual:
You can manage the queued torrents manually using: pause ID and resume ID.
Automatic:
If max_run_job torrents are not currently running, torrents will keep being loaded from the queue until there are max_run_job torrents running.
If there are torrents waiting to be activated, once a torrent has completed and its min_seed_time and min_share_ratio have been reached it will be stopped and the next queued torrent activated, with the constraint that (if possible) there will be min_seeder torrents still running.
If there are no waiting torrents, max_seeder active torrents, once completed, will continue to seed until max_seed_time or max_share_ratio are reached. They will then be deactivated.
Feature request: I do not believe there is a way to set the queue such that one torrent at a time _downloads_ and there are also a set number of 'seeding slots'. If I feel sufficiently motivated I may look at the code and try to add a 'max_downloader' option which lets you prevent all of the 'max_run_job' slots being downloading torrents.
7) Topics not covered (because I don't know enough about them)
Crawler - loads RSS feeds and automatically queues the download of certain torrents matching a prespecified search pattern. More information available http://btqueue.sourceforge.net/2005/12/crawler-mode.html
Windows specific configuration/running etc. If there are details relevent for Windows users please add a comment to help them out.
I looked for documentation for a while (finding none) before I found the sourceforge forums which seems to contain the majority of info about this program out there. So if you need more info use the forums. Sugree seems to respond promptly to queries.
Many thanks to Sugree for giving us this excellent program. If I have stated something wrong please correct me. Also, it would be nice to include this (or something like it) in a README file in the main release tarball to give users a shallower learning curve.
stoic