ejabber, BOSH, and StopheJS, Oh My(SQL)

gistfile1.md

ejabberd

####Server Ubuntu 10.04 LTS Lucid

##Process

Install ejabberd

# sudo apt-get install ejabberd

Add adminstrative user permissions

# vim /etc/ejabberd/ejabberd.cfg

/etc/ejabberd/ejabberd.cfg:

...
{acl, admin, {user, "admin", "example.com"}}.
...

Restart the ejabberd server with the new configuration file

# ejabberdctl restart

Register the new user

# ejabberdctl register admin example.com password

Verify install by navigating to http://example.com:5280/admin

Login: admin@examlpe.com

Password: password

===

####BOSH - XEP-0206

Add the module to the ejabberd configuration

# vim /etc/ejabberd/ejabberd.cfg

/etc/ejabberd/ejabberd.cfg:

{modules,
	[
		...
		{mod_http_bind, []}
		...
	]
}.

Verify a port is designated to listen on for the http_bind module /etc/ejabberd/ejabberd.cfg:

  {5280, ejabberd_http, [
                         %%{request_handlers,
                         %% [
                         %%  {["pub", "archive"], mod_http_fileserver}
                         %% ]},
                         %%captcha,
                         http_bind,
                         http_poll,
                         web_admin
                        ]}

Restart the ejabberd server with the new configuration file

# ejabberdctl restart

Verify the implementation of the http_bind module by navigating to http://example.com:5280/http-bind

===

ejabberd Modules via SVN

• At the time of writing the ejabberd-modules repository is only available via SVN, while ejabberd is only available via git. Keep an eye on this as it would be nice to stick with one version control tool.

#	apt-get install subversion
#	cd ~
#	svn co https://svn.process-one.net/ejabberd-modules
# 	cd ejabberd-modules

Modules are listed by directory. Read the included README for both the entire repository and individual modules for specific installation instructions.

Modifying the mod_http_bind (GET) landing page.

Personally, I don't like the amount of information given on the default http_bind module landing page. Luckily, it's fairly trivial to modify and re-deploy the module.

After downloading the ejabber-modules SVN (see above) and editing the module to your liking, rebuild and restart.

# cd ~/ejabberd-modlues/http-bind/trunk
# vim src/web/mod_http_bind.erl
# ./build.sh
# cp ebin/* /usr/lib/ejabberd/ebin/
# ejabberdctl restart

===

MySQL Integration

Build and deply the ejabberd MySQL ODBC .beam files

# cd ~/ejabberd-modules/mysql/trunk
# ./build.sh
# cp ebin/* /usr/lib/ejabberd/ebin/

Install MySQL, create a new user for ejabberd, and test the new user.

# apt-get install mysql-server
# mysql -u root -p
mysql> GRANT ALL ON ejabberd.* TO 'ejabberd'@'localhost' IDENTIFIED BY 'password';
mysql> CREATE DATABASE ejabberd;
mysql> exit
# mysql -u ejabberd -p

The MySQL schema is available via the ejabberd git repository.

# cd ~
# wget https://git.process-one.net/ejabberd/mainline/blobs/raw/2.1.x/src/odbc/mysql.sql

Create tables using the provided MySQL export and check the database structure.

# cat mysql.sql | mysql -D ejabberd -u ejabberd -p
# echo 'SHOW TABLES' | mysql -D ejabberd -u ejabberd -p

Edit the ejabberd configuration to use ODBC to authenticate and the MySQL driver.

Be sure to comment out {auth_method, internal}

/etc/ejabberd/ejabberd.cfg:

...
{auth_method, odbc}.
...
{odbc_server, {mysql, "localhost", "ejabberd", "ejabberd", "password"}}.
...

• Note switching your driver will require you to either re-register or dump/restore your users. Since we only have one user at this point, we'll just re-register after a restart. Re-registering with a differnt password is an easy way to make sure the MySQL authorization and user registration is working properly.

# ejabberdctl restart
# ejabberdctl register admin localhost differentpassword

(INSERT CUSTOMIZATION, SECURITY, ETC. HERE)

===

Testing via StropheJS

Grab the latest version of StropheJS

	cd /var/www/
	git clone https://github.com/metajack/strophejs
	cd strophejs
	./make
	vim examples/basic.js

Local Testing

Change the BOSH_SERVICE variable to your newly created BOSH service…

 var BOSH_SERVICE = 'http://localhost:5280/http-bind';

Load up http://example.com/strophejs/examples/basic.html. Enter your username and password. Don't for get the domain (admin@localhost)!

You should see the authentication XML being communicated back and forth.

External Server Testing

There are many ways to go about connecting to an external server's BOSH endpoint, one of the easiest is using a proxy either using (insert proxy-able web server here).

Apache

Edit your virtual host configuration or httpd.conf.

ProxyRequests Off
ProxyPass /ejabberd http://example.com:5280/http-bind/
ProxyPassReverse /ejabberd http://example.com:5280/http-bind/
<Proxy *>
    Allow from all
</Proxy>

nginx

Edit your nginx server configuration to include the following.

location /ejabberd {
	proxy_pass http://example.com:5280/http-bind;
}

Then change the BOSH_SERVICE variable…

 var BOSH_SERVICE = 'http://localhost/ejabberd';

mod_rest

Installation & Initial Configuration

# cd ~/ejabberd-modules/mod_rest/trunk
# ./build.sh
# cp ebin/* /usr/lib/ejabberd/ebin/

Update the ejabberd configuration

# vim /etc/ejabberd/ejabberd.cfg

/etc/ejabberd/ejabberd.cfg:

…

{modules,
 [
  {mod_rest, [{allowed_ips, [{127,0,0,1}]}]},
	…
  }
 ]
}

…

{listen,
 [
  {5285, ejabberd_http, [
			 {request_handlers, [
					     {["rest"], mod_rest}
					    ]}
			]},
   …
 ]
}

...

Restart ejabberd, and check out the newly listening port (http://example.com:5285/rest)! You should see the module's default message: Try POSTing a stanza. if accessed via a web browser (GET).

Testing POST (StropheJS & Postman)

Using one of the configurations for StropheJS mentioned before open up the StropheJS echobot example (http://example.com/strophejs/examples/echobot.html)

Note: It may be worthwhile, for ease of testing to alter your ejabberd.cfg to allow request from all IP addresses. To do this edit the mod_rest settings under modules; Since all is the default we can just leave the settings blank:

…

{modules,
 [
  {mod_rest, []},
	…
  }
 ]
}

…

Postman is a wonderful Chrome plugin/app that allows you to make HTTP requests with various control of data, headers, and more!

After logingin into echobot copy your full JID from the output should look something like:

mynode@example.com/969115501351614083675598

Using Postman, set up a POST request using the endpoint you created for the mod_rest

http://example.com:5285/rest

Use the following as raw data:

<message to="mynode@example.com/969115501351614083675598" from="example.com/rest" type="chat"><body>Hello, World!</body></message>

Upon submission you should see an Ok as the response from the REST endpoint.

Common Error Responses

No Response

Could not get any response

This seems to be like an error connecting to http://notexample.com:5285/rest. The response status was 0.
Check out the W3C XMLHttpRequest Level 2 spec for more details about when this happens.

This is usually caused by requesting the mod_rest server through a domain (or even IP) which is not listed in your ejabberd configuration. Be sure you are submitting the request to the domain which your ejabberd server is setup to host.

Rejected Response

Error: REST request is rejected by service.

Are you requesting your service from a different IP that the one set by allowed_ips? Try using the allow all settings mentioned above.

Extended Configuration