Readme for iMule
****************

This is the README file for iMule version 1.4.5.

   Last update on 31 May 2009.

1 About
*******

iMule is a multiplatform ed2k/I2P client, fork of the aMule client,
using the   wxWidgets class library. It was originally forked from the
xMule project,   which in turn was forked from the lMule project. This
is turn was the first   fork of eMule to run natively on Linux and
other Unix-like systems.

2 Installation
**************

Decompress the archive in some directory.

3 Nomad or not nomad
********************

iMule uses configuration files for keeping many informations. These
files   can be kept either in the user's home folder or in iMule's
installation folder.    The latter case is called "nomad", because you
can then install iMule on   a removable disk and launch it from any
computer with the same configuration.    iMule tests the existence of a
file called "thisIsImuleConfigDir" in its   install directory in order
to decide which configuration directory it should   use. If the file
does not exist, then a subdirectory of the user's home   directory will
be used.

   By default, iMule is nomad. You can change this either by removing
the   file "thisIsImuleConfigDir" before running iMule, or by launching
iMule,   unchecking the "nomad" option in the Preferences tab, and
stopping/relaunching   iMule.

4 I2P router
************

iMule uses the I2P protocol for ensuring anonymous transfers. This
protocol is provided by a piece of software : the "I2P router".    You
can get this software here : `http://www.i2p2.de/download'.

   iMule also has an internal I2P router, that can replace the java I2P
router   provided on the link above, but the internal I2P router is not
 as efficient as the java one : it consumes much cpu.

   By default, iMule will try to launch its internal I2P router. You
can change   that in the Preferences tab.

5 First time configuration
**************************

Decide if you want to use the internal router or the external router
(advised).

5.1 Configuration for the internal router
=========================================

Launch iMule and go to Preferences -> I2P connection.

  1. Check the top-most box called "Use internal I2P router" 	This
     enables some configuration boxes : SAM port, I2P proxy port,
     TCP port, UDP port, and 7 other bandwidth options.

  2. Make sure the default TCP and UDP ports are accessible from the
     Internet, 	or enter other values in the corresponding boxes so
     that these ports 	are accessible from internet. Configure your
     firewall and/or your router 	and/or your modem so that they
     are accessible from internet.

     The other following options are not vital :

  3. You can give the IP or the hostname of your router (for instance:
     mycomputer.dyndns.org) 	in the "IP/dynIP" box, after having
     checked the "dynamic address" option.  	This can accelerate the
     starting process of the I2P router.

  4.  Configure the 4 max. bandwidth boxes. They concern the maximum
     total bandwidth 	used by the I2P router, and not only by your
     iMule transfers.

  5. Configure the anonymity level, i.e. the minimum number of I2P
     peers relaying 	your messages (incoming and outgoing). 1 or 2
     are good values. The higher 	the values are, the slower the
     connections will be.

  6. Configure the ratio of your bandwidth you share for relaying
     messages from other 	peers.  CHECK that points 4) and 6)
     allow AT LEAST 16 kB/s of shared bandwidth. This is the minimum
     for a correct running of the I2P network.

  7. You can configure the SAM port of the internal router or keep the
     standard 7656 value 	if no other application is using this
     port. SAM is the protocol iMule uses 	to communicate with the
     I2P router (even the internal router), and is also 	used by
     other softwares, like the anonymous bittorrent software I2P-BT. So,
     when iMule's internal router is launched, other apps can use its
     SAM port 	as they would do with the standard router.

  8. You can configure the I2P proxy port or keep the standard 4444
     value. This is also 	intended for use by other apps such as
     web browser : configure your browser 	to use the HTTP Proxy
     at 127.0.0.1:4444, and it will be able to browse 	eepSites (www
     over I2P) anonymously (check this by browsing www.imule.i2p
     for instance !)


5.2 Configuration for the external router
=========================================

THIS PART HAS BEEN UPDATED FOR I2P ROUTER VERSION 0.6.5.  So, if you
are running an older router, please update it !

  1. You first have to configure your I2P router so that it launches
     the SAM server at startup.  This SAM server is used by iMule to
     communicate with the router.

        * Launch a web navigator and enter the address of the I2P
          router console in the address bar.  This will probably be
          `http://127.0.0.1:7657'.

        * Click on Configuration

        * Click on Clients

        * Check the box near SAMBridge

        * Finally, click on 'Save Client Configuration'


  2. Launch iMule and go to Preferences -> I2P connection. Uncheck the
     "internal router" box.

  3. Enter the IP address of your router in the first text box. It will
     probably be 127.0.0.1 if the router is running on the same
     computer as iMule.

  4. The "port" box is not used anymore by iMule. Do not bother.

  5. Enter the SAM port of your router (if you did not change its
     value, it probably is 7656)

  6. Enter the HTTP Proxy port of your I2P (4444 by default). The I2P
     proxy is used by iMule for downloading information from
     www.imule.i2p (the nodes.dat file for bootstraping peer
     connections, and a version check file).

  7. Configure the anonymity levels of iMule's connections (as
     explained for the internal router).


6 Bootstrapping
***************

iMule is a Peer to peer application, and in order to enter the peers
network,   it has to know at least one other iMule peer on start. The
known peers are   kept in a file named "nodes.dat" in iMule's
configuration directory. On first   use, you can copy the file provided
in the archive into the configuration   directory. You can also click
the "Nodes" button in iMule to try to download   a more recent
nodes.dat file from iMule's website, but before doing so, you   have to
wait until iMule says it has successfully connected to the I2P
network.

   The remaining of this document has been pasted from aMule
documentation and are more or less relevant for iMule (I did not check
everything).

7 Other configuration options
*****************************

   * Go to the "Preferences" tab

   * Enter a nickname or leave as the default value.

   * Enter the "Download Capacity" and "Upload Capacity" according to
     your internet connection. All values in iMule are kiloBytes (kB),
     but your Internet Service Provider's numbers are most likely
     kiloBits (kb).

     8 kiloBits make up 1 kiloByte, so if your Internet Connection is
     768kb Downstream and 128kb Upstream (i.e. German Telekom DSL),
     your correct values are:

     `Downstream:'     768kb / 8 = 96kB, so you enter 96 as "Download Capacity"
     `Upstream:'       128kb / 8 = 16kB, so you enter 16 as "Upload Capacity"

     Anyway, these values are used to calculate the current bandwidth
     usage for display purposes only (mainly for statistics).
     Nevertheless, you need to know them to determine the following
     down/upload limits:

   * Enter "Download Limit" and "Upload Limit"  (IMPORTANT!)

    Download Limit:
          Leave this at 0, which stands for "no limit". However, if
          iMule uses too much bandwidth and causes problems with other
          applications using your internet connection, it would be a
          good idea to limit this to aproximetly 80% of your downstream
          capacity.

    Upload Limit:
          It is recommended that you set this limit to around 80% of
          your actual upstream capacity, in order to avoid degrading
          the performance of your connection.


     Setting the Upload Limit to a value less than 10 will
     automatically reduce your Download Limit after the following
     schema:

     Upload Limit   Max Download
     >= 10          No limit
     < 10           Upload Limit * 4
     <  4           Upload Limit * 3

     NOTE: 56k Modem users: iMule only accepts integral values for these
     settings, you can't enter 1.6 or whatever your sweet-spot setting
     is. Sorry.

   * "Maximum Connections":

     As a general rule, set it to 500 - 2000.

   * "Maximum Sources per File":

     This depends on how many files you tend to download at a time, if
     you     tend to download few files, high values are acceptable,
     otherwise go     for lower values so that all files will be able
     to get sources.

   * Choose the directories you want to share with other users:

     DO NOT SHARE YOUR COMPLETE HARDDISK!

     It is suggested that you either use the "Incoming" folder or a
     seperate     folder for the files you wish to share, to avoid
     inadvertedly sharing     private files.

     If you share more than 200 files, you should consider that some
     servers     have a hard limit due to resource constraints, which
     means that you may     be kicked from them if you share too many
     files or that some of your     files won't be populated to the
     network through that server. So it is not     always a good idea
     to share lots of files.

   * Other:

     The other options are pretty self-explanatory. If you don't know
     what it     does, don't touch it as a general rule. More
     information on getting started     can be found in the iMule wiki:
          `http://www.imule.org/wiki/index.php/Getting_Started'

     Don't forget to connect to a server, or you probably won't
     download too much.

8 Basic iMule Tips
******************

   * *NEVER run iMule as root*.

   * If you are behind a firewall or router, be sure that the ports
     have been     opened. The default ports are _8887_ (TCP) and
     _8886_ (UDP). If     these are blocked, you will have a VERY LOW
     connection, or no connection     at all.

   * Set your temp and shared directories in Preferences->Directories.
     To recursively select a certain directory, right-click over it.

   * *You should NOT share*

        * Your temp download directory!

        * Your /etc directory

        * Probably not your /var, /lib, /boot, or /usr directory

        * Certainly make sure that any really confidential files
          (password files,         private SSH keys, credit card
          numbers :) are *not* shared. So generally         do not
          share your entire home directory, although you might want to
                share some files or directories in it.


   * Remember that you get certain download priveledges with those
     clients     (iMule, eMule, etc users) to whom you upload files, in
     the form of reduced     queue waits.


8.1 Transfer icons
==================

To find descriptions of the various icons found inside iMule, take a
look at
`http://www.amule.org/wiki/index.php/Getting_Started#Icons_and_What_They_Signify'

9 License
*********

iMule is released under the GNU General Public License.    See the
"COPYING" file for details.

10 Developper
*************

mkvore

11 FAQ
******

11.1 I'd like to search for specific file types, what filter stands for which files?
====================================================================================

_File Type_   _Extensions found_
Audio         .mp3 .mp2 .mpc .wav .ogg .aac .mp4 .ape .au .wma
Video         .avi .mpg .mpeg .ram .rm .vob .divx .mov .ogg .vivo
Program       .exe .com
Archive       .zip .rar .ace .tar.gz .tar.bz2 .Z .arj
CDImage       .bin .cue .iso .nrg .ccd .sub .img
Picture       .jpg .jpeg .bmp .gif .tif .png

11.2 What are all those fancy colors in the download progress bar about?
========================================================================

Each download in the the transfers window has a coloured bar to show
current   file availability and progress.

   * Black shows the parts of the file you already have

   * Red indicates a part missing in all known sources

   * Different shades of blue represent the availability of this part
     in the sources. The darker the blue is the higher the availability

   * Yellow denotes a part being downloaded

   * The green bar on top shows the total download progress of this file

   If you expand the download you see its sources with the corresponding
 bar. Here the colours have a slightly different meaning:

   * Black shows parts you are still missing

   * Silver stands for parts this source is also missing

   * Green indicates parts you already have

   * Yellow denotes a part being uploaded to you

   Learning how the progress bar works will greatly help your
understanding of the eD2k network.

11.3 Where can I get more information?
======================================

Here are some links that might be of your interest:

   * iMule forum `http://forum.i2p/viewforum.php?f=30'

   * iMule Wiki `http://www.imule.i2p/trac/wiki'

   * aMule Wiki (documentation pages) `http://wiki.amule.org'

   * aMule forums `http://forum.amule.org'

   * eMule documents `http://www.emule-project.net/home/perl/help.cgi'


12 Want to help?
****************

iMule is a free software project and requires the cooperation of its
users   to improve the quality of the software. We welcome all
contributions to the   project in the form of new features, bug fixes,
feature requests, etc.

   If you are not a programmer you can still contribute by providing
good bug   reports  when you come accross a problem with iMule. A good
bug report gives   the iMule Team information enough to reproduce the
bug (so we can see it in   action) and fix it. If possible, try to
isolate under which the bug occurs   (eg. does it happen on some
specific window, with some specific files, some   specific conditions
etc.) and provide as much detail as you can in your   report.

   If you are a programmer and fix a bug you observe, please send us a
patch or   a note about how you fixed the problem.

13 IRC, Links and Contact
*************************

   *   IRC: Channel #i2p on irc.postman.i2p (127.0.0.1:6668)

   *   iMule homepage

     `http://www.imule.i2p'

   *   aMule related links :

        *       `http://www.amule.org/wiki/index.php/FAQ_ed2k'

        *       `http://www.amule.org/wiki/index.php/iMule'

        *       `http://www.amule.org/wiki/index.php/FAQ_iMule'

        *       `http://www.amule.org/wiki/index.php/FAQ_utils'

        *       `http://www.amule.org/wiki/index.php/Getting_Started'

        *       `http://www.amule.org/wiki/index.php/iMule_problems'


   *   wxWidgets toolkit homepage

     `http://www.wxwidgets.org'

   *   eMule homepage

     `http://www.emule-project.net'


13.1 Legal Notice
=================

iMule is an interface to the ed2k/i2p network. As such, the iMule
developers have   absolutely no control or say over what is transferred
on this medium and   cannot be held liable for any non-personal
copyright infringements or other   illegal activities.

