Jingle/SIP setup proof of concept
This tutorial will show you how to configure MongooseIM, Routr (a SIP server) and client applications to demonstrate how the Jingle/SIP integration works.
Prerequisites
We are going to use the following open source software:
-
MongooseIM - https://github.com/esl/MongooseIM
- see How-to-build for details on building.
It's important to remember to run the configuration script with
with-jingle-sip
flag set:tools/configure with-jingle-sip
. Without this, third party dependencies required by the Jingle/SIP translator will not be included in the release.
- see How-to-build for details on building.
It's important to remember to run the configuration script with
-
Routr (SIP server) - https://routr.io
- I recommend downloading binaries for your system from official source.
- Jitsi (XMPP and SIP client application) - https://desktop.jitsi.org
- Otalk - web based XMPP client - https://github.com/otalk/otalk-im-client
- Folow the instructions on otalk-im-client#installing to run it
We will use 2 users xmpp.user@xmpp.example
and sip.user@sip.example
.
Configuring Routr
First the domain sip.example
needs to be added to domains served by Routr.
To do it, paste the following content to config/domains.yml in the directory where Routr was:
1 2 3 4 5 6 7 |
|
Then the sip.user@sip.example
needs to be added to config/agents.yml
like below:
1 2 3 4 5 6 7 8 9 |
|
Now Routr can be started with
1 |
|
If all goes well we'll see the following output:
1 2 3 4 5 6 |
|
It is important to remember the IP address as it'll be used in next point.
A side note
In Routr's logs you may see messages like
1 |
|
or
1 |
|
They can be ignored for the purpose of the tutorial.
Configuring /etc/hosts
In my case the IP reported by Routr was 10.152.1.27
.
Now we need to use this to update /etc/hosts
file like below:
1 |
|
Configuring MongooseIM
At this point I assume that MongooseIM was built with make rel
, that it is running and the current working directory is _build/prod/rel/mongooseim
.
Similar to Routr, MongooseIM also needs to know which hosts to server.
Please replace the default host defined in etc/mongooseim.toml
; the line:
1 2 |
|
should be changed to:
1 2 |
|
Now we need to enable mod_jingle_sip
, please add the following line in modules list (somewhere around line 740 in the same file)
1 2 |
|
More details on MongooseIM configuration you can find in Configuration and in Modules configuration
Now we are registering both users in MongooseIM by calling the following commands:
1 2 |
|
Yes, we need to have the sip.user@sip.example
registered in MongooseIM.
This is needed because a Jingle call can be initiated by a regular XMPP client only when the app knows the other user's full JID.
The easiest way to achieve that is to exchange presence information between these 2 users.
This can happen automatically if 2 xmpp users have each other in the roster.
The roster can be set by us with the following commands:
1 2 |
|
Adding users to Jitsi
Now the sip.user@sip.example
has to be added to Jitsi app.
When the app is opened for the first time it will display a window to configure the user.
Later users can be configured from the Preferences
page.
Adding a SIP user
In order to add a user who connects to the SIP server we need to choose the SIP
protocol from the available networks
in Jitsi.
In the SIP id
field we put sip.user@sip.example
and in the Password
field we put 1234
as in the agents.yml
file.
Now we need to switch to Advanced
options and go to the Connection
tab.
Here we need to unselect the Configure proxy automatically
and put the IP of our Routr
server, port number 5060
and TCP
as the preferred transport.
Adding an XMPP user
Now we have to add sip.user@sip.example
to Jitsi's XMPP network in order to connect this user to MongooseIM over XMPP.
It's very similar to adding a user to Jitsi's SIP network, the only difference is the password,
for the XMPP conection it's test_pass
as set when registering the user in MongooseIM.
Here we also need to go to the Advanced
window and the Connection
tab in order to put the IP addres (the same as before) in the Connect Server
field.
Remember to check the Override server default options
box.
To connect sip.user@sip.exmple
to MongooseIM over XMPP is to cheat Jingle a bit, so that the client app for user sip.xmpp@xmpp.example
can start the Jingle call.
When Jitsi connects this user, it will likely display a warning about the server's certificate.
This is because by default MongooseIM is configured with a freshly generated, self-signed certificate.
We can click Continue anyway
button in order to proceed.
Adding user to Otalk
Please follow the instructions on https://github.com/otalk/otalk-im-client#installing in order to compile and run the app. If all goes well, you should see the following message printed in the console:
1 |
|
This means that the app is hosted on http://localhost:8000
.
At this point I also recommend opening wss://localhost:5285/ws-xmpp in the same browser. This endpoint works correctly only for WebSocket connections but most probably you will be prompted about the certificate. This is again due to the self-signed certificate. We need to add an exception for this certificate in order to successfully connect from Otalk.
Now let's open http://localhost:8000 where the Otalk app is hosted.
In the Log in
section put xmpp.user@xmpp.example
in the JID
field and test_pass
in the Password
filed.
The default WebSocket endpoint in the WebSocket or BOSH URL
field needs to be changed to:
1 |
|
Mind the wss
protocol, Otalk will not connect the user over WebSockets if for example https
is put in the field.
Now we can hit the Go!
button and the xmpp.user@xmpp.example
will connect to MongooseIM.
Making a call
On the left side we can see that the user already has sip.user@sip.example
in the roster and there should be a green dot indicating that the user is online.
When we click on the contact, the Call
button should appear allowing us to initiate the call.
In Jitsi, the following window should pop up:
Behind the scene the following SIP request was send from MongooseIM to Routr.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 |
|
And Routr sent the Ringing
response code to MongooseIM as soon as the Jitsi app displayed the incoming call window:
1 2 3 4 5 6 7 8 9 |
|
Summary
The example above showcases how you can use Jingle/SIP switch with the available open source software. Sonetel, who are this feature's sponsor, operate on a slightly different use case and utilize more of the functionality with their proprietary software. Current implementation makes following assumptions:
- The peer-to-peer stream is always encrypted.
This means that MongooseIM expects element
<fingerprint>
as described in XEP-0320: Use of DTLS-SRTP in Jingle Sessions to be in the content description. Not every open source XMPP client supporting Jingle supports this encryption. - MongooseIM expects that the
200 OK
response contains at least one ICE candidate to set the peer-to-peer connection up.
This makes the current implementation a bit limited, but on the other hand the basic integration between XMPP and SIP world is already there. Based on the current state it can be improved and extended if needed.