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:
- Full JID lookups on the fly, SIP<>JID mapping on the fly! (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
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
Kelpie cannot function without XMPP/SIP DNS configuration, so you will need to extend your DNS with the following:
- add a rule for _xmpp-server._tcp.{kelpie.hostname} pointing to your Kelpie server port 5269
- add a rule for SIP _sip._udp.{kelpie.hostname} pointing to your SIP server port 5060
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|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 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 status, set your proxy to reply with SIP 500 or use the following parameter: com.voxbone.kelpie.feature.subscribe.force-emu=true
For more options check the preferences file
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;
}
}
In SIP Peerings, create a new group for your Kelpie Gateway, and within the group define your Kelpie SIP listener details matching a set prefix (ie: kelpie.user+domain) and remove it with a rewrite action:
Name: kelpie-gw
IP Address: 1.2.3.4
Hostname: (leave empty)
Port: 5090
Weight: 1
Callee Prefix: kelpie
Create a rule to strip the matched prefix and assign it to the gateway (rewrite_rule_set):
Match Pattern: ^(kelpie\.+)(.*?)$
Replacement Pattern: \2
Description: Kelpie normalizer
create a new dialplan entry to match a prefix (ie: kelpie.user+domain) route the calls to your kelpie gateway:
<include>
<extension name="kelpie">
<condition field="destination_number" expression="^kelpie\.([^\@]+)\@?(.*)$">
<action application="set" data="continue_on_fail=true"/>
<action application="set" data="hangup_after_bridge=true"/>
<action application="bridge" data="sofia/${use_profile}/@kelpie.host.ext:5090"/>
</condition>
</extension>
</include>
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.
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