This tutorial explains how you can install MUCkl, an Ajax application that can be used to join an existing Multi-User Chat based chatroom via a web browser like Firefox. You can create persistent chatrooms using ejabberd's built-in Multi-User Chat module or by using an external component such as Mu-Conference. This tutorial is based on the French tutorial Installer MUCKl EJabberd.

1. Install MUCkl

   Download the latest MUCKl and decompress it in the document root of your Web server.

2. Create a Jabber Account for MUCkl

   Create a Jabber account for MUCkl. Check only the first step of the instructions to create an initial administrator account.

3. Create a Persistent Room

   Create a persistent chatroom with a Multi-User Chat compatible Jabber client and ensure yourself that the user you created in previous step has sufficient permissions to this chatroom.

4. Configure MUCkl

   Edit the file config.js in the directory where you unpacked MUCkl. The most important values are:

   • Use HTTP Polling:

     var BACKENDTYPE = 'polling';

   • The URL to access the HTTP Polling service:

     var HTTPBASE = "http-poll/";

   • Domain name of Jabber service:

     var XMPPDOMAIN = "example.org";

   • The username and the corresponding password of the Jabber account you created in the second step:

     var MUCKLJID = "username";
     var MUCKLPASS = "password";

   • To define a chatroom:

     var ROOMS =
     [
           {
                   name:'my chatroom',
                   description:'My chatroom',
                   server:'conference.example.org'
           }
     ];

   • Refresh rate:

     var timerval = 1000;

5. Configure Apache

   The module mod_proxy_http must be installed and configured:

   a2enmod proxy
   /etc/init.d/apache2 restart

   The HTTP Polling service runs by default on port 5280. However, Apache (which hosts MUCkl) runs on a different port. Hence, we should instruct Apache to redirect MUCkl's requests to the HTTP polling via the URL http://example.org:Apache_port/MUCkl_directory/http-poll to http://localhost:5280/http-poll. Therefore, it is necessary to add a .htaccess file in the directory in which you installed MUCKl. This file should contain the following information:

   AddDefaultCharset UTF-8
    Options +MultiViews
    <IfModule mod_rewrite.c>
          RewriteEngine On
          RewriteRule http-poll/ http://localhost:5280/http-poll/ [P]
    </IfModule>

6. Configure ejabberd

   To configure ejabberd, you can choose between two methods.

   • Using the Web Administration Interface

     Go in the web interface to Nodes/your node/Listened Ports, enter the following information on the last line, and press the Add button:

     Port	Module	Options
     5280	ejabberd_http	[http_poll, web_admin]

   • Using ejabberd.cfg

     Edit ejabberd's configuration file; add the following two lines in the section starting with '{listen,' (also described in the guide). You have to restart ejabberd afterwards to apply the changes:

     {5280, ejabberd_http, [http_poll, web_admin]},

     Remark that there is no ending comma needed in the last entry. However, all entries before the last one need to end with a comma!

   Note that you can host the web administration interface and the HTTP Polling component on different ports. For example, you can host the web interface on a secured port, and HTTP Polling on another unsecured port. Check the examples in the Web Interface section of the guide.

Authentication Methods

ejabberd and MUCkl allow several authentication methods. Example configurations:

• Normal authentication

  In ejabberd.cfg

  {auth_method, [internal]}.

  In MUCkl config.js

  var ANON_AUTHTYPE = 'nonsasl'; 
  var XMPPDOMAIN = "localhost"; // domain name of jabber service to be used
  var MUCKLJID = "muckl"; // username
  var MUCKLPASS = "mucklpass"; // password

  You must create the account muckl@localhost with password 'mucklpass'. MUCkl will login to the account muckl@localhost/randomresource.

• Anonymous login authentication

  In ejabberd.cfg

  {auth_method, [anonymous]}.
  {anonymous_protocol, login_anon}.

  In MUCkl config.js

  var ANON_AUTHTYPE = 'anonymous'; 
  var XMPPDOMAIN = "localhost"; // domain name of jabber service to be used
  var ANONHOST = "localhost"; // hostname of sasl anonymous service

  MUCkl will login to the virtual account undefined@localhost/undefined

• SASL anonymous authentication (it doesn't seem to work correctly)

  In ejabberd.cfg

  {auth_method, [anonymous]}.
  {anonymous_protocol, sasl_anon}.

  In MUCkl config.js

  var ANON_AUTHTYPE = 'saslanon';
  var XMPPDOMAIN = "localhost"; // domain name of jabber service to be used
  var ANONHOST = "localhost"; // hostname of sasl anonymous service