Next Previous Contents

4. Usage

4.1 Running the GUI for the first time

Starting the GUI: For historical reason, the GUI binary is called 'ed2k_gui' (whereas the project name is 'ed2k-gtk-gui'). There are several ways to start the GUI: On the command line, in a console/terminal window (like xterm, konsole etc.), just type


This is also how you need to start the GUI if something doesn't work (because it can print out additional error messages onto the console screen.

Alternatively, in Gnome or KDE, just hit Alt+F2 and then enter 'ed2k_gui' into the window. That should start the GUI as well.

If you are running the GUI for the first time, you will not have any servers in your serverlist. Go to the servers page and hit the 'fetch serverlist' button and wait a couple of seconds. If you're lucky, you will see a list of servers. If it didn't work, have a look at the status page to find out what went wrong. If you are forced to use a http proxy server, please refer to the Questions and Answers section below on how to make the GUI use a proxy server.

Now that you have servers, click on the 'connect' button and connect to a server.

4.2 Sharing files

eDonkey2000 is a file-sharing program, so you should share some files. Note that it is not possible to not share files with eDonkey2000. eDonkey2000 is able to share parts of files which are being downloaded before they are actually complete. So even if you do not share anything, you will always share the files that you are currently downloading. Same goes for Overnet.

It is not possible to share individual files, you can only share whole directories or directory trees. When you click Shared at the top of the GUI screen, you will see the directories (left) and files (right) you are sharing with the world. To share soemthing, right-click in the path window and select either add directory to share or add directory tree to share. The latter shares a directory with all its subdirectories.

When you add directories with files you have never shared before in eDonkey, the files are being hashed to identify them, this will take some time (I am talking of minutes on old computers), but this will block neither the GUI nor the core.

Please share some content!

How many files should I share?

First of all, note again that your current downloads are automatically shared. How many files you should share in addition to that depends on how much upload bandwidth you have.

If you share large files (hundreds of MB) that are not available on the eDonkey network yet, please be prepared to share this file for a long time, so people actually have a chance to fully download it. If you are not sure about that, please do not share these large files. Few things are more frustrating than downloading a large file, which then suddenly vanishes shortly before it is completely downloaded.

4.3 Configuration

There are some configuration settings you should adjust to your needs.

Maximum download speed and maximum upload speed: these two settings probably explain themselves. However, you should know that eDonkey has a ratio-system, meaning: the maximum download speed is dependent on the upload that you allow. If you allow eDonkey to upload with 10kB/s or more, you can download as fast as you want (set download to '0' = unlimited). If you allow less than 10kB/s upload, then your max. download speed will automatically be set to max. upload * 3 or max. upload * 4 (depending on the speed).

If you have a DSL/Cable connection, you will usually be told your max. download and upload speed in kilobit per second (kbps), for example 576/288. Divide these numbers by eight to get your line speeds in kilobyte per second (kB/s). In this case this would be 72kB/s download and 36kB/s upload. Not that these are the maximum speeds your line is technically capable of. However, there is some amount of overhead due to the various network layers and protocols used in the process, so your real maximum speeds are probably a bit lower. You should also take into account that every downloaded packet needs to be acknowledged to the other end, so you should always configure your max. upload speed in eDonkey considerably lower than your max. line speed (I'd say deduct at least 3-6kB/s from your line speed).

Maximum number of connections: this is the maximum number of connections (sockets) that you want eDonkey to use at any given time. Note that this is only a 'recommendation' to eDonkey, the actual number of connections used might overshoot sometimes for a short period of time. The default setting for this is 45. However, as you are running a *nix system and not some crappy Microsoft OS, you should increase this value to something around 350-550.

Incoming directory: this is the directory where your files will be moved to when they are completely downloaded. It is not recommended to use a network drive for this.

Temp directory: this is the directory where your files are stored while they are being downloaded. If you have enough disk space, put the Incoming and the Temp directory on the same partition. Imcoming and Temp directory should be different directories.

There are many other options, but these are the most important ones. You will find more options in the right-click pop-up menus of the download page and the servers page.

4.4 Connecting to the overnet network for the first time (bootstrapping) (Overnet only) This section only applies to Overnet, not to eDonkey2000.

Overnet is a serverless network. It is decentralised in the sense that there are no servers, and all clients are equal. Clients in the overnet network is called 'peer' or 'contact'. In order to connect to the overnet network, you first need to give overnet the IP address and (udp) port number of another client that is already part of the overnet network. From that client, overnet will then retrieve additional contacts and become part of the overnet network. This process is called 'boostrapping'.

Usually you do not have to do anything. Overnet comes with a file contact.dat which already contains the IP addresses and ports of other clients, and overnet should read that file on start-up and connect to the network automatically.

How can you check whether you are connected to the overnet network? Type into the entry widget at the top of the GUI '!vc' (without the apostrophes) and hit the enter button. Now overnet should spit out a list with a couple of contacts. If it does, everything is fine, and search etc. should work just fine. If, however, it outputs '0 contacts', then you are not connected to overnet and need to 'bootrap' into it.

You can do that two ways: either you search in google for 'contact.dat overnet' and download a contact.dat file with fresh contacts from somewhere (make sure the website looks reasonably current!), and place it where your client's pref.met file resides and then restart your client. Or you could an IP address and (udp) port of a currently online client from somewhere and then type '!boot 9876' into the entry widget at the top of the GUI, without the apostrophes of course. Replace those numbers with the IP address and port respectively. You might need to enter a couple of different ones until it starts connecting. Currently, you can fresh boot IPs by coming to the #overnet channel on with an IRC client (IRC = Internet Relay Chat).

If all that doesn't work, you should check your UDP configuration, ie. that your firewall or router is not blocking UDP packets.

4.5 Maintaining your server list (eDonkey2000 only) This section only applies to eDonkey2000, not to Overnet. Overnet is a serverless network.

The eDonkey network has no central servers like the old Napster system or similar file-sharing systems, but it also is not (yet) completely serverless like Gnutella. Everyone can open an eDonkey server, and many of these servers are on dynamic IPs that change regularly.

This means, you need to take care of your server list and update it regularly.

Clicking with the right mouse key into the serverlist window will give you a menu where you can fetch new servers via HTTP from websites with server lists. Those will be added to your own serverlist.

There are always some hundred donkey-Servers online.


Serverlist options --- Always stay connected --- Dead servers

4.6 Searching

Enter search terms into the entry field in the toolbar at the top of the GUI window. You can only search for whole words, and each word needs to be at least three characters long. Search terms cannot contain special symbols like & (ampersands), underscores, etc.

Hit enter or click on the 'Go!' button to start the search.

If you are using eDonkey, you can click on the little arrow left of the entry field in the GUI toolbar at the top. This should reveal a number of additional search options (file type, file size etc.). Overnet does not support these options yet with the GUI.

eDonkey2000: The server you are connected to will answer in a time between one and many seconds (sorry to say that, but some servers are overloaded and really need some time to answer, mostly because of network bandwith), so be patient. After you received a search result (no files found is a result, too), you can click extend search to ask five more servers. Click more times to ask more and more servers.

Overnet: Overnet doesn't use servers, but it will find your stuff anyway. Overnet is a decentralised network, and consecutive searches for the same thing might differ at times. If searching does not work for you at all with overnet, check your UDP network setup and make sure you do not block UDP packets from/to ports higher than 1024.

Double-click search items to download them or use the right-mouse-button-menu.

Note: There is no extend to all servers button and there will be none, as the servers maintained by donkey users can't take the load of every user asking every server for results, as the eDonkey Bot (for windows) did. The network was under heavy stress at that time and many server admins really got angry, having to lower the maximum user limit further every day. Do not ask for this feature to be implemented; I will not do it.

If you search for something which will return a lot of results (e.g. 'mp3'), you will find that you only get 200 results at a time from your main server. If there are more results available, the 'more' button will be active, and you will be able to get the next 200 results by clicking on it.

You can 'blacklist' items. These items will not be shown among any future search results should they be returned as result again. The GUI keeps the blacklisted items in the file 'gui_blacklist' in the '.ed2k_gui/' sub-directory of your home directory.

The GUI is also able to filter out files that contain certain words or substrings (a substring is just a sequence of characters, whereas a word is a sequence of characters surrounded by certain delimiters such as the space character or parentheses). You will need to create or edit a file called 'gui_filters' in the '.ed2k_gui' sub-directory of your home directory (note that this is a hidden directory, so it might not show up in your file manager unless you explicitely tell it to show hidden directories). This file should contain exactly one filter phrase per line. If a line starts with a '*' (asterisk), the GUI will filter out all search results which contain the specified phrase as a whole word. If the line does not start with an asterisk, the GUI will filter out all results that contain the given substring in their filename. Example:


in your gui_filters file will filter out all results containing 'de' and 'sex' as a word (like 'sex in the bathroom (de).avi'), but not results like 'fun in essex.avi' or 'deranged band - deranged song.mp3'.

Other ways to find files and ways to tell friends about files you are sharing

One way to find files on the eDonkey2000 network is by searching the network as described above. This, however, is not always the best way to find files, because ...

The good news is that every file on the eDonkey2000 network has a unique identifier, which consists of a 'hash' (basically a very very large number) which is unique to each file, and the file size. These two bits of information are enough for eDonkey to find a certain file on the network. By passing this information, you can for instance tell a friend about a file you are sharing, and he/she will be able to find this file without using the search. This information is usually passed on via so-called 'ed2k-links'. ed2k-links look like this:


The first parameter is the filename, the second parameter is the file size in bytes, and the third parameter is the file hash in hexadecimal form and will always have exactly 32 digits, with digits from 0-9 and a-f.

In the downloads list, the search results list, and the shared files list you can right-click and select the 'write ed2k-link to log/clipboard' option. This will copy the ed2k-links associated with the selected files to the clipboard.

Please refer to the Question and Answer section on how to use ed2k-links that you have received from other people with the GUI.

There are dedicated websites that collect and publish ed2k-links. The advantage of using these links are that the files refered to there are often widely available and thus easy and fast to download, and that often there is additional information available about these files.

Here are two sites that might get you started:

A word of caution: do resist temptation, don't go wild(e).

There are also search engines for the eDonkey2000 network that contain result caches and that will tell you about general availability of a file right away. Try Jigle or filedonkey.

4.7 Maintaining downloads

What the 'dot' colours on the left mean:

   white   this file is paused, queued, or hashing.

   green   this file is completely available on the
           network and the download is active, which
           means it is either downloading or waiting
           to get a download slot somewhere ('Looking').

   red     this file is currently not available on the
           network (or at least we couldn't find any
           sources for it), or there is some kind of
           error with this file (insufficient disk space,
           error loading, etc.).

   yellow  this file is currently not fully available on
           the network, but we know sources that have parts
           that we do not have yet.

   purple  this file is currently not fully available on
           the network, and we have all parts that are
           currently available.

What the colours in the progress bar mean:

   black   you have this part of the file (good)

   green   you do not have this part of the file, but
           we know at least one person who does (good).
           The darker the green, the better.

   red     you do not have this part of the file, and
           we do not know anyone who has this part of
           the file yet (bad). Waiting is the only
           option you have here, really.

   white   does not mean anything. If the file is paused,
           the parts you do not have are white.

What the different download status mean:

   Downloading   as it says :)

   Looking       eDonkey is currently not downloading
                 this file, but is looking for sources
                 (=other people who have this file) and
                 is waiting in other people's queues until
                 it is your turn to download from them.
                 This is normal and you will see this state
                 most of the time. Do not expect immediate
                 downloads. You usually have to wait until
                 you can download from someone, because many
                 other people want files as well.

    Queued       This file is queued locally, meaning eDonkey
                 is not downloading it and is not looking for
                 sources and is not waiting until it can download
                 parts of it.
                 This can happen in different cases. For instance:

                 (a) eDonkey is using a lot of connections already
                     for other files and at the moment does not
                     have enough left to look for this file as well.
                     Increasing your 'max. connections' setting
                     (options page -> core) might help here.

                 (b) you have a lot of active downloads going on,
                     and looking for further sources wouldn't make
                     much sense. Try giving a 'Queued' download a
                     high priority, then it should start Looking...
                     pretty soon (this of course works only if most
                     other downloads are normal or low priority).

   (Hashing...)  This means that we don't have a status for this
                 file, which happens usually just after the GUI has
                 connected to the core, or for a couple of seconds
                 when a block has finished downloading. You shouldn't
                 see this status (_with_ the brackets!) for too long.

   Hashing...    This (without brackets) means that eDonkey is hashing
                 your files to make sure nothing has been corrupted etc.
                 This happens just after you start the core, and it may
                 take a while to finish (depending on your system).

   Paused        You have paused this file. It is not active at the
                 moment and will not download. Resume it to continue

   Insuff.Disk   This means that there is not enough space free in either
    Space        your temp partition or your incoming partition. Note that
                 eDonkey might take a minute or so to notice when you've
                 freed up more space.

TODO: downloading --- pausing --- resuming --- download priority --- x.part filenames --- and the temp directory

4.8 Optimising downloads

There are a couple of things you can do to make sure your download goes smoothly. They have been rehashed many times in the forums (at, so you should have a look there for more details.

Firstly, you should make sure you are not 'firewalled'. You can be 'firewalled' even if you are not running a firewall, for example if you are behind a router/gateway that does NAT/IP masquerading (most DSL routers are set up this way by default). In this case you need to forward the appropriate ports to get an 'open' status (see the Questions and Answers section below for details). In overnet, you can see your firewalled status in the status bar at the bottom if you switch to the status page (the log). In eDonkey2000, your status should also be shown on the servers page. If your status is 'unclear', that means you are either not connected to a server (in eDonkey2000), or you have no contacts (in overnet, see above then).

If you can't get rid of your 'firewalled' status, this is not the end of the world. Things just won't be working perfectly then.

Secondly, make sure your max. upload/download settings are right. Do not upload too much. If you upload too much, your uploads might 'starve' your downloads. Most DSL/Cable lines come with a speed specification for download/upload, e.g. 512/128. Those values are in kbps, so you have to divide them by 8 to get the theoretical line speeds in kB/s. In this case the theoretical max. download would be 64kB/s and the theoretical max. upload would be 16kB/s. You should always leave a bit of space for protocol overhead and other stuff, so in practice you would probably choose to set max. download to 55kB/s (or 0 for unlimited), and max. upload to 10-12 kB/s on such a line. Try different values, your mileage may vary. Just make sure you max. upload setting is not too high.

Thirdly, download popular and well-spread files. For testing purposes, you might try some of the non-copyrighted content from sites like ShareReactor.

4.9 Maintaining uploads

There is nothing to maintain. You can only watch them and feel good about yourself.

You cannot cancel uploads and you cannot not share in eDonkey. Always keep in mind that everything that you download someone else needs to upload. If noone uploads anything, noone can download anything. Noone includes you in these cases.

In a closed network like eDonkey the formula is quite simple: total download at any time = total upload at any time.

Note that uploading takes away nothing from your download speed. Upload and download speeds are more or less independent from each other on a broadband connection (DSL/Cable).

4.10 Tricks with 'advanced commands'

'Advanced commands' are command line commands that can be sent from the GUI to the core (=command line client). You can send them by typing


into the entry widget in the GUI toolbar at the top of the window ("vo" will output your core's options settings; type "!?" into the toolbar to get a list of core commands).

If the donkey started and is trying to connect to any server while you want it to be connected to a specific server, clicking disconnect often does not work. Go to the About screen, type "x" and click send advanced command several times. Then you can connect to your server of choice within one or two seconds even while Always stay connected is checked.

If you need network bandwith fast, you type dumax 1 1 to set down- and upload speed to 1 KB/s. When you're finished, change back with something like dumax 0 10 to set download speed to 0 (unlimited) and upload speed to 10 KB/s (or whatever your settings were before).

4.11 Using ed2k-links

You can start downloads from ed2k-links by passing those links to the GUI. There are four different ways to pass ed2k-links (server links and file links) to the GUI.


You can simply drag'n'drop ed2k-links from your browser into the GUI window. Server links will be added to the server list. File links will either start a new download immediately, or land on the search page in the 'ed2k-links' tab (depending on your options settings). Drag'n'Drop should work with any browser (apart from lynx).


You can also copy one or more links to the clipboard and then paste them into the toolbar.

pipe (for advanced users)

A pipe is something like a file, but not quite. It appears as a file in a directory, but it is directly connected to the GUI, which will immediately receive all output that is being written to that file. This allows you to use system commands to pass an ed2k-link to the GUI, or allows external programs to pass links to the GUI. Example:

   %echo "ed2k://|file|stupid_example.txt|42321|abababababababababababababababab|" > ~/.ed2k_gui/pipe

The pipe mechanism is also used by other programs, like the linkhandlers for KDE and GNOME (see below). (note: with older GUI versions, the pipe used to be /tmp/.ed2k_gui_socket)

link handler for KDE and GNOME

From version 0.5.0 of the GUI onwards, you can register the GUI as a link handler with the KDE and/or GNOME desktop environment. You can do this from the options page. Note that even if you have gnome2, you might also need to install the gnome1 link handler, because not all applications are already gnome2-applications (like galeon).

This will make your desktop environment (KDE,GNOME), start the GUI with the ed2k:// link as first command line parameter whenever you click on an ed2k-link in your desktop environment's browser (konqueror or galeon).

However, this will not work for browsers which do not care about your desktop environment, so this will probably not work for Mozilla or Opera or Safari. Please use drag and drop with these browsers.

4.12 Keyboard shortcuts

Some of the most important pop-up menu functions can also be selected via keyboard shortcuts. These keyboard shortcuts will only be active if the focus is on one of the list rows (which will be the case when you have just selected some rows).

Downloads list keyboard shortcuts

shortcut         function
========         ========

    l            set selected downloads to low priority
    n            set selected downloads to normal priority
    h            set selected downloads to high priority

    p            pause selected downloads
    r            resume selected downloads

    a            select all
    u            unselect all

 <delete>        cancel selected downloads

Search results list keyboard shortcuts

shortcut           function
========           ========

    b              add selected search results to blacklist
    d              download selected search results
    c              download selected search results with custom filename
 n, s, a           set focus to search phrase entry widget
 <enter>           download selected search results
 <shift>+<enter>   download selected search results with custom filename

Servers list keyboard shortcuts

shortcut           function
========           ========

    c              connect to any of the selected servers

    l              set selected servers to low priority
    n              set selected servers to normal priority
    h              set selected servers to high priority

    a              select all
    u              unselect all

Uploads, Status, Options, About, Shared, and Statistics page keyboard shortcuts

None of these pages has any keyboard shortcuts defined yet.

Next Previous Contents