SourceForge Logo

Go to the SourceForge project home page








Running a daemon and setting up a private network

Go to documentation index

Table of contents

You can launch your own HeavyMole network and use it in a public or private purpose. For that, you need to set up some central servers and update data of the HeavyMole applications that you want to join the network. This text explains main things you should know for that purpose.

A. Server functioning overview

A.1 What is the role of servers ?

Servers are used:

  • to know his public IP when an application is behind a NAT
  • when an application is launched for the first time and doesn't know anybody yet
  • when an application cannot find satisfactory neighbours by itself
  • to update data of favorite users whose information have changed (eg IP address or ports changed)
  • to hold chat rooms data, ie to create a room, to connect to or disconnect from it

This was done in version 0.1.1 by using only one server. We improved it by using multiple servers which connect with each other and exchange only names of hosted chat rooms and the number of users connected to them. We choosed to use a distributed architecture because:

  • it is more tolerant to server crashed or unreachable
  • it distributes the load through all servers and permits to handle huge networks

In order to give an identity to each network, to prevent from undesired interference between them and to give (very) small protection against attacks, the servers are defined with password and they can connect only with servers of the same password.

A.2 Server hardware load

There are two factors in the hardware load:

  • handling of messages from HeavyMole applications
  • data to update from other servers

Messages from HeavyMole applications are composed of:

  • operations to update user data or find new neighbours: applications do rarely need to access these data and the load is really small
  • operations on chat rooms: these are the main messages that a server will receive
All these messages are very light to handle and the server load is tiny while there's not a lot of users. In fact, the connection of a user to a chat room is the most heavyiest operation for the daemon. It may cause some troubles only when the number of user is becoming really big.
The amount of data kept by a server is small and it doesn't need lots of memory to run.

An estimation on paper gives the following ressources load for 1000 users connected:

  • 1 Kb/s of traffic load
  • less than 1% of CPU and memory of a modern computer

A.3 Server hardware comparison

Unless most of other file sharing programs, HeavyMole doesn't need some monstrous dedicated central server.

You can make the comparison for yourself with the following specifications of a popular eDonkey server with a capacity of 100 000 users (the server is "The Silent-Bob Edonkey Server", the specifications have been found on

  • CPUs: 2 PIII with 1000MHz CPUs
  • RAM: 1 GB RAM
  • Network: 100 MBit Fast Ethernet
    The computer is connected to a 100MBit link directly connected to a redundant optic fibre back-bone at 2.4 GBit to the internet.
  • HD: 2 * 8 GB SCSI with Linux-Software RAID 0
  • OS: Debian Linux (Woody, Kernel 2.4.20)
While the specifications of the server of HeavyMole 0.6.0 are:
  • CPUs: Pentium II 200 Mhz
  • RAM: 64 Mb
  • Network: cable
  • HD: 120 Mb 5400 t/m
  • OS: OpenBSD 3.3
  • Plus: the HeavyMole server is one of the services running on the machine (which is also a router and a web server), and the server is a little bit slow because of other P2P applications.

A.4 How many servers are necessary ?

The answer depends on the size of the network, the reliability of hosts and the use you want to make of chat rooms:

  • if a host is crashed, down or unreachable, the chat rooms it holds are not accessible. If all servers are down, it is more embarassing: no chat rooms will be accessible and no new one can be created; a newly installed application won't find anybody; an application with really bad neighbours cannot find new users; previously knew users which have changed their IP adress or port numbers will be considered down. In order to reduce these problems, you can install at least 2 or 3 servers to be sure there's always one ready (if you really wanna be sure and if it is a really small network, you can even set up one server per machine).
  • each server can handle a real big number of users, but in order to not overload it, you can set up more servers to distribute the load through them. It is besides highly recommended if your network is geographically exploded. However, as servers communicate themselves some datas, adding a new server will ask more work and, if you set up too much servers, it will overload them instead of decrease the total load. Simulation, experimentation or theorisation will be necessary to give a precise number of server to use.

B. Setting up a network

[There is no installation procedure for MS Windows systems yet.]

To set up your own network, you need to launch some central servers and change the servers data that the HeavyMole applications will use.

Note: a server can't be behind a NAT.

B.1 Setting up servers

  • You first need to get the last "heavymole-0.7.0.src.tar.gz" file and untar it.
  • If you are not under GNU/Linux, then go to the "heavymole-0.7.0/src" directory, choose a file and copy it to heavymole-0.7.0/src/common. Example for BSD: cp common.bsd common
  • If you want to use a BSD-style init script instead of the System V-style, then edit the heavymole-0.7.0/src/common file and modify the "INSTALL_METHOD" variable to "BSD".
  • Go into into the "heavymole-0.7.0/src" directory and type make installserver. It will:
    • compile the sources to get the "hmd" executable file (only for the source tarball).
    • copy the executable to the directory "/usr/local/share/hmd", and a script in "/usr/local/bin".
    • if you use a System V-style init script, it will
      • copy a script in "/etc/rc.d/init.d".
      • use the "chkconfig" command to create links in the "/etc/rc.d/" directories, so that the daemon will be launched when the host goes in the runtime levels 3, 4 and 5 (i.e when the host boots up).
      else (BSD-style), it will modify your /etc/rc.local.
    • launch the daemon with the command option -C so that you can configure the data of the server. You need to enter:
      • the network interface to be used. Push the enter key if you do not need to specify one.
      • the port number to be used.
      • the password of the network (must be the same for all servers; you'd better not use the default one, except for test purpose)
    • launch the daemon with the command option -o to display the data of the server. You need to write down for memories the fields "IP address" and "port number" cause these are the data that need to be exported to other servers and to HeavyMole applications.
  • If you already launched some other servers, you need to import their data to let the new server connect with them. For that purpose:
    • edit or create the "/usr/local/share/hmd/SERVERS" file or copy it from a previous installation
    • you must enter at least data from one running server (if it finds a server, it will ask for data of other servers and update itself the file):
      see here for details on editing a server file
  • If you used a System V-style init script, then you can type "make startserver" to launch the daemon (it will automatically be launched the other times the host boots up, but it isn't yet launched for this time). Note that you can also use the "make stopserver", "make restartserver" or "make statusserver" commands.
    If you used a System V-style init script, then you need to launch the server via the "/usr/local/bin/hmd" script.


  • If you want to modify the data of the server, you can use the "/usr/local/bin/hmd" shell script like that:
    • /usr/local/bin/hmd - o: to display the current data
    • /usr/local/bin/hmd - c: to re-set data
    • /usr/local/bin/hmd - h: for help

    Once you have changed the data, you can restart it so that the current running daemon uses the new data. For that, type "make restartserver".

  • If you don't want to install the server (eg to use it locally for test purpose), you'd better cd and work in the "heavymole-0.7.0/src/hmd" directory. Then just compile it (eg with "make debug") and launch it (eg "hmd"). If you don't use the "-d <path>" option, it will create a directory "data" in the current directory.

B.2 Setting up HeavyMole applications

After setting up at least one server, you need to configure the data of the HeavyMole applications:

  • edit the "HMDDATA" file. It is held in the directory pointed by USER_DATA_PATH in your config file (normally in "$HOME/heavymole/data" or "data/user" if you work locally).
    You can run heavymole with the -v option to see what server file it is using
  • set up data from at least one server
    see here for details on editing a server file
  • launch the application to check if it works

B.3 Editing a server file

A server file is composed of one or more server descriptions.

A server description is composed by a line of the following format:

  • first, the dotted IP address or the DNS name of the server
  • then a quote (:)
  • then the port number of the server
  • lastly, a carriage return (ENTER)
Empty lines and lines beginning with '#' are ignored.

Fictitious example:

# ************
# * server 1 *
# ************

# format of an entry: <IP Address>:<Port number>

# ************
# * server 2 *
# ************

# *****************
# * local machine *
# ***************** - This page was last updated on july, 30th 2003