Difference between revisions of "Integration/XMPP/Prosody"

From diaspora* project wiki
Jump to: navigation, search
(MySQL)
(Drop i18n template)
 
(31 intermediate revisions by 10 users not shown)
Line 1: Line 1:
 +
= Integrating Prosody with Diaspora =
  
= Integrating Prosody with Diaspora =
+
Here you will find all you need to install and set up a Prosody XMPP server integrated with your Diaspora user database.
 +
This guide was tested using Debian 7 and Archlinux, but it will probably work well for all GNU distributions.
 +
There are several steps and configurations you will need to perform, so read the instructions carefully.
  
Here you will find all you need to install and setup a Prosody XMPP server integrated with Diaspora users database.
+
'''See debian specific instructions at https://wiki.debian.org/Diaspora/XMPP'''
This tutorial was developed using Debain 7 but it probably will work well for all GNU Distributions.
 
There is several steps and configurations you will need to do, so watch it carefully.
 
  
 
= Understanding =
 
= Understanding =
  
The main goal is setup '''Prosody''' to be capable to compare the password received by the XMPP Client with the hashed password stored on '''Diaspora''' database.
+
The main goal is to set up Prosody to be capable of comparing the password received by the XMPP client with the hashed password stored on your pod's Diaspora database.
'''Diaspora''' password hash is done with bcrypt library, so we need to patch '''Prosody''' to do the same with the received password. To do so, we need to install a modified [https://code.google.com/p/prosody-modules/wiki/mod_auth_sql - mod_auth_sql] module available below.
+
Diasporas password hash is done using <tt>bcrypt</tt>, so we need to extend Prosody to do the same with the received password. To do so, we need to install a modified version of the [https://code.google.com/p/prosody-modules/wiki/mod_auth_sql - <tt>mod_auth_sql</tt>] module, available below.
  
On this setup '''Prosody''' will use it's own SQL database to store users data like friends, etc. and it will connect on '''Diaspora''' database just to compare passwords. Then two database configurations will be required.
+
Since authentication methods can be set per host, you can use an existing Prosody instance with access to Diasporas database.
  
Follow the tutorial and this should work well.
+
You can also pull in Diaspora contacts into the roster. They will only be updated on signing into the XMPP account and all modifications to them from the XMPP side will be lost.
  
= SQL =
+
= Prosody =
  
Before install '''Prosody''' create a database and user for it. You can do it on the same '''Diaspora''' SQL Server.
+
If you haven't  yet, install Prosody. This setup was tested against 0.9.8 and is known to be incompatible with the 0.8 series.
Just as '''Diaspora''' you can choose between '''MySQL''' or '''PostgreSQL'''.
+
Follow the instructions described on their [http://prosody.im/download/start official site].
  
= Prosody =
+
Once Prosody is installed, you can proceed.
  
Prosody is a modern XMPP communication server. It aims to be easy to set up and configure, and efficient with system resources. Additionally, for developers it aims to be easy to extend and give a flexible system on which to rapidly develop added functionality, or prototype new protocols.
+
== Install bcrypt Lua library ==
* [http://prosody.im Prosody] - XMPP Server
 
  
== Installing Prosody ==
+
Lua or Prosody don't ship with the bcrypt library. If it isn't in your repositories, you can install it with the following command:
  
To install '''Prosody''' follow the official instructions described on their official site - [http://prosody.im/download/start - Download]
+
<syntaxhighlight lang="bash">
 +
luarocks install bcrypt
 +
</syntaxhighlight>
  
Once '''Prosody''' is installed ten you can proceed.
+
Prosody still depends on Lua 5.1, if your distribution is already on Lua 5.2 you may need to change the command to <tt>luarocks-5.1</tt> or something similar.
  
== Setup prosody.cfg.lua ==
+
== Changes in <tt>prosody.cfg.lua</tt> ==
  
Separated by topics here you have what you need to do on this file:
+
There are a couple of required changes to your <tt>prosody.cfg.lua</tt>.
  
=== modules_enabled ===
+
=== Plugin path ===
  
* Disable
+
Since we're going to install a new module, you should pick a location where you want to store it, for example <tt>/etc/prosody/modules</tt>.
 +
Then tell Prosody to look for modules there:
  
<syntaxhighlight lang="bash">
+
<syntaxhighlight lang="lua">
"saslauth"
+
plugin_paths = { "/etc/prosody/modules" }
 
</syntaxhighlight>
 
</syntaxhighlight>
  
* Enable
+
Don't worry, Prosody will continue looking for modules in the standard location.
 +
 
 +
Now download the module to your machine:
  
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
"bosh"
+
curl https://gist.githubusercontent.com/jhass/948e8e8d87b9143f97ad/raw/mod_auth_diaspora.lua > /etc/prosody/modules/mod_auth_diaspora.lua
"legacyauth"
+
curl https://gist.githubusercontent.com/jhass/948e8e8d87b9143f97ad/raw/mod_diaspora_contacts.lua > /etc/prosody/modules/mod_diaspora_contacts.lua
 
</syntaxhighlight>
 
</syntaxhighlight>
  
=== Setup and configure SQL ===
+
=== Add a virtual host for your pod ===
  
The default auth method is '''internal''' and it must be replaced by '''sql'''. But '''sql''' require some configurations like SQL Server, database, user and password to access '''Diaspora''' and '''Prosody''' databases.
+
<syntaxhighlight lang="lua">
 +
VirtualHost "yourpod.example.org"
 +
  authentication = "diaspora"
 +
  -- Uncomment and adjust username and password for MySQL/MariaDB
 +
  --auth_diaspora = { driver = "MySQL", database = "diaspora_production", username = "diaspora", password = "pass", host = "localhost" }
 +
  -- Uncomment and adjust username and password for PostgreSQL
 +
  --auth_diaspora = { driver = "PostgreSQL", database = "diaspora_production", username = "diaspora", password = "pass", host = "localhost" }
 +
 
 +
  modules_enabled = {
 +
    "diaspora_contacts";
 +
  };
 +
</syntaxhighlight>
  
* Modify
+
Replace <tt>yourpod.example.org</tt> with your pod's domain and adjust the username and password for the database connection. This is very important!
  
<syntaxhighlight lang="bash">
+
Read in [http://prosody.im/doc/dns Prosodys official documentation] on how to correctly update your nameserver records afterwards.
authentication = "sql"
+
Also read about setting up the right [http://prosody.im/doc/certificates certificates] for your host.
</syntaxhighlight>
 
  
* Add
+
=== Enable BOSH support ===
  
<syntaxhighlight lang="bash">
+
Uncomment following line inside '''modules_enabled''' to enable BOSH support:
storage = "sql"
+
<syntaxhighlight lang="lua">
 +
"bosh"; -- Enable BOSH clients, aka "Jabber over HTTP"
 
</syntaxhighlight>
 
</syntaxhighlight>
  
* '''MySQL'''
+
=== Other recommendations ===
  
<syntaxhighlight lang="bash">
+
* Since we have to transmit the password in plaintext to the server, we strongly recommend to require encryption:
sql = { driver = "MySQL", database = "prosody_xmpp", username = "prosody_xmpp", password = "pass", host = "localhost" }
+
:<syntaxhighlight lang="lua">
sql_dsp = { driver = "MySQL", database = "diaspora_production", username = "diaspora", password = "pass", host = "localhost" }
+
c2s_require_encryption = true
 
</syntaxhighlight>
 
</syntaxhighlight>
  
* sql
+
* You may also require server to server connections to be encrypted and validate server certificates (diaspora does this already), but your pod won't be able to talk to some xmpp servers which use self signed certificates.
  
This are the '''Prosody''' database setup where '''Prosody''' will store users friends lists and it's personal setup. The database user must have wright permission on this;
+
:<syntaxhighlight lang="lua">
 +
s2s_require_encryption = true
 +
s2s_secure_auth = true
 +
</syntaxhighlight>
  
* sql_dsp
+
* Adding a reverse proxy to Prosody's BOSH endpoint under your pods domain on the path <tt>/http-bind</tt>  is a good idea too (check the [https://wiki.diasporafoundation.org/Vines#Browser_blocks_mixed-content examples on Vines page]). If you have done so, set the <tt>proxy</tt> setting in <tt>diaspora.yml</tt> to <tt>true</tt> and add <tt>consider_bosh_secure = true</tt> to your Prosody configuration.
  
This are the '''Diaspora''' database setup
+
* If you want to improve the experience of your users when connecting from mobile devices, install [https://wiki.debian.org/InstallingProsody#Useful_Modules_.28Mobile_support.29 modules listed on Debian's Prosody Installation guide].
  
 +
* If you want to allow users to connect via HTTPS port (443) to bypass restrictive firewalls, follow [https://wiki.debian.org/InstallingProsody#XMPP_over_HTTPS steps documented at Debian's Prosody Installation guide].
  
<syntaxhighlight lang="bash">
+
== Restart Prosody ==
</syntaxhighlight>
 
  
<syntaxhighlight lang="bash">
+
To complete the setup, just restart Prosody.
</syntaxhighlight>
 
  
<syntaxhighlight lang="bash">
+
= Testing =
</syntaxhighlight>
 
  
=== Add to the file ===
+
Just use your favorite XMPP client to connect to your pod using your regular Diaspora account and password.
  
<syntaxhighlight lang="bash">
+
[[Category:Podmin]]
VirtualHost "your POD domain.foo"
 
</syntaxhighlight>
 

Latest revision as of 02:46, 15 October 2018

Integrating Prosody with Diaspora

Here you will find all you need to install and set up a Prosody XMPP server integrated with your Diaspora user database. This guide was tested using Debian 7 and Archlinux, but it will probably work well for all GNU distributions. There are several steps and configurations you will need to perform, so read the instructions carefully.

See debian specific instructions at https://wiki.debian.org/Diaspora/XMPP

Understanding

The main goal is to set up Prosody to be capable of comparing the password received by the XMPP client with the hashed password stored on your pod's Diaspora database. Diasporas password hash is done using bcrypt, so we need to extend Prosody to do the same with the received password. To do so, we need to install a modified version of the - mod_auth_sql module, available below.

Since authentication methods can be set per host, you can use an existing Prosody instance with access to Diasporas database.

You can also pull in Diaspora contacts into the roster. They will only be updated on signing into the XMPP account and all modifications to them from the XMPP side will be lost.

Prosody

If you haven't yet, install Prosody. This setup was tested against 0.9.8 and is known to be incompatible with the 0.8 series. Follow the instructions described on their official site.

Once Prosody is installed, you can proceed.

Install bcrypt Lua library

Lua or Prosody don't ship with the bcrypt library. If it isn't in your repositories, you can install it with the following command:

luarocks install bcrypt

Prosody still depends on Lua 5.1, if your distribution is already on Lua 5.2 you may need to change the command to luarocks-5.1 or something similar.

Changes in prosody.cfg.lua

There are a couple of required changes to your prosody.cfg.lua.

Plugin path

Since we're going to install a new module, you should pick a location where you want to store it, for example /etc/prosody/modules. Then tell Prosody to look for modules there:

plugin_paths = { "/etc/prosody/modules" }

Don't worry, Prosody will continue looking for modules in the standard location.

Now download the module to your machine:

curl https://gist.githubusercontent.com/jhass/948e8e8d87b9143f97ad/raw/mod_auth_diaspora.lua > /etc/prosody/modules/mod_auth_diaspora.lua
curl https://gist.githubusercontent.com/jhass/948e8e8d87b9143f97ad/raw/mod_diaspora_contacts.lua > /etc/prosody/modules/mod_diaspora_contacts.lua

Add a virtual host for your pod

VirtualHost "yourpod.example.org"
  authentication = "diaspora"
  -- Uncomment and adjust username and password for MySQL/MariaDB
  --auth_diaspora = { driver = "MySQL", database = "diaspora_production", username = "diaspora", password = "pass", host = "localhost" }
  -- Uncomment and adjust username and password for PostgreSQL
  --auth_diaspora = { driver = "PostgreSQL", database = "diaspora_production", username = "diaspora", password = "pass", host = "localhost" }
  
  modules_enabled = {
    "diaspora_contacts";
  };

Replace yourpod.example.org with your pod's domain and adjust the username and password for the database connection. This is very important!

Read in Prosodys official documentation on how to correctly update your nameserver records afterwards. Also read about setting up the right certificates for your host.

Enable BOSH support

Uncomment following line inside modules_enabled to enable BOSH support:

"bosh"; -- Enable BOSH clients, aka "Jabber over HTTP"

Other recommendations

  • Since we have to transmit the password in plaintext to the server, we strongly recommend to require encryption:
 c2s_require_encryption = true
  • You may also require server to server connections to be encrypted and validate server certificates (diaspora does this already), but your pod won't be able to talk to some xmpp servers which use self signed certificates.
s2s_require_encryption = true
s2s_secure_auth = true
  • Adding a reverse proxy to Prosody's BOSH endpoint under your pods domain on the path /http-bind is a good idea too (check the examples on Vines page). If you have done so, set the proxy setting in diaspora.yml to true and add consider_bosh_secure = true to your Prosody configuration.

Restart Prosody

To complete the setup, just restart Prosody.

Testing

Just use your favorite XMPP client to connect to your pod using your regular Diaspora account and password.