Azureus CLI: The Dark Side of Azureus

We create open-source because we love it, and we share our finding so everyone else can benefit as well.


Azureus CLI: The Dark Side of Azureus

While torrent sharing grows more and more each day, it has started to become a great way to host large archives without sacrificing your bandwidth. Such a case is a remote server, that has a limit on the bandwidth, but you don’t want to cripple your user base because of it. So, how do you go about this on a co-location server and such? Well, it’s quite simple, you use the Azureus cli. Most may have a weird look on their face, wondering what co-location server, hosting, and offering other services would really have X installed. Well, that’s what we’re about to talk about. The almost completely undocumented part of Azureus; the console ui.

Azureus Installation

The first thing we are going to do, is make sure we have java 1.5 or later installed. Simply type ‘java -version’ in a terminal to make sure you have the correct version. Also, you need to make sure that the two java libraries, log4j, and commons-cli are installed. Next, we need to go to the java class directory. You can do a ‘whereis java’ to find this. In Ubuntu Feisty, it is /usr/share/java. In FreeBSD, it is /usr/local/share/java/classes. Download the latest Azereus ( at the time of this article), extract the contents, and copy the Azureus2.jar to your class directory. Last, make sure that a file named log4j.jar is in your class directory. You might see log4j-1.2.13.jar, and if that’s all you see, make a symlink to that file.

/usr/share/java# ln -s log4j-1.2.13.jar log4j.jar

Last, we want to make a script to run the client. In your home directory:

 cd /usr/local/share/java
 java -jar Azureus2.jar --ui=console

Change the class directory as needed, save, and chmod 755 the script.

Once that’s done, we will be ready to run our new client.

Setting Up The Azureus File System

To make it easier on you, and to make things a little more organized, we will create two new directories. One named Torrents, and one named Downloads. I put these in a shared NFS directory, but you can put them anywhere. As an example, make a new directory /Azureus, and then make the Torrents and Downloads directories in that folder. Any time you get a torrent file, or want to seed a torrent you created, put it in the Torrents folder. The files you want to seed, put in Downloads directory.

Using the Azureus CLI

Now, we want to run our client by executing the script we wrote earlier. Once we have done that, we should see the Azureus CLI for the first time. At first, you’ll see the patch notes and then it will stop. While it isn’t doing much more, you are ready to use it. Type “?”, and press enter. The basic help menu will output after this, and you can see the various things you can do.

hack [<various options>]        #       Modify torrent settings. Use without parameters for further help. add [addoptions] [.torrent path|url]            a       Add a download from the given .torrent file path or url. check (<torrentoptions>)        c       Force recheck on torrent(s). queue (<torrentoptions>)        q       Queue torrent(s). remove (<torrentoptions>)       r       Remove torrent(s). start (<torrentoptions>)        s       Start torrent(s). stop (<torrentoptions>)         h       Stop torrent(s). host (<torrentoptions>)                 Host or stop hosting torrent(s). publish (<torrentoptions>)              Publish or stop publishing torrent(s). forcestart (<torrentoptions>)           Start torrent ignoring other limits/rule --snip-- show [<various options>]        sh      Show info. Use without parameter to get a list of available options.

That part of the help section, is what we are really interested in. So, let’s give this a shot. Let’s say we created a torrent named MyNewTorrent, and we put the .torrent file in the Torrents folder. We then put the files we want to host in the Downloads directory, exactly as it would be downloaded. Let’s say your torrent hosted a directory named “My Tutorials”, with several files inside. Copy that folder to the Downloads directory, that way the path would be /Azureus/Downloads/My Tutorials.

Now how will the Azureus CLI know where to look for these files? Well, let’s take a look at the options available for the client. Type “set”, in the client. You will see an almost overwhelming amount of settings. Don’t worry, we’ll cover what’s most important in these settings. First, let’s set the download directory.

set "General_sDefaultSave_Directory" /Azureus/Downloads
 > Parameter 'General_sDefaultSave_Directory' set to '/Azureus/Downloads'. [string]

Ok, now that we have the download directory, it’s time to start seeding. So, now we need to load the torrent file.

add /Azureus/Torrents/MyNew*
 > -----
 > Found 1 files:
 > '/Azureus/Torrents/MyNewTorrent.torrent' added.
 > -----

So, now we added the torrent, and demonstrated that we can use wildcards. Now, if there was another torrent named MyNewTorrent2, and you did the same command with the first one already loaded, it would simply load the second one without messing with the 1. So, let’s take a look at the torrent. Simply type “show torrents” in our Azureus CLI.

show torrents
 > -----
  1 [C] 40.0%   MyNewTorrent (42.21 MB) ETA: Finished                 Speed: 0 B/s / 0 B/s    Amount: 42.21 MB / 0 MB   Connections: 0(?) / 0(?)
 Total Speed (down/up): 0 B/s / 0 B/s
 Transferred Volume (down/up/discarded): 0 B / 0 B / 0 B
 Total Connected Peers (seeds/peers): 0 / 0
 > -----

Now, we see that the torrent is loaded, the torrent number is “1”, and looking at the state [C] we know it’s checking the files. After it’s done checking, it will start to seed. If we were downloading from a torrent, and didn’t have the files; the client would start downloading, seeing that the files did not exist. Let’s take a look at all of the states a torrent can be in, and how to read it in the client.

? torrents 
> ----- 
# [state] PercentDone Name (Filesize) ETA 

        DownSpeed / UpSpeed     Downloaded/Uploaded     ConnectedSeeds(total) / ConnectedPeers(total) 

  > Downloading
  * Seeding
  ! Stopped
  . Waiting (for allocation/checking)
  : Ready
  - Queued
  A Allocating
  C Checking
  E Error
  I Initializing
  ? Unknown
 > -----

Just like we did here, you can ask for help for certain commands with the syntax “? “.

Handling Azureus CLI Connections

Not only can we see the type of states, we also see how to read the syntax of the torrent view. Let’s look a few other basic commands. Typing ‘stop 1’ will of course, stop the torrent labeled “1”. If you want to recheck the files for torrent 1, type ‘check 1’. Of course, if you want to remove the torrent from the queue, type ‘remove 1’.

Now, if we want to throttle a certain torrent to use a set amount of bandwidth, we can use the ‘hack’ command.

hack > Missing subcommand for 'hack'
 > ----- 'hack' syntax: hack <torrent id> <command> <command options>

 <torrent id> can be one of the following:
 <#>             Number of a torrent. You have to use 'show torrents' first as the number is taken from there.
 hash <hash>     Applied to torrent with the hash <hash> as given in the xml output or extended torrent info ('show <#>').
 help            Detailed help for <command>
 Available <command>s:
 uploadspeed     u       Set max upload speed [in kbps] of a torrent (0 for unlimited).
 tracker         t       Modify Tracker URL of a torrent. 
downloadspeed   d       Set max download speed [in kbps]of a torrent (0 for unlimited).
 file            f       Modify priority of a single file of a batch torrent. 
uploads v       Set max upload slots of a torrent.
 > -----

If we wanted to make the max upload of the second torrent 5KB/s, we would execute this command:

hack 2 u 5
 > Hacking Torrent #2 (MyNewTorrent2) succeeded.

The same goes for the download speed, but with ‘d’ instead of ‘u’. If you wanted to change the passkey or URL for the tracker, you can do it here as well, but with the “t” command.

If you want to test your NAT setup, and make sure you have a good connetion for peers and trackers, make use of the ‘show nat’ command:

show nat
 Testing TCP port 17737 inbound
     -> OK, public address=/
 Testing UDP port 17737 inbound
     -> Failed: timed out, Inbound check failed

Advanced Azureus Usage

Now that we’ve dealt with the basic commands. Let’s start tweaking our configuration, making the best of our experience. Let’s get back to our setting that we viewed using “set”. Instead of showing you each and every one of them, and how they effect the torrent, I will list the major ones, and what they do.

Remember, to set a new value, use this syntax

set "<parameter name>" <value>

The parameter name is everything before “is not set, KBs, or [datatype]”, and after the “>”. For example.

> Auto Upload Speed Seeding Enabled is not set. [int, default: 0]
 set "Auto Upload Speed Seeding Enabled" 1

Let’s take a look at the most common settings:

> Auto Upload Speed Seeding Enabled is not set. [int, default: 0]
    # turn on/off auto upload speed for all torrents (1=on, 2=off)

 > AutoSpeed Max Upload KBs: 30 [int]                                            
 # if auto upload speed is on, set the total amount of upload bandwidth

 > Core_bDisconnectSeed: false [bool]                                               
 # disconnect seed, or always active (0=false, 1=true)

 > Core_fSeedingShareStop is not set. [string, default: 0.0]             
 # Stop seeding when a ratio is achieved

 > Core_iMaxActiveTorrents is not set. [int, default: 4]                     
 # Maximum amount of active torrents at one time

 > Core_iMaxDownloads is not set. [int, default: 4]                           
 # Maximum number of active downloads at one time

 > Core_iMaxUploadSpeed is not set. [int, default: 0]                       
 # Maximum upload speed for each torrent. Use if not using AutoSpeed

 > Core_iMaxUploads is not set. [int, default: 4]                                
# Maximum number of active uploads at one time

 > Core_iTCPListenPort: 17737 [int]                                                  
 # TCP port to bind to

 > Max Upload Speed Seeding KBs is not set. [int, default: 0]         
 # Maximum upload speed for torrents when seeding

 > StartStopManager_bAutoStart0Peers true bool                          
# Keep seeding even with 0 peers, and seed when possible

 > StartStopManager_iIgnoreShareRatioSeedStart: 1 [int]             
 # Ignore the share ratio when seeding

 > Plugin.UPnP.upnp.enable is not set. [int, default: 1]                    
 # Enable/Disable uPnP Support

 > UDP.NonData.Listen.Port: 17737 [int]                                         
 # UDP port to bind to

If you set something, and want to find out what you set, but don’t want to go through all the settings, use the ‘set -export’ command. This will only show the settings that are not at their default setting.

While there are many many more options you could set, these are probably the most common for the general Azureus power user. Of course, we only skimmed the surface of what the client can do. Aside from a few things, the console client is capable of doing anything the GUI client can do, you just have to find it.

The Easy Way Out

Of course, we may want a setup like this, but we don’t want to deal with combing the settings to get it how we want it. You can always use the same version of Azureus on another Linux or UNIX box, and copy the ~/.azureus folder to the user’s home directory on the other system. From there, Azureus will automatically load those settings, just how you wanted them set. Of course, if you wanted to change them, a ‘set -export’ will make it easy to identify the parameter you need to change.

Well, that’s it. I know I didn’t cover too much of the client, but at least this can get everyone using it for a basic purpose. Enjoy!

No Comments

Add your comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.