search

jlouis / etorrent

Erlang Bittorrent Client
BSD 2-Clause "Simplified" License
294 stars 50 forks source link

readme

; -- Mode: Markdown; -- ; vim: filetype=none tw=76 expandtab

ETORRENT

ETORRENT is a bittorrent client written in Erlang. The focus is on robustness and scalability in number of torrents rather than in pure speed. ETORRENT is mostly meant for unattended operation, where one just specifies what files to download and gets a notification when they are.

Flag days

Flag days are when you need to do something to your setup

Build Status

Currently, we are running build-bots through [http://travis-ci.org](Travis CI). Build Status

Why

ETORRENT was mostly conceived as an experiment in how easy it would be to write a bittorrent client in Erlang. The hypothesis is that the code will be cleaner and smaller than comparative bittorrent clients.

Maturity

The code is at this point somewhat mature. It has been used in several scenarios with a good host of different clients and trackers. The code base is not known to act as a bad p2p citizen, although it may be possible that it is.

The most important missing link currently is that only a few users have been testing it - so there may still be bugs in the code. The master branch has been quite stable for months now however, so it is time to get some more users for testing. Please report any bugs, especially if the client behaves badly.

Currently supported BEPs:

Required software:

GETTING STARTED

  1. make deps - Pull the relevant dependencies into deps/
  2. make compile - this compiles the source code
  3. make rel - this creates an embedded release in rel/etorrent which can subsequently be moved to a location at your leisure.
  4. edit ${EDITOR} rel/etorrent/etc/app.config - there are a number of directories which must be set in order to make the system work.
  5. check ${EDITOR} rel/etorrent/etc/vm.args - Erlang args to supply
  6. be sure to protect the erlang cookie or anybody can connect to your erlang system! See the Erlang user manual in distributed operation
  7. run rel/etorrent/bin/etorrent console
  8. drop a .torrent file in the watched dir and see what happens.
  9. call etorrent:help(). from the Erlang CLI to get a list of available commands.
  10. If you enabled the webui, you can try browsing to its location. By default the location is 'http://localhost:8080'.

GETTING STARTED (Windows)

  1. Obviously get and install erlang from erlang.org. This process was tested with R14B01 release. You may want to add the bin directory to your PATH in order to reduce the length of the commands you will enter later on.
  2. Install msysgit. Tested with 1.7.3.1.msysgit.0.
  3. Install Win32 OpenSSL. The installer hang on me midway through the process but the libs were properly copied to C:\Windows\system32.
  4. Confirm that your crypto works correctly by running crypto:start(). from an erlang shell (Start->Erlang OTP R14B01->Erlang). The shell should respond with ok. If you get an error then your openssl libraries are still missing.
  5. Open up a git bash shell and cd to a directory you want to work in.
  6. Clone the rebar repository git clone https://github.com/basho/rebar.git

  7. From a regular cmd.exe shell cd rebar. Now if you added the erlang bin directory to your PATH then you can simply run bootstrap.bat. If you didn't add Erlang's bin to your path then issue the following command:

    "C:\Program Files\erl5.8.2\bin\escript.exe" bootstrap

    Adjust the path to your Erlang installation directory. From now on, use this invocation for escript.exe and erl.exe. I'll assume it's on PATH. You should now have a rebar file created. If you have Erlangs bin dir on your PATH then you may want to also add the rebar directory to your PATH. This will allow you to use the rebar.bat script which will also reduce the amount of typing you will have to do.

  8. Clone etorrent and copy the rebar file into it (unless you have it on path).

  9. Now, we need to satisfy the dependencies. This should be done by rebar itself but I couldn't get it to work correctly with git. This point describes how to do it manually.

    mkdir deps # this is where rebar will look for etorrent dependencies

    escript.exe rebar check-deps # this will give you a list of the missing dependencies and their git repos.

    For each dependency reported by check-deps perform the following command in a git bash shell (be sure to be in the etorrent directory)

    git clone git://path_to_repo/name.git deps/name

    Be sure to run escript.exe rebar check-deps after cloning each additional repo as new dependencies might be added by them.

    For the time of this writing (2011-02-13) I had to clone the following repositories:

    git clone git://github.com/esl/gproc.git deps/gproc

    git clone git://github.com/esl/edown.git deps/edown

    git clone git://github.com/basho/riak_err.git deps/riak_err

  10. escript.exe rebar compile to compile the application from a cmd.exe prompt.

    1. escript.exe rebar generate this creates an embedded release in rel/etorrent which can subsequently be moved to a location at your leisure. This command may take some time so be patient.
    2. Edit rel/etorrent/etc/app.config - there are a number of directories which must be set in order to make the system work. Be sure each directory exists before starting etorrent. You also have to change all paths starting with / (ie. /var/lib...). When setting paths use forward slashes. For example {dir, "D:/etorrent/torrents"},.
    3. Check rel/etorrent/etc/vm.args - Erlang args to supply
    4. Be sure to protect the erlang cookie or anybody can connect to your erlang system! See the Erlang user manual in distributed operation

    5. We can't run the etorrent script because it's written in bash. So in order to start ettorent cd from a cmd.exe shell into the rel\etorrent directory. And perform the following command

      erts-5.8.2\bin\erl.exe -boot release\1.2.1\etorrent -embedded -config etc\app.config -args_file etc\vm.args

      Be sure to substitute the version number in the release path to the current etorrent release version. Do the same for the erts version. Allow port communication when/if the Windows firewall asks for it.

    6. drop a .torrent file in the watched dir and see what happens.
    7. call etorrent:help(). from the Erlang CLI to get a list of available commands.
    8. If you enabled the webui, you can try browsing to its location. By default the location is 'http://localhost:8080'.

Testing etorrent

Read the document etorrent/TEST.md for how to run tests of the system.

Troubleshooting

If the above commands doesn't work, we want to hear about it. This is a list of known problems:

Installing Erlang

I (jlouis@) use the following commands to install Erlang:

And then I enable it in stow:

cd /usr/local/stow && stow ${otp_version}

You may have to use stow -D on an old

Another way is to use Basho kerl, a simple shell script:

$ curl -O https://raw.github.com/spawngrid/kerl/master/kerl; chmod a+x kerl
$ ./kerl build R14B04 r14b04
$ ./kerl install r14b04 /opt/erlang/r14b04
$ . /opt/erlang/r14b04/activate

In the above example, kerl installs Erlang R14B04 to directory /opt/erlang/r14b04 and makes it default. For more information, please check kerl readme.

QUESTIONS??

You can either mail them to jesper.louis.andersen@gmail.com or you can come by on IRC #etorrent/freenode and ask.

Development

PATCHES

To submit patches, we have documentation in documentation/git.md, giving tips to patch submitters.

Setting up a development environment

When developing for etorrent, you might end up generating a new environment quite often. So ease the configuration, the build infrastructure support this.

Notice that we -pa add ../../apps/etorrent/ebin so you can l(Mod) files from the shell directly into the running system after having recompiled them.

Documentation

Read the HACKING.md file in this directory. For how the git repository is worked, see documentation/git.md.

ISSUES

Either mail them to jesper.louis.andersen@gmail.com (We are currently lacking a mailing list) or use the issue tracker

Reading material for hacking Etorrent: