mailing lists

FAQ English

FAQ Deutsch

FAQ Francais


Other projects:




A GUI for the eDonkey2000 and Overnet file-sharing programs on GNU/Linux, FreeBSD, Mac OS X and other *nix systems.
20th May 2005: ed2k-gtk-gui v0.6.4 RPM packages available

The MS Windows version is at 0.6.4 as well now!

Frequently Asked Questions (FAQ)

This documented is outdated. Please consult the Documentation first.

by Tim-Philipp Müller - tim@edonkey2000.com

last updated: 05 October 2002 (recently changed: Q99, Q16).

Latest version of this FAQ should be available from here - dort gibt es auch die FAQ auf Deutsch

Screenshots and more recent development versions of the GUI are available here

If you find any mistakes on this page, please let me know.

Thanks to 'Sy.' for pointing out some severe typos, and everyone who suggested new questions.

This FAQ does not apply to the Java GUI, only to the gtk GUI.
However, the first couple of questions might also help you solve connection problems with the JavaGUI.

Frequently Asked Questions:

(1) GUI? What's that?

GUI = Graphical User Interface
Translate that into: windows, buttons, etc.

(2) What is 'the core'?

'The core' is the actual edonkey program which does everything behind the scenes - connecting to servers, searching, downloading, uploading, all that stuff.

Generally, the 'core' is simply the usual linux command line client. However, if it is started with a special command line option (ie. '-'), it is no longer the usual command line client, but listens on a specified 'admin port' (which you can set in the command line client via the 'aport' command - default is port 4663) for a GUI to tell it what to do.

Usually, you can spawn (=start) the 'core' via the GUI. If, for some reason, this doesn't work or you want to do it manually, you'll have to start it like this in order to make it controllable via a GUI: './donkey - !' or './donkey_s - !' (depending on which binary you use). The exclamation mark/bang is not really necessary, but it saves you from running into difficulties shutting down the core via the GUI.

(3) What's the difference between the 'core' and the 'GUI'?

The core simply does all the stuff. You need a user interface to tell it what to do (ie. connect to servers, do searches, download stuff). The core comes with a very simple text interface (=command line client), where you can tell it what to do by typing in commands like 'c' for "connect" and 'd 1' for "download search result number 1". Most people do not find this very convenient and rather have a window with lists and buttons to click. The 'GUI' is a separate program which connect to the core via a TCP connection and tells it what to do. Likewise, the core sends messages to the GUI when something happens (eg. a download has finished), so the GUI can present this to the user.

The GUI and the core are two totally separate programs in linux. They talk to each other via an internet (TCP) connection and tell each other what they are currently doing. In Windows, the GUI and the core are one program with the core being hidden from the user.

(4) What do I have to do before I can use the GUI for the first time?

If you haven't done so, you'll have to unpack the archive with the GUI files. On the command line, enter 'tar xzf linux_gui_alpha.tgz' (or whatever the archive is called). The extension can be '.tgz' or '.tar.gz', with the former being a shorter way for the latter.

Please note: You should not unpack the GUI archive on a windows vfat partition unless you know what you are doing. Windows partitions in linux are often mounted in a way that prevents the system from executing binaries (=programs) which are on those windows partitions. If you unpack the archive somewhere in your home directory tree or so you should not have to worry about the this permissions business. You can still set your eDonkey temp or incoming folder to be on a windows partition if you want to, as long as you have read and write access to it.

Before you can use the GUI, you'll have to set up an admin username and password. For security reasons, you have to do this manually, but you'll only have to do this once.

You set up an admin username and a passwort by starting the edonkey binary supplied with the GUI manually from the command line [1], and then typing 'pass username password' (and hitting ENTER). Then type 'q' ENTER and 'y' ENTER to quit and make the core save its preferences.

After you've done this, you can start the GUI (ed2k_gui) by clicking on the filename in a file manager or invoking it on the command line. Hit the 'spawn local donkey' button if you want to run the edonkey2000 core on the same machine as the GUI. You can also connect to a core that runs on a different computer, but then you have to start it manually and make it listen to a GUI connection via the '-' command line option (and better also add '!' as another command line option to make sure it can always be properly shutdown via the GUI).

[1] How to start the command line client manually (without being accessible by the GUI): On a console (or x window command line window like xterm), type in './donkey_s' or './donkey' (depending on whether you use the statically compiled binary or not). NOTA BENE: If you have different edonkey binaries on your system, you have to use the one that is supplied with the GUI, and you have to run this from the command line (meaning: change into the appropriate folder first via 'cd /home/joe/myfolder/').

(5) Okay, the GUI starts and there is that 'connect to' dialog - what do I do?

First of all, you'll need an edonkey core running somewhere. Usually this will be the computer you're running the GUI on. There should be a status message above the buttons that tell you if there is already a core running locally or not. If not (which is usually the case), hit the 'spawn local donkey' button to start the edonkey2000 core program. Now the status message should change. If not, you'll have to start the core manually (see Question 2 above). Please report all problems with this to me, including what you did, what values the 'connect to' dialogue showed in all the fields, and the full path to the GUI and the donkey binary.

Second, if you spawned the donkey core alright, you enter the admin username and password into the appropriate fields in the 'connect to' dialog and hit the 'connect' button. Now the 'connect to' dialog should disappear and the GUI should be connected to the core. If this does not happen, there could be the following problems (also check the statusbar of the GUI main window for messages):

    (0) If you have started the core manually, you forgot the '-' option. Start it with './donkey - !'
    (a) You're connecting to the wrong computer ('host'). This should be 'localhost' by default.
    (b) You're connecting to the wrong port on your computer. The default GUI port can be set in the command line client via the 'aport' command, but should be 4663 by default.
    (c) You haven't set a username and/or password with the core manually (see Q4 above).
    (d) Your username/password are wrong (run the core manually and type the 'vo' command to see what they are set to).
    (e) The 'connect to' dialog disappears, but nothing seems to happen. Most notably, the options page shows 'pleasewait' as a nickname: This happens if you connect to the core on the wrong port, namely on the port the core uses as its _data_ port. Start the core manually and type 'vo' to see what the admin port is. Make sure the 'admin port' is different from the 'door port' (=data port). If in doubt, type 'netstat -l' on a console/bash to see on what ports the donkey is listening. It should be one of those.
    (f) If you're trying to control a GUI on a remote host, chances are that there is a firewall between you and the remote host that blocks all TCP connections on the admin port. If this is the case, you have to check your firewall settings and allow these connections or try a different port as an admin port.

Third, you're connected, and the options page does NOT show 'pleasewait' as a nickname. This is a very good sign, meaning that the GUI and the core can actually talk to each other. Now you should be able to do whatever you want: Go to the servers page and connect to a server first. Then you can search and start to download things. If you right-click on the list-entries you'll get all the available actions. Don't forget to share.

(6) I can connect to the core, but nothing seems to happen - what's wrong?

Check if the options dialog shows 'pleasewait' as a nick. If yes, see Question 5e above. If no, I don't know what's wrong. Please mail me or post a report in the edonkey2000 bugs forum in the appropriate bugs thread (and only there please, otherwise I might miss it).

(7) Why does the linux GUI not show the nice progress bars etc like the windows version?

Because it's an alpha version. Please be patient, those features will be implemented over time, but first I'd like to make sure the basic functions work.

(8) How does the binary supplied with the GUI differ from the 'official' version?

It doesn't. Not very much anyway. If they differ, then the donkey binary supplied with the GUI is more up-to-date, possibly having some new functions that are needed by the GUI which are not yet in the last official linux command line client release.

(9) Why do you only supply the statically linked 'donkey_s' with the GUI?

Because it's easier and makes the downloadable archive smaller. Also, everyone who can run the dynamically linked binary can also run the statically linked one, but not vice versa. Simple as that.

Some people have claimed that the dynamically linked binary 'donkey' runs faster than the statically linked binary 'donkey_s'. Personally, I think this is close to nonsense in practice, not only due to theoretical reasons, but also according to some runtime tests I made. Anyone who wants to convince me of the opposite is welcome to mail me reproducable runtime tests and results (on post-486 machines, please). :)

(10) What's saved in the 'gui_options' file?

The 'gui_options' file simply contains all your _GUI_ preferences (ie. last GUI window size, size of the columns in the different tables, your GUI options like 'shutdown core on exit'/ 'confirm cancel' etc. However, it also contains your default username/password to connect to the core, so this file should be made readable/writable only for the user who uses the GUI and not be readable to others and/or the users' group (use the chmod command to change this if necessary).

(11) What about the 'gui_lookuplist' file?

This file contains a list of names of edonkey2000 servers that are not on static (=fixed) IPs. When you start the GUI, it will read this file (one hostname per line) and resolve the hostnames specified there to the current server IP. These servers will be removed from the edonkey2000 serverlist when the GUI shuts down the core.

(12) What about filters?

Filters for search results (e.g. automatically filter out all search results which contain the word/substring 'do_it_to_me_baby') are not implemented yet, but will (hopefully) be implemented in one of the next releases.

(13) Will my downloads stop when I close the GUI / when the GUI crashes / when the X server crashes?

Usually, they won't. It all depends on how the core was started. If you started it manually from an xterm window withing X, chances are that it will stop when the X server crashes/ is shutdown. Ususally, however, the core will go on downloading until it is explicitely shut down by the GUI (either on exit if you have the 'always shutdown core on exit' box ticked) or it is manually killed from the commandline or you shutdown your computer or the core crashes (does happen from time to time ;)).

(14) Suddenly, for some reason, the 'connect to' dialog re-appers - what's wrong?

This happens if the connection between the core and the GUI is disrupted, which in most cases means that the core has crashed, or - if the core is running on a remote host - that your internet connection is broken/has been disrupted.

(15) Why didn't you write a proper KDE program?

There are a couple of reasons for this.

First, one advantage of linux over windows is the fact that linux users have a choice as to what they prefer to run as their X window server, X window manager, desktop system, etc. You might think that KDE is simply the best (and, yes, I use KDE, too), but others might not. Now my aim was to produce something which runs on as many different installations as possible, and I found that the gtk+ toolkit was the best smallest common denominator if one wanted to avoid direct xlib programming. It is almost a standard on any system which installs X window. KDE is not. (what was the liberals' argument again? Something has value because one chose it... ;) )

Secondly, I wanted to produce something which could more or less easily be ported to other systems (windows, BeOS, Mac OS X) and architectures. It is true that Qt exists for a variety of systems as well, at the moment, however, there seem to be licensing issues on non-linux systems which have to be taken into account.

Thirdly, I don't know much C++, and as I was writing the program during my final uni exams, I figured that I'd rather come up with something usable if I do it in C, than if I start learning C++ first. Simple as that.

(16) Why is the GUI not open source? (deprecated)

The GUI is open source now and licensed under the GNU Public License (GPL). The project homepage is here: http://ed2k-gtk-gui.sourceforge.net

(17) German and other international characters...

are not shown correctly by the GUI? Symptom: When trying to display a string with an international character, the string is cut off at the point where the special character is supposed to be.

If this happens, you are probably using KDE2. Do the following to fix this problem:
Go to the KDE Control Center / Look&Feel / Style, and untick the box 'Apply KDE fonts and colors to non-KDE apps'. Then click the 'Apply' button and restart the GUI. The problem should not occur any longer now. If it does, see if you have a file in your home directory called '.gtkrc' (it's usually hidden, so use 'ls -a ~' to see if it's there). If yes, open it in a text editor and uncomment the line 'fontset' (to '#fontest'), then save it and restart the GUI again. Now it should definitively work!

The same in German: I'm very grateful to the SuSe knowledge database for this hint.

(18) Can I run two GUIs controlling two different cores at the same time?

Yes, you can, but you'll need to put both GUIs in different directories (e.g./home/joe/ed2k_gui1/ and /home/joe/ed2k_gui2). Why you need to do this? Because the GUI regularly saves its options (into gui_options), the upload and download statistics (into gui_uploadstats), and possibly the status window output (into gui_statuslog). Of course you could start the same binary in the same directory twice, but then both would regularly overwrite the above mentioned files with their own values. Which doesn't really matter if you don't care about keeping your options settings or if you don't mind that the statuslog is confusing and mixed up. However, if you do, you should run both GUIs in different directories.

(19) Can two people controll a core a the same time?

Or: What happens, if I'm running the GUI and controlling the core, and my flatmate starts another GUI on his computer and wants to connect to and controll that same core (e.g. on a gateway/router) as well?

This is not possible. Only one person can control a core at the same time. If your GUI is connected to the core, and someone else tries to connect to it as well, the core will send you a message 'Another control attempt'.

(20) How reliable are the upload and download statistics? (upcoming version)

They aren't reliable at all. They are there for the bored, the curious, and the control freaks ;)
A couple of things you should know about those statistics:

First, they are produced by the GUI alone, in other words: if you close the GUI and keep the core running, the core will continue to download and upload. These downloads and uploads will never make it into the statistic! Only downloads and uploads that occur while the GUI is connected will make it into the statistics.

Second, they are estimates. How does it work? The core regularly sends out the current upload/download speeds for all the up- and downloads. Currently, the GUI receives a speed value every three seconds. Now the GUI says: 25kB/s is the speed, let's take that as the average (which it isn't!) over the last three seconds, then we've transferred 75kB in 3 seconds.

This is a very rough way of estimating, but very easy as well. It should work pretty fine with normal download and upload speeds, ie. for 95% of the people. It will not work fine on an internal LAN where you get download and upload speeds of up to 750kB/s. In short: The higher the speeds, and the shorter the downloads, the less accurate it gets.

Addendum: What is the ul/size ratio supposed to tell me?

Honestly, I don't know. I like to think about it this way:
What does the amount uploaded tell us? How popular a file is in comparison to others, right? (There are some assumptions about equal average chances and equal average slot sizes for all people who want a file made, but I think it's safe to assume that those are true over a longer period of time.) Let's also assume that we upload because we want to make other people 'happy' (happier that should be, but who cares). Then if we need to remove a shared file to free some space on our harddrive, we look at the upload stats and remove those which are least in demand. But: This would only serve our purpose (increase happiness of others) if we assume that happiness increases with the amount transfered (at least that's the implicit assumption).
Now one could take a different perspective and say that happiness is not dependent on the amount transfered, but on the number of items completed (or, in other words, marginal utility per MB transferred decreases with filesize). A single episode of "My 14 Days on an exchange program in Paris - a Diary" would therefore increase happiness exactly as much as your "Exploring the Louvre" which is ten-times the size of one your diary episodes.
If we go with this, then the ul/size factor is the indicator to consult

Anyone have any other daring interpretations? ;)

(21) What does the stuff in the statistics status line exactly mean?

First of all, be advised that all this statistics stuff is totally unreliable, buggy, and experimental. If you notice weird stuff going on, please tell me about it, but don't be suprised.

Lets take the line 'Total upload: ~17.63G in 11.5 days (~1565.3M/day) - actual: ~220.2kB/s, uploading 8.4% of the time (23.3h)' - what does it mean (assuming it worked alright)?

It means that the GUI has watched the core upload around 17GB since the statistics were last cleared 11.5 days ago. If the core runs in the background without the GUI being connected to it, it will still upload, but the GUI won't know about this, so it can't take it into account. The 11.5 days is the time since the stats have been cleared the last time. It does not mean that the core or the GUI have been running for 11.5 days. If you clear the stats, go on holiday for two weeks, come back and start the GUI with core, it will display '0 GB in 14 days', even though the computer was switched off during that time.

Now, the '23.3h' should be the time when the GUI was connected to the core and has seen the core actually upload (total upload speed > 0kB/s). 23.3 hours is 8.4% of 11.5 days. And the 'actual speed' of 220.2kB/s means that the average upload speed should be around 220kB/s, taking into account only the times when it is actually uploading.

(22) What exactly does the 'exec command on download complete' function do? (upcoming version)

If you specify some command there, the GUI will invoke a shell via system() and execute the command(s) you specified. The GUI will export two environment variables: $ED2K_FN contains the name of the file that's just been completed, and $ED2K_IN contains the path to the incoming folder. The GUI will attach these exports in the form of 'export ED2K_FN="filename" && export ED2K_IN="/mnt/daten/incoming" && [your string here]'.

What you do with this function is up to you. You can do basically everything ;) But please note, that this function is experimental, so if you don't know exactly what you are doing and what the worst thing is that could happen to your system if something goes wrong, then please don't use it. Please send bug reports to me.

a simple example: I've put in my 'exec on complete' entry field the following entry:
echo -e "$ED2K_FN\n~.\n" | mail -s "Download complete, dude" tim
which sends me an e-mail on my local system every time a download is complete. If your mail system is set up properly, you can also use an external address like dude@wakeup.com. You might have to/want to use 'procmail' or 'sendmail' instead of mail. If you have any cool, sophisticated examples, please let me know :-)

another example:
echo "$ED2K_FN has been completed!" | smbclient -M JOHANNA sends a popup-message to the client on the internal network known as JOHANNA (//JOHANNA) on the Windows Network Neighborhood.

(23) ed2k-links in linux (upcoming version)

As you probably know, in Windows it's possible to add servers to eDonkey just by clicking on a 'ed2k://|server||4661|' link, and to automatically start downloading files without searching by clicking on a ed2k://|file|Drunk Baby Animation.avi|630116|3490b0765c3467f9e3c5ebcdfc33d251| link.

What do you need for ed2k-links to work in linux? You need a GUI that can handle ed2k-links (e.g. the linux 'C' GUI - currently any development version built Dec 16 2001 and later), and you need a core that supports starting downloads from ed2k-links (currently eg the special core versions that are linked to from my posts in the forum as well as from the gui home page. Currently you can use ed2k-links only via the GUI (or phpdonkey, for that matter), but not simply with the command line client on its own.

With the latest gui development versions (>17/12/01) you should be able to simply drag'n'drop an ed2k-link from your browser into the GUI window. Depending on your gui options, it will start to download right away or be added to the search list first.

How does it work? The GUI listens on a named fifo pipe '/tmp/.ed2k_gui_socket' (like a file on your local file system), and you yourself or other programs can drop single ed2k-links or whole ed2k-link lists into that pipe. On the command line you can do that via a simpel 'echo "ed2k://|file|somefile|size|hash|" > /tmp/.ed2k_gui_socket' or a 'cat linklist.html > /tmp/.ed2k_gui_socket'. Server and file links will be accepted. Depending on your options, the file links will either appear on the search page or be downloaded right away.

Now, the fancy stuff: Koen Bailleul has written a ed2k://-protocol kioslave for kde2. That means that you will be able to click on an ed2k-link in konqueror and it's automatically passed on to the gui just like in windows! Currently (Dec 16), the kioslave is not available yet, as there are still some installation problems that need sorting out, but it's worth checking back to the gui development page regularly.

Other fancy stuff: 'exp' has written an ed2k://-protocol agent for windows. Many people have the linux core and GUI running at home or on their router in the basement, but they mainly work with their windows computers in the kitchen or at work. Using said agent for windows, and installing another small agent on the linux box, it is possible to click on an ed2k-link on your windows machine at work, and have it sent to the GUI/core running on the other side of town. As above, this is not available yet, but check on the gui development home page for updates.

(24) How can I use ed2k-links from within galeon or other gnome programs? (upcoming version)

Drag'n'drop should work from Galeon.

If you don't like drag'n'drop, start the gnome control center, choose "URL Handlers" in the "Document Handlers" category. Then enter "ed2k" (without quotes) in the field left of "handler" and as the handler enter

sh -c 'echo $0 >/tmp/.ed2k_gui_socket' "%s"

(exactly as shown here). Then press 'Set' and then the 'Ok' button.

(many thanks to Friedrich Delgado Friedrichs for this tip. Note: what happens if the gui is not running, ie. the pipe does not exist? Maybe one should do a 'test' at the beginning?)

Here's a more sophisticated version to provide GNOME-apps with ed2k-link handling.
(Thanks to Veit Wahlich)

(25) Is it possible that the windows version downloads better/faster than the linux version?

Everything is possible. Fact is, it is very hard to make proper comparisons. Even if the settings are exactly the same, most donkey users will probably agree that downloadspeed can be a function of virtually anything, meaning it can be totally random. Maybe you just caught a good time with your windows client and a bad one with your linux client. I've heard the "people, get the linux client, it's so much faster" just as often as I've heard the opposite.

Fact is also, that the code that handles the downloading, uploading, and searching for sources is exactly the same for the windows and the linux client. It's one and the same source code! The problem is that the source code is continually developed, experimented with, changes are made and other changes are reversed. Although the linux client might have the same version number as the windows client, it has usually not been compiled at the same time, so the actual routines can differ between the v58 linux client and the v58 windows client. Additionally, there are usually a couple of different 'unofficial' linux client versions around which are also compiled at different times. You just have to try them and see which one works best for you (if there wasn't the problem that the newer ones usually have bugs fixed or new features ;).

(26) The GUI crashes immediately under Suse 7.x

I don't know what the reason for this is, but a Yast-upgrade (or Yast-update or whatever it's called) should get rid of this problem.

(27) I've updated my core from v57 (bundled with the gui v0.1) to a newer one and now XYZ doesn't work

The reason for this is probably that later versions (v59, not sure about v58) have a different pref.met format and thus do not read in the old v57 preferences correctly. This means that you might have to reset your gui admin username / password, the aport, the incoming and temp directories and other options manually from the command line. After you've done that, everything should work fine again.

(28-96) ... Nothing here yet :)

(97) I have some other problem - what do I do?

Post it to the eDonkey2000 forums (in the Bugs forum or in the Help forum) with the words 'linux GUI' and a short description of your problem in the topic header (so I can easily find it). If that doesn't help, e-mail me .

Please keep in mind that not all problems are the GUI's fault. Some have to do with the core (ie. "I can't connect to any servers"). Some have to do with an incorrectly set up system (firewall, routers etc.) or bugs in system components (libraries,kernel. etc).
So be polite when you report a bug.. Please also use the forum's search function before you post any problems. A lot of problems have been answered there already. In principle, the linux core works just like the windows eDonkey program/core, so the solutions are quite similar, if not the same.

(98) I have found a bug - what do I do?

Please submit the bug to the project's bug-tracking system with as much detail as possible. If you have a sourceforge account, please log in so that I can get back to you if I have further questions about the bug.

(99) This GUI really makes me happy - how can I reward you?

Write me an e-mail. Positive feedback always makes me happy :-)

Also, I've now got an amazon.co.uk wishlist and an amazon.de wishlist in case you feel like getting me a small something for the millions of hours of work I've put into the GUI and the core :-)

ed2k-gtk-gui project home page - ed2k-tools - scentric