
<!doctype linuxdoc system>
<article>
<title>
The ed2k-gtk-gui Handbook
</title>
<author>
Thomas Ritter (<tt>th.ritter <em>at</em> gmx <em>dot</em> net</tt>),
Tim-Philipp M&uuml;ller (<tt>t.i.m <em>at</em> orange <em>dot</em> net</tt>)
</author>
<date>
Version 0.6.2 , Fri Jan 16 21:00:00 BST 2004
</date>
<abstract>
This Handbook describes installation and usage of the ed2k-gtk-gui, version 0.6.0, for the eDonkey2000 or Overnet command line client.
</abstract>

<toc>

<sect>Introduction

<sect1>State of this document
<p>
<bf>This document is somewhat incomplete and work-in-progress. If you cannot find the answer
to your questions in here, please consult the
<htmlurl url="http://ed2k-gtk-gui.sourceforge.net/faq.shtml" name="FAQ"></bf>. However, this
document is more recent and is the only one being updated (the FAQs are available in more languages though).
</p>

<sect1>What is eDonkey2000? What is Overnet?
<p>
<bf>eDonkey2000</bf> is peer-to-peer file-sharing software written by Jed McCaleb (jed <em>at</em> eDonkey2000 <em>dot</em> com) of MetaMachine.
</p>

<p>
<bf>Overnet</bf> is also peer-to-peer file-sharing software, also written by Jed McCaleb (jed <em>at</em> eDonkey2000 <em>dot</em> com) of MetaMachine.
</p>

<p>
Overnet is the new serverless successor of eDonkey2000. From a technological point of view,
Overnet is much superior to eDonkey2000. However, at the time of writing (Januar 2003),
it seems like there is still more content being offered on the eDonkey2000 network. This
situation is likely to change in the future though.
</p>

<p>
Since version 0.5.0, you can use ed2k-gtk-gui also with the overnet command line client.
Almost everything that is written about the edonkey command line client in the following
text also applies to the overnet command line client.
</p>

<sect1>What is a 'GUI'? What is a 'core'?
<p>
Under GNU/Linux, the donkey is different to the well-known Windows
 version - it consists of two parts, the GUI (<em>G</em>raphical <em>U</em>ser <em>I</em>nterface)
 and the core. The <em>core</em> is the part which is responsible for all the file-sharing work (upload, download,
 connecting to servers, publishing files), and the GUI shows us what the core is up to.
</p>
<p>
This separation of GUI and core has several advantages: one is that the GUI does not need to run on the same computer
 as the core. This way you can remote control a core running on your linux router in the basement with a GUI running
 on your main computer in the living room, or from work, or from a friend's house (see security considerations in the
 last section); another advantage is that when
 the GUI crashes *cough* which of course never happens *cough*, then the core will happily continue to download
 and upload, and you only have to restart the GUI.
</p>

<p>
Help with the documentation is always welcome, please send errors,
 comments and suggestions to Tim-Philipp Müller (<tt>t.i.m <em>at</em> orange <em>dot</em> net</tt>).

</p>


<sect1>Changes
<p>
<bf>2002-Nov-09</bf>
<em>merged Thomas Ritter's initial version of this document with the one in the source tree [Tim]</em>
</p>
<p>
<bf>2003-Jan-31</bf>
<em>updated the handbook to reflect changes in 0.5.0 and include some comments about overnet [Tim]</em>
</p>
<p>
<bf>2003-Sep-04</bf>
<em>updated the handbook for v0.6.x [Tim]</em>
</p>
<p>
<bf>2004-Jan-16</bf>
<em>updated the handbook for v0.6.2 [Tim]</em>
</p>

<sect>Installation (GUI)
<p>
You will need get and install both the GUI and the core. This section will tell
 you how to get and install the GUI. The next section will tell you how to get
 and install the core.
</p>
<p>
The GUI is only a Graphical User Interface (read: windows and buttons) for the eDonkey2000 command
line client. The eDonkey2000 command line client is not open-source, but proprietary software which you have to
obtain separately. Without the command line client (='core'), the GUI does not make much sense. <bf>Get a core from here</bf>:
<htmlurl url="http://ed2k-gtk-gui.sourceforge.net/core.shtml" name="http://ed2k-gtk-gui.sourceforge.net/core.shtml">.
</p>

<sect1>How to obtain the GUI
<p>
You can get the latest GUI from
<htmlurl url="http://ed2k-gtk-gui.sourceforge.net" name="http://ed2k-gtk-gui.sourceforge.net">.
 If you are lucky, you will find a ready-made .rpm or .deb package for your distribution, otherwise you will
 need to download the source code tarball and compile the GUI yourself.
</p>

<p>
If you're living on the edge, you can also get the latest GUI source code from CVS. CVS stands for Concurrent
 Versioning System and is a client-server system which is used by developers to keep track of changes made to
 the source code over time. The ed2k-gtk-gui has its own CVS server on sourceforge, and developers will
 regularly upload ('commit') the latest changes (bugfixes, new features) to the CVS 'repository'.
 Bugs are always fixed in CVS first, so if you do not want to wait for the next release,
 you can access the CVS and download the very latest version of the source code even before a proper release is made.
 Instructions on how to do this can be found on the GUI
 <htmlurl url="http://ed2k-gtk-gui.sourceforge.net/download.shtml" name="download page">.
</p>

<sect1>Requirements

<p>

<itemize>
	<item>An eDonkey2000 or Overnet command line client (=core)</item>
	<item>gtk+ toolkit libraries (gtk, gdk, pango, atk, glib) (2.x series; please usage pre-made packages if possible)</item>
	<item>gnet library (gnet-2.0.x) (only required if you compile the GUI from source)</item>
</itemize>

In order to <bf>run a pre-compiled binary</bf> you will need the gtk+-2.x libraries on your system.
Just run <tscreen><verb>'locate libgtk2 | grep ".so"'</verb></tscreen> to check. If this returns results, you should
be fine. The GTK+ libraries are installed by default on virtually every linux desktop system that is out there. If you
just want to run a pre-compiled packed GUI, then you don't need to worry about the gnet library.
The GUI packages have libgnet statically linked in, which avoids all kinds of problems.

In order to <bf>compile the GUI yourself</bf> you will not only need the gnet-2.0.x library and the gtk+2.x toolkit libraries,
 but also the respective <em>development packages</em> (header files etc.) of those libraries. Just run
 <tscreen><verb>'pkg-config --libs gnet-2.0'</verb></tscreen> and <tscreen><verb>'pkg-config --libs gtk+-2.0'</verb></tscreen> to check
 if you have them.
If both commands return something else than an error message, you're all set up. Otherwise you will need to install
 the necessary development packages, which usually have a '-dev' or '-devel' suffix.
Look out for packages called 'gtk2-devel' (or 'libgtk2.0-dev' or similar on debian)
 and 'gnet2-dev' ('libgnet2.0-dev' on debian) or similar. Note that there are two versions of GTK+ out there, viz. the ancient
1.2.x-series and the 2.x.y-series. Both versions of gtk+ (1.2 and 2.x) should be able to co-exist without problems.
You will need GTK+-2.x for the GUI. The current GTK+ version is GTK+-2.2.4. Try to avoid GTK+-2.0.x if you can (it's old, that's all).


<sect1>Installation of the GUI from .rpm or .deb package
<p>
Download the package of your choice and use your distribution's package manager to install it. Please refer to
 your distribution's documentation for instructions on how to do this.

<p>
If your distribution is using RPM packages, you usually use the command
<tscreen><verb>
# rpm -i ed2k-gtk-gui-0.6.0-2.i386.rpm
</verb></tscreen>

as root to install the GUI on your system (exact filename might differ).

<p>
If you are using a debian system, install the GUI with
<tscreen><verb>
# dpkg -i ed2k-gtk-gui-0.6.0-1_i386.deb
</verb></tscreen>

as root (exact filename might differ).


<sect1>Compilation and installation of the GUI from source

<p>
Download the source tarball (.tar.gz) and unpack it with
<tscreen><verb>
% tar xzf ed2k-gtk-gui_BLA.tar.gz
</verb></tscreen>

or download it from the CVS repository (see above), and change into the source directory with

<tscreen><verb>
% cd ed2k_gui/
</verb></tscreen>

</p>

<p>

In order to compile and install ed2k_gui on your system, type the following in
the base directory of the ed2k_gui distribution (ie. the directory where the AUTHORS file is):

<tscreen><verb>
% ./configure
% make
% make install
</verb></tscreen>

<p>
Since Ed2k_gui uses autoconf/automake you should have no trouble compiling it. If you are on the
bleeding edge and got your source code via CVS (see homepage), then you will need to run the
./autogen script to produce the ./configure file.

<p>

You will probably need to <em>become root</em> in order to install the GUI on your system. This is
how you do it:

<tscreen><verb>
% su
Password:                   (type in the root password here)
# make install
(loads of screen output follows)
# exit
</verb></tscreen>
</p>

<p>
Now you should be able to run the GUI simply by typing 'ed2k_gui' into a command line window (konsole or xterm or
whatever), or by pressing ALT-F2 in Gnome/KDE and typing 'ed2k_gui' there. <em>However, you still need to install
 the core before you can actually use the GUI. </em> Please proceed to the next section for instructions
 on how to install the core.
</p>

<p>

Should you run into problems please report them to the the author:
 <htmlurl url="mailto:uberdork@users.sourceforge.net" name = "Tim-Philipp Müller">,
or report them in the
 <htmlurl url="http://sourceforge.net/forum/?group_id=61752" name="ed2k-gtk-gui forum">.

</p>


<sect> Installation (core)
<p>
Now that you have the GUI installed, you will need to set up the eDonkey2000
command line client (=core). This has proved to be a bit tricky in the past,
because the eDonkey2000 command line client is basically a windows application
that has been compiled and works on GNU/Linux (and also on FreeBSD in 'linux
emulation mode'), and as such not always behaves very unix-like.

Don't be discouraged by all the details that follow. Most people never have any
major problems.

<bf>Quick-Start:</bf> The quickest way to get things up and running is to get the latest GUI
version, starting the GUI (by typing 'ed2k_gui' on a command line, or by pressing ALT-F2 in GNOME/KDE
and then typing 'ed2k_gui' there), and then clicking on the
'Quick start' button.

<sect1> Which version of the core should I choose? (can be skipped)
<p>
You might find that there are different versions of the core available. You can get a recent core from here:
<htmlurl url="http://ed2k-gtk-gui.sourceforge.net/core.shtml" name="http://ed2k-gtk-gui.sourceforge.net/core.shtml">.

<p>
Usually you should be fine with using the latest official core (currently this is version 0.50.1).

<p>
Should you get an Overnet core or an eDonkey2000 core? (see introduction) I don't know.
The eDonkey2000 network still seems to have more content than the Overnet network, but
this is likely to change soon. The Overnet network is technologically superior, and it
also is the future ;) Overnet is less hassle in my opinion, because you do not to maintain
a serverlist and all that all the time. You only need to 'boot' into the overnet network
once (using an IP and port of someone who is already on the overnet network), and then
Overnet should really keep its contacts up-to-date on its own.

<p>
Just try them both, and stick with whatever works best for you. Both overnet and eDonkey
can deal with ed2k-links, and overnet can continue the downloads that you started from
eDonkey, and vice versa, so that you can switch back and forth without problems.


<sect1> Downloading and unpacking the core

<p>

Get a recent core from here:
<htmlurl url="http://ed2k-gtk-gui.sourceforge.net/core.shtml" name="http://ed2k-gtk-gui.sourceforge.net/core.shtml">.

<bf>Download it to a subdirectory of your home directory</bf>, e.g. <tt>/home/joe/ed2k</tt>.

Then <bf>unpack it</bf> from the command line (you can do it differently as well of course, if you know how):
<tscreen><verb>
% cd /home/joe/ed2k/
% tar xzf donkey0.50.1.tar.gz   (exact filename might differ)
</verb></tscreen>

You should now have a donkey binary in that directory, and it should be executable, i.e. have the
'x' flag set (if not, set it with <tt>'chmod +x donkey0.50.1'</tt>):
<tscreen><verb>
% ls -l donkey0.50.1
-rwxr-xr-x    2 tim      tim       1159400 Jun 28 19:10 donkey0.50.1
</verb></tscreen>



<sect1> Quick-start - Getting everything to work as quickly as possible

<p>

This will only work if you are planning to run the GUI and the core on the same computer. If the core runs
 on a different computer than the GUI, you will need to set up the core manually. Please refer to the
 next section for instructions on how to do this.

</p>

<p>

<itemize>
	<item>
	  You have downloaded and installed the latest GUI as described above. Good.
	</item>
	<item>
	  You also have a core and have unpacked it as described above. Good.
	</item>
	<item>
	  Start the GUI (by typing <tt>'ed2k_gui'</tt>).
	</item>
	<item>
	  Put the full path to the binary, e.g. '/home/joe/ed2k/donkey0.50.1' into the 'path' field
	  of the 'connect to' dialog.
	</item>
	<item>
	  Choose an arbitrary username and password. Avoid special characters.
	</item>
	<item>
	  The hostname should be 'localhost' and the port should be 4663.
	</item>
	<item>
	  <tt>'ping localhost'</tt> should work. If not, then either use '127.0.0.1'
	  as the hostname, or (better) put a line with '127.0.0.1 localhost' into your
	  /etc/hosts file.
	</item>
	<item>
	  <tt>'netstat -ln | grep 4662'</tt> should not display any output.
	  If it does, don't worry and see if the GUI will detect it and fix it.
	</item>
	<item>
	  <tt>'netstat -ln | grep 4663'</tt> should not display any output.
	  If it does, don't worry and see if the GUI will detect it and fix it.
	</item>
	<item>
	  Hit the 'spawn' button. The dialog should display 'running' now. Hit the 'Go!' button.
	</item>
	<item>
	  You should now be connected to the core properly. Make sure that on the 'Shared'
	  page there is at least one directory listed. If that is so, you are ready to go.
	</item>
	<item>
	  Right-click on the server list and fetch an up-to-date list of servers and connect to one.
	</item>
</itemize>

If this procedure does not work, please look at the status page of the GUI for any hints on what
went wrong and consult the rest of the documentation (FAQ and the sections below) on how to
set up the core manually.




<sect1> If things don't work right away - setting up the core manually
<p>
I need yet to be written.




<sect> Usage <p>

<sect1> Running the GUI for the first time

<p>
<bf>Starting the GUI:</bf> 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

<tscreen><verb>
%ed2k_gui
</verb></tscreen>

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.
<p>
Alternatively, in Gnome or KDE, just hit Alt+F2 and then enter 'ed2k_gui' into the window. That should
start the GUI as well.

<p>

If you are <bf>running the GUI for the first time</bf>, 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.

<p>

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


<sect1> Sharing files

<p>

eDonkey2000 is a file-sharing program, so you should share some files. Note that <bf>it is not possible
 to not share files</bf> 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.

<p>

It is not possible to share individual files, you can only share whole directories or directory trees.
When you click <em>Shared</em> 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 <em>path</em> window and select either <em>add directory
 to share</em> or <em>add directory tree to share</em>. The latter shares a directory
 with all its subdirectories.

<p>
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.

<p>

<em>Please share some content!</em>

<sect2> How many files should I share?

<p>

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.

<p>
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.

<sect1> Configuration

<p>

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

<p>

<em>Maximum download speed</em> and <em>maximum upload speed</em>: 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 <tt>max. upload * 3</tt> or <tt>max. upload * 4</tt> (depending on the speed).

<p>

If you have a DSL/Cable connection, you will usually be told your max. download and upload speed in
 kilo<bf>bit</bf> per second (kbps), for example 576/288. Divide these numbers by eight to get your
 line speeds in kilo<bf>byte</bf> 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).

<p>

<em>Maximum number of connections</em>: 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.

<em>Incoming directory</em>: 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.

<em>Temp directory</em>: 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.

<sect1> Connecting to the overnet network for the first time (bootstrapping) (Overnet only)

<bf>This section only applies to Overnet, not to eDonkey2000.</bf>

<p>
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'.

<p>
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.

<p>
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.

<p>
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 1.2.3.4 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 irc.psycholand.org
with an IRC client (IRC = Internet Relay Chat).

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


<sect1> Maintaining your server list (eDonkey2000 only)

<bf>This section only applies to eDonkey2000, not to Overnet. Overnet is a serverless network.</bf>

<p>
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.

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

<p>
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.

<p>
There are always some hundred donkey-Servers online.

<p>

<bf> TODO: </bf>

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


<sect1> Searching

<p>

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 &amp; (ampersands), underscores, etc.

<p>

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

<p>

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.

<p>
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 <em>extend search</em> to ask five more servers. Click more times
 to ask more and more servers.

<p>
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.

<p>

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

<p>

<em>Note:</em> There is no <em>extend to all servers</em> 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.

<p>

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.

<p>

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.

<p>

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
 <em>as a whole word</em>. 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:

<tscreen><verb>
deutsch
german
*de
*sex
</verb></tscreen>

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'.


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

<p>

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 ...

<itemize>
  <item> files can be fake (i.e. being shared under one name, but in reality be something completely different)</item>
  <item> you do not always know everything about the file that you want to know (e.g. the quality of a film or its language)</item>
  <item> servers are sometimes overloaded and searching becomes painfully slow</item>
</itemize>

<p>

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:

<tscreen><verb>
ed2k://|file|some_fictitious_example.mp3|3949232|ab349abf7b531c21980a0f22eeef7e21|
</verb></tscreen>

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.

<p>

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.

<p>

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

<p>

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.

<p>
Here are two sites that might get you started:

<itemize>
  <item><htmlurl url="http://www.google.com/search?hl=en&amp;ie=ISO-8859-1&amp;q=sharereactor&amp;btnI=I%27m+Feeling+Lucky" name="ShareReactor"></item>
  <item><htmlurl url="http://www.filenexus.com" name="FileNexus"></item>
  <item><htmlurl url="http://www.google.com/search?q=ed2k%20links" name="google for 'ed2k links'"></item>
  <item><htmlurl url="http://www.varkoume.com/donkey/index.php" name="music donkey">
</itemize>

A word of caution: do resist temptation, don't go <htmlurl url="http://www.amazon.com/exec/obidos/ASIN/0231104561/" name="wild(e)">.

<p>
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
 <htmlurl url="http://jigle.com" name="Jigle"> or
 <htmlurl url="http://www.filedonkey.com" name="filedonkey">.


<sect1> Maintaining downloads

<p>
<bf>What the 'dot' colours on the left mean:</bf>
   <tscreen><verb>
   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.
   </verb></tscreen>

<p>
<bf>What the colours in the progress bar mean:</bf>
   <tscreen><verb>
   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.
   </verb></tscreen>

<p>
<bf>What the different download status mean:</bf>
   <tscreen><verb>
   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
                 downloading.

   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.
   </verb></tscreen>


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

<sect1> Optimising downloads

<p>

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 http://forum.overnet.com), so you should have a look there for
more details.

<p>
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).

<p>
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.

<p>
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.

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


<sect1> Maintaining uploads

<p>

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

<p>

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.

<p>

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).


<sect1> Tricks with 'advanced commands'
<p>
'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

   <tscreen><verb>
   !vo
   </verb></tscreen>

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

<p>
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.

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


<sect1> Using ed2k-links

<p>
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.

   <sect2> Drag'n'Drop

   <p>

   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).

   <sect2> Clipboard

   <p>

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

   <sect2> pipe (for advanced users)

   <p>

   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:

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

   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)

   <sect2> link handler for KDE and GNOME

   <p>

   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).

   <p>

   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).

   <p>

   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.


<sect1> Keyboard shortcuts

<p>

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).

<sect2> Downloads list keyboard shortcuts

<p>
<tscreen><verb>
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
</verb></tscreen>

<sect2> Search results list keyboard shortcuts

<p>
<tscreen><verb>
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
</verb></tscreen>


<sect2> Servers list keyboard shortcuts

<p>
<tscreen><verb>
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

</verb></tscreen>

<sect2> Uploads, Status, Options, About, Shared, and Statistics page keyboard shortcuts

<p>
None of these pages has any keyboard shortcuts defined yet.




<sect>Questions and Answers, Tips'n'Tricks<p>

<sect1> Frequently Asked Questions (FAQ)
<p>

For now, please look at the FAQ (available in English, German, and French)
<htmlurl url="http://ed2k-gtk-gui.sourceforge.net" name="on the project homepage">.

<sect1> Using a http-proxy to fetch serverlists via http
<p>
If you have to use a http proxy server for web access and want to make the GUI use
this proxy server whenever you fetch new serverlists via http, set the environment
variable 'http_proxy' before you start the GUI from the shell (=command line):

<tscreen><verb>
export http_proxy=http://wwwcache.somehost.net:8080/
</verb></tscreen>

Note the <bf>slash at the end</bf>. Other programs like wget and lynx will honour this
setting as well if the variable is set. You can check if the variable is set with
the <tt>echo $http_proxy</tt> command.

The best thing is probably to put the above export-line at the end of your &tilde/.bashrc file,
then you don't have to type it in every time you start the GUI, but the environment variable
'http_proxy' will automatically be set every time you login.

<sect1> Corruption found in XYZ in at N

<p>

This means that after completing a part of the file, the checksum ('partial hash') of the
this part of the file on your harddrive does not match the checksum that it should have.

<p>

This is nothing to worry about. eDonkey/overnet has realised the problem and will
download this part again.

<p>

Data corruption just happens. There is nothing you can do about it. Don't worry about it.
However, if this happens very very often with many different files, there might be some
hardware problem on your side (faulty RAM, faulty harddrive, faulty controller, faulty
IDE cable, problems due to overclocking, overheated system, problems with the filesystem,
etc).


<sect1> Changing the default browser that the GUI invokes

<p>

By default, the GUI will search for a browser on your system and use the first it can
find (of Galeon, Konqueror, Mozilla, Netscape, Opera). If you prefer a specific browser,
then you should set the environment variable 'BROWSER' before you start the GUI from the
shell (=command line):

<tscreen><verb>
export BROWSER=/usr/bin/konqueror
</verb></tscreen>

You need to specify an absolute path to the binary. You can find out this path by using
either the <tt>whereis konqueror</tt> or the <tt>which konqueror</tt> command (note:
<tt>which</tt> might not always find your binary because it has hard-coded paths).

The best thing is probably to put the above export-line at the end of your &tilde/.bashrc file,
then you don't have to type it in every time you start the GUI, but the environment variable
'BROWSER' will automatically be set every time you login.


<sect1> Customising the preview script

<p>
The latest GUI version lets you 'preview' ongoing downloads before they are finished if
your core communicates the x.part temp filenames to the GUI (all recent versions should
do that) and if your core is running on your local box.

If you run the 'preview' function for the very first time, the GUI will write a default 
preview shell script to your harddrive. This preview script is located at <tt>~/.ed2k_gui/ed2k_gui_preview</tt>.
You can open it in a normal text editor and customise it according to your own preferences.

Here is how it works: The GUI will call the script and will pass the location of the partially downloaded file
to the script as parameter. In the script this appears as <tt>$*</tt> (which basically just means 'replace with
all parameters that I got'). The GUI will also set the environment variable <tt>ED2K_PREVIEW_EXTENSION</tt> to
contain the file extension of the file in lower case (as you can't really easily tell what type of file it is from
a name like /mnt/temp/34.part).

Now the script takes the file extension and looks if it matches any of the preconfigured cases in the <tt>case</tt>-
statement of the script. If it does match, then the variable <tt>PREVIEW_BIN</tt> is set to contain the name of the
program that should be used to preview this file, including any parameters for that program. Then the program for
the filetype is run. As you can see it's dead easy to change your favourite player or add new extensions.

After the preview program has stopped, you will need to press the Enter key in order to close the xterm window which
has been opened to show the output of any preview programs (and that lets you interrupt previewing with Control-C, for
example in the case of mpg123/ogg123).

If you do not want the script to wait after a preview has finished, remove these two lines from the script:
<tscreen><verb>
echo "Finished. Hit <enter> to close this window"
read
</verb></tscreen>

If you want the xterm window to close right away after calling the preview program, remove the two lines above and modify
the line calling the preview program like this:
<tscreen><verb>
$PREVIEW_BIN "$*" &
</verb></tscreen>


<sect1> Using ed2k-links

<p>
Please refer to the section on ed2k-links in the 'Usage' chapter of this documentation.


<sect1> Exec command on download complete

<p>
TODO, see FAQ

<sect1> International characters are not displayed properly in the GUI

<p>
If this is in filenames or servernames, then this is probably due to your
selected locale. You need to figure out how to change your locale to something
appropriate. If you change your locale anyway, please do change it by all means
to use the UTF8 charset, and not ISO-8859-X (e.g. de_DE.UTF8 or similar).

<p>
However, both eDonkey2000 and Overnet are completely locale un-aware, in the sense that
they do not tell the GUI or other clients in which character set a string was encoded.
So you will never really be able to see a filename within the search results exactly the
same way that the other person sees it with any other person in any language. This should
not be a big problem though usually.


<sect1> DNS lookup for servers

<p>
TODO, see FAQ


<sect1> I have a mouse wheel and weird things happen. Why?

<p>
Why? I don't know. Possibly a GTK+ bug. Go to the options page and make sure the
'disable double-click in lists' option is set. That should solve your problems.


<sect1> The 'preview' function is always disabled - what's wrong?

<p>
The 'preview' function of the downloads list right-click pop-up menu
is disabled in two cases:
<p>
(1) no items are selected
<p>
(2) the GUI thinks that the core is running on another computer. The GUI will
assume that this is the case when you are using a differen hostname/IP than
'localhost' or '127.0.0.1' as the hostname of the core (note: more sophisticated
checking for local interface addresses/hostname has been disabled due to user
requests). So for now everything that is not 127.0.0.1 or localhost is non-local.



<sect1> Using several eDonkeys from different computers, all sharing one line/DSL router

<p>
Problem: You can only configure your router to IP-forward a port to exactly one IP address,
so the other boxes can't use the same port and have a high ID.
<p>
Solution: Run each donkey client on a different port (e.g. one on 3662, one on 4662,
one on 5662, one on 6662, etc.), and configure your router to IP-forward each port to the
right IP. Note: you only need to forward one tcp port per client in order to get a high ID.





<sect1> Having multiple cores

<p>
You might have multiple cores running that you want to control either at the same time or at different times.
In this case you probably want to use the '-n' command line option of the GUI, which will run the GUI in
another 'instance', meaning that it will use a completely different set of GUI configuration files. For the
first core, just start the GUI normally. For the second core, pass the '-n 2' option to the GUI. This way
your statistics etc. will be kept clean and separate and you can also configure the GUI to auto-connect to
the core in question on startup.

<sect1> Multiple GUI connections to one core

<p>
This is a problem. A core can only be controlled by one GUI at a time.

<p>
However, there is an easy and free way to solve this problem:
 use <htmlurl url="http://www.uk.research.att.com/vnc/" name="VNC">.

Install a VNC server on the machine where the core runs, and VNC viewers (available for all kinds of platforms)
 on the systems where you want to control the GUI and the core from. Now run the GUI on the machine where the core
 runs, and remote control the GUI on that machine using VNC. One VNC desktop can be shared by multiple users, so
 this should solve your problem. In theory at least, as I haven't tried it myself yet.


<sect1> A small starting skript

<p>
This is my (Thomas) starting script for the donkey, as I was tired of
 changing to the correct dir manually every day... It fetches a fresh
 serverlist, starts the core, waits and then starts the GUI.

<p>
<code>
&num;!/bin/sh
&num; E-Donkey 2000 Starting Script
&num; Start the donkey from its home dir, replace this with your donkey directory!
cd &tilde;/ablage/edonkey
&num; Get server list, try to be tricky
mv server.met _server.met
wget http://ocbmaurice.dyndns.org/pl/slist.pl/server.met?download/server-max.met || cp _server.met server.met
rm _server.met
&num; Start eDonkey in a named screen session (You need GNU screen!)
screen -dmS donkey -- ./donkey - !
&num; Otherwise:
&num; ./donkey - ! &amp;
&num; Wait a little...
sleep 5
&num; start GUI
ed2k_gui -c
</code>


<sect1> Starting the core in the background or via telnet/ssh

<p>
Usually you can just start programs with a '&' at the end in the shell and they will happily run in the background.
With the eDonkey command line client, however, this will not work properly. You might have a similar problem if you
want to start the donkey from a telnet/ssh (don't use telnet, use ssh!) session, but keep it running even if you
log out. 'nohup' doesn't work with the donkey on many systems either.

<p>
For this kind of magic you need the 'screen' utility, which is probably already installed on your system. Check out
 the man page with <tt>man screen></tt>. Here is the summary:

<p>
Start the donkey with

<tscreen><verb>
cd /home/joe/ed2k/
screen -dmS donk ./donkey0.50.1 - !
</verb></tscreen>

The 'cd' is to make sure that the core reads and writes its config files always from/to the same
directory (i.e. /home/joe/ed2k/ here). If you don't do this, the core will write its config
files to the current working directory, which will probably cause confusion at some point.

The '-' option is to put the donkey in GUI mode, and the '!' option is to make the donkey accept commands only
via the GUI, but not from the command line, which you need in order to shut down the core properly from the GUI.

Leave the screen by first pressing Control-A, then Control-D. You should be back in the shell now.

You can go back to the donkey screen at any time with

<tscreen><verb>
screen -d -r donk
</verb></tscreen>

then.




<sect1> All servers say that I am firewalled, but I am NOT firewalled!

<p>
This can have multiple causes. Note that 'firewalled' is not to be taken literally.
'Firewalled' simply means that the other server could not successfully connect to
your client on the configured client port (which is 4662 by default).

<p>
One reason why this could happen is that you are really running a firewall,
either on your computer, or on your gateway/router, and that firewall blocks
the incoming connection attempt from the server.

<p>
Another reason could be that you are using a DSL router or some other router/gateway,
and this router does NAT (= Network Address Translation = IP Masquerading =
Internet Connection Sharing/ICS). NAT is used so that multiple computers on a small
private network can share one internet connection. In this case the 'public IP' from
your ISP is assigned to your router, and all your computers on the private network get
a 'private IP' (e.g. 192.168.x.x or 10.x.x.x). If this is the case, you will need to
configure port-forwarding on the router. You will need to forward tcp port 4662 to the
IP of the computer where the donkey is running. If you have multiple donkeys running on
your network, run them all on different ports and configure port-forwarding for each of
those ports to a different private IP.

<p>
Finally, some servers are misconfigured and do not allow outgoing connections to
non-standard ports. These servers will always tell you you are firewalled, even though
they are firewalled, and not you. This is likely to happen occasionally if you run your
donkey on a different port than the standard port (tcp 4662). However, if really all
servers tell you that you are firewalled, then this is not likely to be the cause of it.


<sect1> I need to use a SOCKS proxy, but the command line client does not seem to support this

<p>
Unfortunately the current command line client does not support a SOCKS proxy server, but you
could try using <htmlurl url="http://tsocks.sourceforge.net/" name="tsocks">, which will provide SOCKS proxy
support for programs that don't have that natively. (It does that by means of a pre-load
library that intercepts the network system calls to connect() and 'redirects' it to a
socks proxy etc.).


<sect1> If your DSL/cable connection gets unresponsive and surfing the web gets a pain

<p>
You might find that after running the donkey for a while your internet connection seems
to get horribly slow, or at least very unresponsive: connecting to a webserver or checking
your e-mail suddenly takes a couple of seconds instead of a couple of milliseconds.

First off: if this can be reproduced with specific servers independent of whether the donkey
is running or not, then the problem is likely to lie elsewhere. If you are using PPP-over-Ethernet
(PPPoE) then you should double-check your network interface's (pppX or ethX) MTU settings (as an
example). If the problem only occurs when the donkey is heavily uploading, read on.

Here is <bf>the problem</bf> in a nutshell: your DSL router has a built-in packet queue, which works quite simple:
the first packet that comes in goes out again first (FIFO). If the packet queue on your router is full, then
the router will just silently drop packets. This is a normal thing to happen, and the TCP protocol deals with
that. The problem is that for each TCP packet that you receive your computer needs to send a small acknowledgment
(ACK) packet to the sender so the sender knows that the data arrives. This mechanism is used to compensate for
lost packets and adjust speeds dynamically with respect to the available network bandwidth. Now if your router's
packet queue is filled up because of the donkey's upload and you want to connect to a websever, then the connection
request (SYN packet) gets sent to the router, which will put it into its queue. But if the queue is full, it will
take up to a couple of seconds until that SYN request is actually sent out to the webserver you want to connect to,
because your router usually can't distinguish between important and unimportant packets. And the same thing is going
to be repeated for each other packet that you send out (e.g. the HTTP-GET request from your web browser).
That's why things get sluggish. What you need to take into account is that even if your upload line speed is
technically 128kbps = 16kB/s (as an example), some of that is used up by administrative information
(headers) of the various protocols involved. So your effective upload line speed is lower,
and your upload can easily fill up even if it looks like it is safely below the upper limit.

<bf>What to do?</bf>

Quite simple: you want something called Quality-of-Service (QoS). Later 2.4.x Linux kernels have this stuff already
built in, you just need to make sure that your kernel has been compiled with full QoS support (in-built or as modules).

The principle is simple: make sure that router's packet queue never fills up. In order to achieve this, you want to
queue all packets that need queueing on your Linux box instead of on your router (note: this will usually not happen,
because the connection between your linux box and the router is so much faster than the one between the router and
the rest of the internet, so the linux kernel will usually just send everything out to the router immediately and
without delay). Now that the packet queue is administered by your linux kernel, you can tell linux to do all
kinds of neat things. For example, you can tell it to give some packets priority over others. Then those packets will
'jump the queue' and be sent out immediately even if other (less important) packets are waiting in the queue. Personally,
I have marked all traffic to the 'interactive' ports 21,22,23,110 (but not 80 because many windows people configure
their donkey to use port 80) and all traffic to my favourite websites and all 'small packets' (SYN or ACK packets usually)
with the highest priority.

A good description by Emmanuel Roger of how to set up this stuff can be found here:
<htmlurl url="http://www.prout.be/qos/QoS-connection-tuning-HOWTO.html" name="http://www.prout.be/qos/QoS-connection-tuning-HOWTO.html">.

From my own experience I would advise you to stay clear of other HOWTOs (like the
<htmlurl url="http://www.tldp.org/HOWTO/ADSL-Bandwidth-Management-HOWTO/index.html" name="ADSL-Bandwidth-Management-HOWTO">),
unless you want a challenge. This and most other HOWTOs that I have found on this issue require you to patch
your kernel source and your iptables source
(e.g. for the IMQ-device), which proves especially difficult if the patches mentioned there don't work with
the latest kernel/iptables releases....

Here's a snippet from my iptables start-up script, in case anyone is interested:

<code>
	##########################################################
	#
	# Quality of Service (QoS)
	#
	# from http://www.prout.be/qos/QoS-connection-tuning-HOWTO-4.html
	#
	##########################################################

	# reset

	tc qdisc del dev eth1 root 2>/dev/null > /dev/null


	# mark packets with size 0-500 (considered interactive traffic)
	#
	iptables -t mangle -A OUTPUT -m length --length 0:500 -j MARK --set-mark 3

	# mark UDP packets as important as well
	#
	iptables -t mangle -A OUTPUT -p udp -j MARK --set-mark 3

	# bigger packets will be marked data traffic
	#
	iptables -t mangle -A OUTPUT -m length --length 500:1500 -j MARK --set-mark 4

	# mark ssh/smtp/pop3 packets also as priority
	# (not http, due to many donkey people using port 80)

	for i in 22 25 110
	do
		iptables -t mangle -A OUTPUT -p tcp --dport "$i" -j MARK --set-mark 3
		iptables -t mangle -A OUTPUT -p tcp --dport "$i" -j TOS --set-tos Minimize-Delay
	done

	# mark favourite sites high priority traffic.
	#
	# slashdot(new) slashdot.org, www.ct.heise.de,
	#	edonkey2000, jigle.com, jabber.org
	#	google
	#
	for i in "66.35.250.150" "64.28.67.150" "193.99.144.71" \
			"198.77.34.120" "212.249.10.246" "208.245.212.108" \
			"216.239.39.101"
	do
		iptables -t mangle -A OUTPUT -p tcp -d "$i/255.255.255.255" -j MARK --set-mark 3
		iptables -t mangle -A OUTPUT -p tcp -d "$i/255.255.255.255" -j TOS --set-tos Minimize-Delay
	done

	# mark whole subdomains important
	#
	# amazon/imdb - sourceforge.net
	#
	for i in "207.171.166.0" "216.136.171.201"
	do
		iptables -t mangle -A OUTPUT -p tcp -d "$i/255.255.255.0" -j MARK --set-mark 3
		iptables -t mangle -A OUTPUT -p tcp -d "$i/255.255.255.0" -j TOS --set-tos Minimize-Delay
	done

	# create root cvq qdisc for our device eth1
	#
	tc qdisc add dev eth1 root handle 10: cbq bandwidth 10Mbit avpkt 1000 mpu 64

	# DL bandwidth = 576 kbits
	# UL bandwidth = 288 kbits
	#
	# Interactive class rate = DL bandwidth / 20 = 29
	# Data class rate = UL bandwidth - Interactive class rate = 259
	#
	# Let's make the latter a bit smaller just to be on the safe side
	# (we don't want a single packet ever to be queued on the router)
	#  => 190, which is much lower than suggested, but works best wor me
	#
	# (1500 is interface MTU?)
	#
	tc class add dev eth1 parent 10:0 classid 10:1 cbq bandwidth 10Mbit \
		rate 29Kbit allot 1500 prio 1 maxburst 10 avpkt 100 isolated weight 100

	tc class add dev eth1 parent 10:0 classid 10:2 cbq bandwidth 10Mbit \
		rate 190Kbit allot 1500 prio 8 maxburst 2 avpkt 1500 bounded weight 1500

	# tell kernel which class we want to send packets to

	tc filter add dev eth1 parent 10:0 protocol ip handle 3 fw flowid 10:1
	tc filter add dev eth1 parent 10:0 protocol ip handle 4 fw flowid 10:2
</code>


<sect1> "Couldn't create Temp File" error message

<p>
That seems to happen with the recent cores. The reason ist most likely that eDonkey/Overnet use
too many file descriptors (one filedescriptor for each open file and each active network connection),
that is more than you as normal user joe are allowed on your system.

<p>
You can check with

<tscreen><verb>
%ulimit -n
</verb></tscreen>

<p>
the number of open file descriptors your user is allowed in total (taking into account <em>all</em>
programs and processes that you are running currently).

You can change that limit by editing the file /etc/security/limits.conf (as root) and adding a line like this at the end:

<tscreen><verb>
tim     hard    nofile  4096
</verb></tscreen>

<p>
'tim' is the username you are using, 'hard' stands for 'hard limit', 'nofile' stands for
the number of open file descriptors allowed, and 4096 is the value (you might want a higher
value, but 4096 should be fine).

<p>
Now you need to check one more thing, which might be slightly different from distribution to
distribution. If you have a file <tt>/etc/pam.d/common-session</tt>, then make sure you have a
line like this in it:

<tscreen><verb>
session required        pam_limits.so
</verb></tscreen>

If you do not have a file like this, add or uncomment the above line in <tt>/etc/pam.d/login</tt>.
If you use gdm/kdm/xdm to login, then you should check whether <tt>/etc/pam.d/gdm</tt>,
<tt>/etc/pam.d/kdm</tt>, and/or <tt>/etc/pam.d/xdm</tt> have this line and add/uncomment it if required.

<p>
After you've edited that file, you need to re-login <em>'properly'</em> (log out from X and
re-login on the konsole or xdm/kdm/gdm). After that if you run 'ulimit -n' in an xterm window,
it should display the new limit and the problem should be solved.

<p>
<em>On Mac OS X</em> the default limit is apparently 256 file descriptors per user. This is way too
little for eDonkey2000/overnet. You can change this limit by typing 

<tscreen><verb>
limit descriptors 4096                      (this is MacOSX tcsh!)
</verb></tscreen>

on the command line and then starting either the GUI or the core from there (this is because this
setting is only inherited by child processes that you start, it doesn't change system wide). You 
can check your limit by typing 'limit' on the command line. (Thanks to anonymous nobody in forums
for this).

<p>
The exact procedure might depend on your system/distribution. Let me know if this needs to be
solved differently on other systems.


<sect1> The GUI doesn't recognise my manually started core!

<p>
For one, did you pass the '-' command line options to the core when you started it? The '-'  command line option
tells the core to listen for a GUI on the specified aport. Without passing it, the GUI will not be able to connect
to the core, therefore the GUI only checks for a running core that has this flag as a command line option.

<p>
Secondly, the GUI expects the core binary to be called 'donkey*', 'overnet*', or 'cdonkey*'
(it only cares about the beginning of the name). If you renamed the program, the GUI will not find it (how would it?).


<sect1> I want to tunnel the gui-core connection via ssh, but the GUI insist on a local
running core if I use 'localhost' or '127.0.0.1' for the local end of the tunnel.

<p>
Two easy solutions: Either use one of the other non-localhost IPs of that box, for instance
the IP of your network card (e.g. 192.168.0.2), or edit your /etc/hosts file and add an
line like 'core.outerspace.world 127.0.0.1' and put 'core.outerspace.world' into the
hostname field of the 'Connect to.."-dialog.

<p>
This is an issue that is unlikely to be 'fixed', by the way, because the decision to insist
on a locally running core in case of 'localhost' has been made on purpose,
namely in order to facilitate joe average newbie user's getting-started procedure.

<p>
<bf>Please also note that the the 'running core detection' only works on GNU/Linux with a mounted /proc filesystem</bf>
at the moment. Users of other Operating Systems (e.g. *BSD, MacOSX) might want to send a patch to fix this :)



<sect1> It says I am firewalled! Which ports do I need to forward in my router?

<p>
In Overnet the default TCP port is 4662, and the UDP port used is chosen randomly on
start-up. You can, however, make overnet use a fixed UDP port with the 'uport' advanced
command. Type '!uport 9876' without the apostrophes into the toolbar entry, and check
by typing '!vo' whether the setting got saved. After that, overnet should use the same
UDP port every time. You should forward the TCP port (4662 by default, or different if
configured differently) and the UDP port after it has been set to a fixed port.

<p>
In eDonkey2000, you only need to forward the TCP port (4662 by default).


<sect1> I have found a bug - what do I do?

<p>
See if you can reproduce it and/or how to reproduce it.

<p>
Check whether the bug has already been reported, and if yes, if it has been fixed already.
Make sure you look at 'all' bugs in the bug-tracking system, otherwise you will be shown
only the open bugs, but not the fixed bugs.

<p>
If you know how to use CVS, please check out the latest GUI version from CVS to see if the
 bug is still present in the CVS version.

<p>
Submit the bug to the
 <htmlurl url="http://sourceforge.net/tracker/?group_id=61752&amp;atid=498271" name="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. Otherwise, please monitor the bug or check back from time
 to time to see if there are more questions.


<sect1> This GUI really makes me happy - how can I reward you?

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

<p>
Also, I've now got an
 <htmlurl url="http://www.amazon.co.uk/exec/obidos/wishlist/1NL5R93EL1WA6" name="amazon.co.uk wishlist">
 and an
 <htmlurl url="http://www.amazon.de/exec/obidos/wishlist/3G88NU8L43WL6" name="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 ;)



<sect>Copyright

<p>

ed2k_gui Copyright 2001-2004 Tim-Philipp M&uuml;ller , t.i.m at orange dot net


This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

<p>
</article>
