Home
This is a development fork of Voxbone's Kelpie. Please make sure you check the original repository to see what fits you best! Most general purpose changes are being merged back to the original SVN once verified, while some experimental features and bad practice implementations might only exists here while testing or for the time being. Make your choice based on your needs.
Currently Forkusing on:
- Jingle bells & whistles (XEP-0166/XEP-0167) implementation
- Full JID lookups & feature probe on the fly for all SIP <-> JID mapping (user+domain@kelpie)
- Exposing additional user-configurable parameters (features, behavior, hacks, etc)
- Implements support & options for additional methods (SIP CANCEL, XMPP Reject, XMPP Errors)
- Extended support for SIP INFO DTMF as alternative to default RTP EVENT RFC2833 DTMF
- Extended support for OPTIONS session probing and presence/NOTIFY delivery (SIP side)
- Extending XEP implementation/support (http://xmpp.org/xmpp-protocols/xmpp-extensions/)
- Video interoperability improvements & extended testing against Video endpoints
- Error handling improvements (internal)
See server-properties for the available extra functionality or explore the code.
Kelpie attempts to make SIP endpoints appear as XMPP endpoints and vice-versa, and it fully supports:
- Voice Calls
- Video Calls
- Instant Messaging
- Presence
The gateway only focuses on protocol translation (SIP to Jingle/Gingle) and media path/relay (ICE-STUN RTP). For routing traffic you will need:
- SIP proxy/server/pbx (such as Kamailio, Asterisk, FreeSWITCH, etc)
- Federated XMPP server (your own own or /gtalk)
XMPP and SIP methods are generally mapped to their corresponding format on each side, for example:
...
initiate <> INVITE
transport-info <> INVITE/SDP
candidates <> INVITE/SDP
session-info <> UPDATE/RE-INVITE
reject <> CANCEL
presence <> SUBSCRIBE/NOTIFY
message <> MESSAGE/INFO
terminate <> BYE/CANCEL
...
In order to use Kelpie, you need to have a server with a public IP address, access to a DNS server capable of DNS SRV requests. In this quick setup we'll assume you'll run Kamailio and Kelpie on the same box. You will also need to have a 3rd party xmpp account we'll refer to it as [email protected].
Kelpie in Action: Video Demo | RatLab NightCall | SIP to GTALK Video Call
SIP & XMPP services cannot function as intended without SRV pointers, and Kelpie needs both - so you will need to extend your DNS with the following example:
- add a rule for _xmpp-server._tcp.{kelpie.hostname} pointing to your Kelpie XMPP port 5269 (mandatory!)
- add a rule for SIP _sip._udp.{kelpie.hostname} pointing to your Kelpie SIP port 5060 (or other port)
Check out the full Kelpie mod sources by running:
git clone git://github.com/lmangani/kelpie.git kelpie
then run the installation script (install will require maven2 and java)
cd kelpie
./install.sh
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
...
Kelpie is now ready and installed. After configuring the server properties, you can manage the service:
/etc/init.d/kelpied {start|stop|restart|status}
##Configuring Kelpie Update the properties file "/usr/lib/kelpie-0.1/conf/server.properties" and configure, the required IP Address, SIP port for kelpie (example 5090), the details to your SIP gateway (defaults to 5060) and the port range to be used for RTP Relay:
com.voxbone.kelpie.ip={kelpie.server_ip}
com.voxbone.kelpie.sip_port=5090
com.voxbone.kelpie.sip_gateway={sip.server_ip}
com.voxbone.kelpie.hostname={kelpie.hostname}
com.voxbone.kelpie.rtp.min_port=40000
com.voxbone.kelpie.rtp.max_port=50000
In the same file, static SIP<>XMPP Mappings can be defined as follows:
# Example: map juliet to sip:juliet@{kelpie.hostname}
[email protected]
# Example: map echo@yourdomain to the google echotest bot
[email protected]
To allow calls from/to contacts without prior invitation/pairing/configuration (important):
com.voxbone.kelpie.map.strict=false
To control the XMPP/Jingle features being presented:
com.voxbone.kelpie.feature.video=true
com.voxbone.kelpie.feature.pmuc=true
com.voxbone.kelpie.feature.sms=true _(for Google Voice SMS [email protected])_
If you need a separate route for SIP MESSAGE methods, use the optional property:
com.voxbone.kelpie.im_gateway={im.server_ip}:5060
If you wish to turn the SIP username@ into XMPP Nickname, use the optional property:
com.voxbone.kelpie.feature.chat-nickname=true
If you need force RPORT detection/use for SIP NOTIFY presence (broken Contact header):
com.voxbone.kelpie.feature.subscribe.rport=true
If you want Kelpie to emulate SUBSCRIBE statuses, set your proxy to reply with SIP 500 or use the following (always online):
com.voxbone.kelpie.feature.subscribe.force-emu=true
OpenKelpie has basic support for XEP-0166 and XEP-0167 (Jingle) and supports the pre-standard versions of those protocols that Google Talk currently uses (Gingle). If you plan interoperating with Google/GTalk services, you will need to decide if you want to do so by using either Jingle/Gingle or both (and let the remote server/party choose). There are benefits and drawbacks to both dialects currently, so test and determine/share your own best results.
OpenKelpie currently defaults the Gingle dialect to interact with Gtalk as its quite stable, while Jingle support is readily available and can be activated as follows:
com.voxbone.kelpie.jingle=true
FEEDBACK ON JINGLE IS KEY TO IMPROVEMENT! IF YOU FOUND A BUG, PLEASE RAISE AN ISSUE!
For more details and options check the latest project preferences file or consult the parameters Wiki page
the "simplest" way to get kamailio working is to configure it to use userloc, and text db update the LOCATION section to requests to unknown users to kelpie (if not me, assume xmpp)
if (!lookup("location")) {
switch ($rc) {
case -1:
case -3:
# t_newtran();
# t_reply("404", "Not Found");
forward({server_ip}:5090);
exit;
case -2:
sl_send_reply("405", "Method Not Allowed");
exit;
}
}
Configure a presence enabled SIP client (like jitsi) to register to your SIP server (as sip:romeo@{kelpie.hostname}) and make sure to have enabled "Peer to Peer" presence. Add sip:juliet+gmail.com@{kelpie.hostname} to your contact list, juliet should see an invitation on her jabber account. Likewise, Juliet should add romeo@{kelpie.hostname} to her account, and Romeo should see a subscription request.
NOTE: Away/Busy GTalk contacts will NOT receive calls. Set your presence status accordingly!
Romeo is using SIP. Juliet is using Jabber/XMPP. How can they talk/video/chat?
Romeo (sip:romeo@{kelpie.hostname}) calls Juliet on GMail ([email protected]) from a SIP phone using:
sip:juliet+gmail.com@{kelpie.hostname}:{kelpie.port}
Juliet will see an invitation and once accepted, receive audio and video calls as well as IMs. Juliet, the Jabber/Gtalk contact, can also add Romeo's SIP phone to her contacts by inviting:
romeo@{kelpie.hostname}
Kelpie will accept the invitation and will immediately forward calls, videocalls and IMs to the registered SIP endpoint. It's that easy!
Say that the sip endpoint is an IVR or other application expecting a pin number or digits to be dialed. What do you do since gtalk doesn't have a dial pad? In the IM/GTALK window just type:
/dial:123
This will send the digits "1 2 3" to the SIP endpoint as DTMF RTP EVENT (RFC 2833) If you wish to use SIP INFO DTMF instead, just change the following parameter settings:
com.voxbone.kelpie.feature.dtmf-info=true
com.voxbone.kelpie.feature.dtmf-duration=160
Another way to work around the lack of keypad is to use the fantastic INUM network. Voxbone has a direct peering agreement with Google Voice, allowing free calls to any INUM destination directly from Google Voice and GTalk dialplans, and when dialing a +883 number you will get the full phone gtalk widget, including a keypad. Just get a number, map it to your services and voila'.
Try for yourself by using the CALL PHONE option in gtalk, with the following number:
+883510000000092