docs/README

   1
   2                                  -----------
   3                                     aMule
   4                                  -----------
   5                          The All-platform eD2k Client
   6
   7
   8  About
   9 -------
  10   aMule is a multiplatform ed2k client, fork of the eMule client, using the
  11   wxWidgets class library. It was originally forked from the xMule project,
  12   which in turn was forked from the lMule project. This is turn was the first
  13   fork of eMule to run nativly on Linux and other Unix-like systems.
  14
  15
  16  Installation
  17 --------------
  18   See INSTALL file
  19
  20
  21  Configuration:
  22 ----------------
  23   - Go to the "Preferences" tab
  24
  25   - Enter a nickname or leave as the default value.
  26
  27   - Enter the "Download Capacity" and "Upload Capacity" according to your
  28     internet connection. All values in aMule are kiloBytes (kB), but your
  29     Internet Service Provider's numbers are most likely kiloBits (kb).
  30
  31     8 kiloBits make up 1 kiloByte, so if your Internet Connection is 768kb
  32     Downstream and 128kb Upstream (i.e. German Telekom DSL), your correct
  33     values are:
  34
  35       Downstream: 768kb / 8 = 96kB, so you enter 96 as "Download Capacity"
  36       Upstream:   128kb / 8 = 16kB, so you enter 16 as "Upload Capacity"
  37
  38     Anyway, these values are used to calculate the current bandwidth usage for
  39     display purposes only (mainly for statistics). Nevertheless, you need to
  40     know them to determine the following down/upload limits:
  41
  42   - Enter "Download Limit" and "Upload Limit"  (IMPORTANT!)
  43
  44     Download Limit:
  45         Leave this at 0, which stands for "no limit". However, if aMule uses
  46         too much bandwidth and causes problems with other applications using
  47         your internet connection, it would be a good idea to limit this to
  48         aproximetly 80% of your downstream capacity.
  49
  50     Upload Limit:
  51         It is recommended that you set this limit to around 80% of your actual
  52         upstream capacity, in order to avoid degrading the performance of your
  53         connection.
  54
  55     Setting the Upload Limit to a value less than 10 will automatically reduce
  56     your Download Limit after the following schema:
  57
  58       Upload Limit  |  Max Download
  59          >= 10      |    No limit
  60           < 10      |    Upload Limit * 4
  61           <  4      |    Upload Limit * 3
  62
  63
  64     NOTE: 56k Modem users: aMule only accepts integral values for these
  65           settings, you can't enter 1.6 or whatever your sweet-spot setting
  66           is. Sorry.
  67
  68   - "Maximum Connections":
  69     As a general rule, set it to 500 - 2000.
  70
  71   - "Maximum Sources per File":
  72     This depends on how many files you tend to download at a time, if you
  73     tend to download few files, high values are acceptable, otherwise go
  74     for lower values so that all files will be able to get sources.
  75
  76   - Choose the directories you want to share with other users:
  77     DO NOT SHARE YOUR COMPLETE HARDDISK!
  78
  79     It is suggested that you either use the "Incoming" folder or a seperate
  80     folder for the files you wish to share, to avoid inadvertedly sharing
  81     private files.
  82
  83     If you share more than 200 files, you should consider that some servers
  84     have a hard limit due to resource constraints, which means that you may
  85     be kicked from them if you share too many files or that some of your
  86     files won't be populated to the network through that server. So it is not
  87     always a good idea to share lots of files.
  88
  89   - Other:
  90     The other options are pretty self-explanatory. If you don't know what it
  91     does, don't touch it as a general rule. More information on getting started
  92     can be found in the aMule wiki:
  93       http://wiki.amule.org/index.php/Getting_Started
  94
  95     Don't forget to connect to a server, or you probably won't download too much.
  96
  97
  98  Basic aMule Tips
  99 ------------------
 100   * NEVER run aMule as root.
 101   * If you are behind a firewall or router, be sure that the ports have been
 102     opened. The default ports are 4662 (TCP). 4665 (UDP) and 4672 (UDP). If
 103     these are blocked, you will receive a "LowID" which results in fewer
 104     availble sources for the files you are downloading.
 105   * Obtain an appropriate server.met: e.g., if you are a dialup, using
 106     a large server list is not appropiate.
 107   * Set your temp and shared directories in Preferences->Directories
 108     * To recursively select a certain directory, right-click over it.
 109     * You should *NOT* share
 110       * Your temp download directory!
 111       * Your /etc directory
 112       * Probably not your /var, /lib, /boot, or /usr directory
 113       * Certainly make sure that any really confidential files (password files,
 114         private SSH keys, credit card numbers :) are *not* shared. So generally
 115         do not share your entire home directory, although you might want to
 116         share some files or directories in it.
 117   * Remember that you get certain download priveledges with those clients
 118     (aMule, eMule, etc users) to whom you upload files, in the form of reduced
 119     queue waits.
 120   * Please note that compilation with optimizations is supported. However, if
 121     you pull a Gentoo, we will probably just tell you to recompile aMule and/or
 122     your system with sane compiler-flags before we will attempt to address the
 123     problem.
 124
 125
 126  Obtaining your first server list
 127 ----------------------------------
 128   Use one of the following links in the "Update server.met from URL" box in
 129   the Server tab. They are apparently updated every 20 minutes.
 130
 131   * The current top 50 servers (these fill up fast):
 132       http://ocbmaurice.dyndns.org/pl/slist.pl/server.met?download
 133   * The current top 150 servers:
 134       http://ocbmaurice.dyndns.org/pl/slist.pl/server.met?download/server-good.met
 135   * The biggest list (about 300 servers) maintained by the site. Only if you
 136     have a very decent connection:
 137       http://ocbmaurice.dyndns.org/pl/slist.pl/server.met?download/server-max.met
 138   * Should maurice be down for some reasons, use this server.met instead:
 139       http://www.srv1000.com/azz/server.met
 140
 141   If these are non-functional, simply google for 'server.met'.
 142
 143
 144  Tranfers icons
 145 ----------------
 146   To find descriptions of the various icons found inside aMule, take a look at
 147   http://wiki.amule.org/index.php/Getting_Started#Icons_and_What_They_Signify
 148
 149
 150  License
 151 ---------
 152   aMule -- like eMule -- is released under the GNU General Public License.
 153   See the "COPYING" file for details.
 154
 155
 156  Developers
 157 ------------
 158   See AUTHORS
 159
 160
 161  FAQ:
 162 ------
 163   -- How do I know whether my ID is high or low? --
 164
 165   Look at the arrows at the bottom right corner, wrapping a world icon, next to
 166   the server name you are connected to. If they're green, your ID is high. If
 167   they're yellow, your ID is low.
 168
 169
 170   -- What does high and low ID mean anyway? --
 171
 172   When your ID is high (green arrows), everything is fine.
 173   When it's low (yellow arrows), you are probably behind a firewall or a
 174   router, and other clients can't connect to you directly (which is a bad
 175   thing). Please read the FAQ, search our wiki or forums on how to configure
 176   your firewall/router for aMule.
 177
 178   NOTE: you can also get a low ID when the server you connected to is too busy
 179   to answer properly, or simply badly configured. When you are sure your
 180   settings are ok and you SHOULD have a high ID, connect to another server.
 181
 182
 183   -- I'd like to search for specific file types, what filter stands for which files? --
 184
 185   File Type Extensions found
 186   --------------------------------------------------------------------
 187   Audio         .mp3 .mp2 .mpc .wav .ogg .aac .mp4 .ape .au .wma
 188   Video         .avi .mpg .mpeg .ram .rm .vob .divx .mov .ogg .vivo
 189   Program       .exe .com
 190   Archive       .zip .rar .ace .tar.gz .tar.bz2 .Z .arj
 191   CDImage       .bin .cue .iso .nrg .ccd .sub .img
 192   Picture       .jpg .jpeg .bmp .gif .tif .png
 193
 194
 195   -- What are all those fancy colors in the download progress bar about? --
 196
 197   Each download in the the transfers window has a coloured bar to show current
 198   file availability and progress.
 199
 200   * Black shows the parts of the file you already have
 201   * Red indicates a part missing in all known sources
 202   * Different shades of blue represent the availability of this part in the
 203     sources. The darker the blue is the higher the availability
 204   * Yellow denotes a part being downloaded
 205   * The green bar on top shows the total download progress of this file
 206
 207   If you expand the download you see its sources with the corresponding
 208   bar. Here the colours have a slightly different meaning:
 209
 210   * Black shows parts you are still missing
 211   * Silver stands for parts this source is also missing
 212   * Green indicates parts you already have
 213   * Yellow denotes a part being uploaded to you
 214
 215   Learning how the progress bar works will greatly help your understanding
 216   of the eD2k network.
 217
 218
 219   -- Where can I get more information? --
 220
 221   Here are some links that might be of your interest:
 222
 223   * aMule Wiki (documentation pages)
 224       http://wiki.amule.org
 225
 226   * aMule forums
 227       http://forum.amule.org
 228
 229   * eMule documents
 230       http://www.emule-project.net/home/perl/help.cgi
 231
 232
 233  Want to help?
 234 ---------------
 235   aMule is a free software project and requires the cooperation of its users
 236   to improve the quality of the software. We welcome all contributions to the
 237   project in the form of new features, bug fixes, feature requests, etc.
 238
 239   If you are not a programmer you can still contribute by providing good bug
 240   reports  when you come accross a problem with aMule. A good bug report gives
 241   the aMule Team information enough to reproduce the bug (so we can see it in
 242   action) and fix it. If possible, try to isolate under which the bug occurs
 243   (eg. does it happen on some specific window, with some specific files, some
 244   specific conditions etc.) and provide as much detail as you can in your
 245   report.
 246
 247   If you are a programmer and fix a bug you observe, please send us a patch or
 248   a note about how you fixed the problem.
 249
 250
 251  IRC, Links and Contact
 252 -------------
 253   IRC: Channel #aMule on FREENODE IRC Network (irc.freenode.net)
 254
 255   aMule homepage
 256       http://www.amule.org
 257
 258   aMule related links
 259       http://wiki.amule.org/index.php/FAQ_eD2k-Kademlia
 260       http://wiki.amule.org/index.php/aMule
 261       http://wiki.amule.org/index.php/FAQ_aMule
 262       http://wiki.amule.org/index.php/FAQ_utils
 263       http://wiki.amule.org/index.php/Getting_Started
 264       http://wiki.amule.org/index.php/aMule_problems
 265
 266   wxWidgets toolkit homepage
 267       http://www.wxwidgets.org
 268
 269   eMule homepage
 270       http://www.emule-project.net
 271
 272   Contact (administrative issues only!)
 273       admin@amule.org
 274
 275  Legal Notice
 276 --------------
 277
 278   aMule is an interface to the ed2k network. As such, the aMule developers have
 279   absolutely no control or say over what is transferred on this medium and
 280   cannot be held liable for any non-personal copyright infringements or other
 281   illegal activities.
 282
 283
 284 -- Last modified Sun May 1 13:05:02 CEST 2005 --