Monday, December 17, 2007

Interim information on integration OCS and Asterisk

Disclaimer: This guide hasn't been tested and verified like the Exchange UM guide - it may not be 100% accurate. It is not a step-by-step detailed and assumes you know your way around trixbox, sipX and OCS, or at least have configured Exchange UM using my guide. It is provided only for early adopters that want to experiment in a test environment. It WILL NOT work with the trixbox version (2.2) used in the Exchange UM guide. See my post here on issues with Asterisk and OCS integration FIRST. Please feel free to provide comments, feedback and results of your own testing (via email please).

Overview: In order to make this work, we need to install the follow-me module in Asterisk, define a custom voicemail macro for follow-me, and configure some new dial rules in sipx. I use a single extension range (400-499), and use sipx to do some fancy number transformations to allow calls to flow back and forth correctly.

Step 1: Install the folllow-me module in freePBX.

Step 2:  Edit extensions_custom.conf and add the following code;

[custom-exchangevm]
exten => s,1,NoOp(Entering custom-exchangevm for a call to ${DNID})
exten => s,n,Set(EXTTOCALL=${BLKVM_BASE})
exten => s,n,NoOp(Sending to Voicemail box ${EXTTOCALL})
exten => s,n,SIPAddHeader(Diversion: <tel:${EXTTOCALL}>\;reason=no-answer\;screen=no\;privacy=off)
exten => s,n,Dial(
SIP/222@sipx.lithnet.local|30)

Step 3: Configure follow-me for your extensions. The extension list should contain both the extension number, and the extension number followed by a numerical prefix. I used the number 4. You can use whatever you want, as long as you can route it in your dial plan - adapt this guide as appropriate. Make sure the the external numbers are followed by '#' so the module knows it needs to route outside of asterisk. Select 'Custom app' for the no answer destination, and type custom-exchangevm,s,1 in the text box.

image

Step 4. Configure an outbound route. You can either create a new route to send 4xxx calls to sipx, or add 4xxx to your existing sipx route as shown below.

image

Step 5. Now we need to configure sipX to strip off the prefix ('4') we added, and replace it with a plus sign (+). OCS requires that numbers be in E164 format, I'm not going to go into that in detail, but for testing purposes, we can just add a + at the start of the number, and it will be happy.

Add the following to your /etc/sipxpbx/external_mappingrules.xml file.

   <!-- Asterisk-OCS Dial Rule -->
    <userMatch>
      <userPattern>4xxx</userPattern>
      <permissionMatch>
        <transform>
          <user>+{vdigits}</user>
          <host>ocs-med.lithnet.local</host>
          <urlparams>transport=tcp</urlparams>
          <fieldparams>q=0.9</fieldparams>
        </transform>
      </permissionMatch>
    </userMatch>

Add this to your external_authrules.xml file:

  <hostMatch>
    <!--OCS Mediation Dial Rule (IPs and hostnames of your OCS mediation and OCS comms server-->
    <hostPattern>ocs-med.lithnet.local</hostPattern>
    <hostPattern>192.168.0.80</hostPattern>
    <hostPattern>ocs-main.lithnet.local</hostPattern>
    <hostPattern>192.168.0.70</hostPattern>
    <userMatch>
      <userPattern>.</userPattern>
      <permissionMatch/>
    </userMatch>
  </hostMatch> 

Step 6: In the sipx web interface, add a new dial rule called OCS-Asterisk Dial Rule. In the dialed number field, put + as the prefix, and select ‘3 digits’ (or however many digits you have in your extension). Leave all the ‘required permissions’ unticked. In resulting call, leave the prefix blank, and select  ‘variable part of dialed number’. Select Asterisk as your gateway. Activate your dial plans and you are done.

image

Step 7: In the OCS Management console, right click on your mediation server, and click properties. Type the IP Address of your sipX server as the next hop destination.

image

Step 8: Configure users for PBX integration. Note the "+" before the number.

image

Step 9: Add an outbound route in OCS by right clicking on your forest in the OCS Management Console, selecting 'Voice Properties', clicking on the 'Routes' tab, clicking 'Add', and entering the information shown below. The regular expression basically says to route all calls to numbers beginning with a + to the Mediation Server.

image

Step 10: Add normalization rules. Back on the Voice Properties tab, click Location profiles and add a new profile. Add a new normalization rule. Use the information below to create a basic normalization rule. This example will take any 3 digit number starting with '4', and append a + sign to it. This gives us a number that is formatted and can understood by the dial rule we set up in step 9.

image

That should be it. Add other normalization and dial rules as required to accommodate your needs. OCS uses SIP/TLS for encrypted communication between OCS servers and clients by default. If you run into difficulties and need to troubleshoot, turn off TLS and you will be able to see the SIP packets, rather than encrypted TCP traffic.

Once again, I stress that this is not a complete guide. Just something to get started with, as many people have been asking for this. Please contact me via email if there are any errors you come across in this post.

OCS/Asterisk integration Update

Many people have been eager to find out what is going on with the Asterisk and OCS integration guide. First, let me say I haven't forgotten about it! There are a few problems that myself and others who are working on this with me are trying to resolve.

As it stands, OCS and Asterisk don't want to play nice together. Each product seems to have a unique bug in it, that unfortunately only shows up in combination with the other. I'll give you a short explanation of each problem. If you haven't already done so, I recommend you read up on SIP and RTP, otherwise this probably wont make any sense to you.

The OCS bug

The first RTP packet sent by the OCS mediation server is completely broken. There are two problems with this packet

1. The packet is being sent to UDP port 0, not the port defined in the SIP Session description (SIP/SD) packet. Port 0 is a reserved port, and should never be used. The remote host correctly responds with an ICMP destination port unreachable message.

2. The second problem with the packet, is that it is sent to the SIP gateway, not the RTP endpoint specified in the SIP/SD packet. So even if the packet was sent to the correct port, its being sent to the wrong host. In our setup, the Mediation Server is sending this RTP packet to port 0 of the sipX server. It should be going to the RTP port of the Asterisk server.

image Initial RTP packet sent by the OCS Mediation server to port 0

Now, as far as I can tell, this happens even with the 'OCS approved' gateway products. I reviewed some SIP traces of communication with a Dialogic gateway, and saw the same behaviour. Subsequent RTP packets appear to travel to the correct destination server and port, and other gateways ignore and compensate for the bad/missing packet. This is where Asterisk's bug comes into play

The Asterisk bug

Now, as we all know, UDP is a stateless protocol, that does not guarantee reliability or delivery as TCP does. Packets may arrive out of order, or go missing completely. As VoIP is time-sensitive, we use UDP for the audio data, because we would rather some packets go missing, than all of the arrive, but possibly be delayed. So a UDP implementation must never rely on the delivery of a UDP packet.

From my own behavioural observations (and I could be wrong), it seems the Asterisk uses the initial RTP packet as a 'trigger' to start proxying the RTP traffic it receives from both endpoints. This first RTP packet is used to inform the other endpoint that it is about to start receiving data, but it never contains audio data (as shown in diagram above). As this packet never arrives, Asterisk just seems to wait indefinitely, ignoring all subsequent RTP packets from the mediation server, and our SIP phone. Given that there is no guarantee of receiving this packet, Asterisk should not be waiting for it, and should proceed with the correctly formed RTP packets it receives from the OCS Mediation Server.

The good news

There have been some reports of success with the newer build of Asterisk that comes with the new beta version of trixbox. I have not personally tried this, and coming up to Christmas, I'm not sure I will get time to until the new year. However, for those that do not want to wait, here is a post with some bits and pieces to get you started.