DonkeySurvey Release 0.1


DonkeySurvey is a tool for collecting, storing and retrieving information about
downloads and uploads on a edonkey network. It is fully implemented in Python
and uses MySQL as database system. DonkeySurvey runs concurrently with a
MlDonkey server, reading messages from this client through a socket in a
assynchronous way. It processes those messages, querying the client for more
information when necessary, and store them in a database.

This tool is not mature yet and it has not been fully tested yet, but it is
functional. If you have problems, please report them to the authors (see
AUTHORS file for e-mail contact).

This README file should contain enough information to get you started
with DonkeySurvey.  Additional information regarding the contents of the
release can be found at the DonkeySurvey web site,
http://ccsl.ime.usp.br/mac5856/DonkeySurvey/trac, which contains information on
bug fixes and new releases. The public repository can be founded at
http://github.com/tassia/DonkeySurvey.

Getting Started
===============

The following instructions take you through a sequence of steps to get
the DonkeySurvey up and running.

1.  You will need the following prerequisites.

    - This tar file donkeysurvey-0.1.tar.gz

    - Python Interpreter (It has been tested with 2.5.x and 2.6.2 versions, but
      should work with version > 2.2)

    - MySQL for Python - python-mysqldb

    - MLDonkey Client 3.0.0 or later

    - MySQL 5.0 or later

3. Run MLDonkey Client

    cd mldonkey-3.x.x
    ./mlnet

    or, if you have it installed through some package management system like
    dpkg, just type 'mldonkey' on a console

2. Unpack the tar file and go to the top level directory

    tar xzvf donkeysurvey-0.1.tar.gz
    cd donkeysurvey-0.1

    If your tar doesn't accept the z option, use

      gunzip donkeysurvey-0.1.tar.gz
      tar xf donkeysurvey-0.1.tar
      cd donkeysurvey-0.1

3. Configure logging settings, database connection and mldonkey host connection

    vim donkeysurvey/donkeysurvey.conf

4. Run it!

    ./DonkeySurvey.py

    Alternatively you can pass arguments through command line:
    ex.: ./DonkeySurvey.py -d -b -U <user> -P <password> -o /var/log/donkeysurvey.log

    Instructions on how to use the command line options can be found typing ./DonkeySurvey --help



Database Configuration
======================

In order to persist the data, you need to create the database and tables. The
sql script 'schema.sql' is located at documentation/data in the
donkeysurvey-0.1 directory. You can execute it with the following commands:

    mysql -u root -h localhost
    mysql> \. <path-to-donkeysurvey-directory>/documentation/data/schema.sql



A database named 'donkeystats' will be created.