Sunday, April 29, 2007

Accessing Exchange 2007 Unified Messaging: Part 4 – Configure the sipX Server

--------------------------------------
STOP! This page has been replaced by a new version based on sipX 3.8 and Centos 5. This page will no longer be updated, and is kept for reference only. Please see the replacement page for updated instructions.
-------------------------------------

Initial Configuration

Start your sipX VMWare virtual machine. During start up, the OS will detect that a network card has been removed. Select Remove Config to remove this card. You will then be prompted with a message that a new network card has been detected. Select Configure and assign a fixed manual IP address to this PC.


Log in as root, with the password voipjots and change the root password by typing passwd at the command line. Remember this password, as you will not be able to log into the server without it. First thing we need to do is install operating system updates, then we will download the updated sipX repositories, and upgrade sipX to the latest version (I had lots of issues getting version 3.0 – the installation in the VM – to work, but 3.6 (the latest stable release at the time I wrote this works much better). Run the following commands in this order, and to all the Windows kids like me, remember that Linux is case sensitive, so take note of the uppercase X in the URL below (yes I stuffed it up myself and it took me about 20 minutes to work out why it was failing – silly muppet).

yum –y update
wget -P /etc/yum.repos.d/ http://sipxecs.sipfoundry.org/pub/sipXecs/sipxecs-stable-centos.repo
yum –y update sipxpbx

This may take some time depending on how many updates are needed. There seems to be a lot of packages installed, that I'm sure could be removed. However, being an MCSE who spends very little time using Linux, I have no idea what's what. If someone who knows what they are talking about wants to suggest the packages that can be removed, I'll include them in this documentation.

Once the packages have been updated, we need to set the hostname for this server. Use the nano editor to edit the network configuration file, and change HOSTNAME to sipX.lithnet.local

nano /etc/sysconfig/network


When done, press Ctrl-X, then Y, then enter to save the file.

Now we need to fix the SSL certificates. If you have a CA on your network, you can have it generate a certificate for these purposes. Otherwise, we can just generate a self signed certificate using the following commands.

cd $HOME/sslkeys
rm –f *
/usr/bin/ssl-cert/gen-ssl-keys.sh

This will prompt you for several pieces of information. Enter the appropriate information, and the following values when prompted.

CA Common Name: SelfSigned
SIP domain name: lithnet.local - The domain name of your installation
Full DNS name for the server: sipx.lithnet.local - Enter fully qualified hostname of your sipX server

Type the following to install the certificate.

/usr/bin/ssl-cert/install-cert.sh sipx.lithnet.local

Now we need to configure the Exchange gateway and rules. Normally, this XML is generated automatically by the web interface as we modify the gateway and dial plan options. We have to do this manually, because the web interface doesn't provide us a way to force sipX to use TCP for a particular gateway. If we configure our dial plans through the web interface, sipX tries to contact Exchange first using UDP, which more often than not results in a timed-out call. The sipX team is working to more natively support Exchange configuration through the web interface in the future. I will keep you posted.

At the sipx command prompt, type

wget -P /etc/sipxpbx/ http://lithiumblue.com/config/external_mappingrules.xml

to download the preconfigured mappingrules file needed to force TCP communication with Exchange. Type nano /etc/sipxpbx/external_mappingrules.xml to modify the file and replace the hostname values with your own. If for some reason you cannot download the file with wget, you can type it out manually as it appears below.

<?xml version="1.0" encoding="UTF-8"?>
<mappings xmlns="
http://www.sipfoundry.org/sipX/schema/xml/urlmap-00-00">
<hostMatch>
<hostPattern>${SIPXCHANGE_DOMAIN_NAME}</hostPattern>
<hostPattern>${MY_FULL_HOSTNAME}</hostPattern>
<hostPattern>${MY_HOSTNAME}</hostPattern>
<hostPattern>${MY_IP_ADDR}</hostPattern>
<userMatch>
<!--ExchangeDialRule-->
<userPattern>2xx</userPattern>
<permissionMatch>
<transform>
<host>dc1.lithnet.local</host>
<urlparams>transport=tcp</urlparams>
<fieldparams>q=0.9</fieldparams>
</transform>
</permissionMatch>
</userMatch>
<userMatch>
<!--ExchangeVoicemailRule-->
<!--Note this is only to handle diversions for local sipX 3xx extentions-->
<userPattern>3xx</userPattern>
<permissionMatch>
<permission>Voicemail</permission>
<transform>
<user>222</user>
<host>dc1.lithnet.local</host>
<urlparams>transport=tcp</urlparams>
<headerparams>Diversion=&lt;tel:{digits}&gt;;reason=no-answer;screen=no;privacy=off</headerparams>
<fieldparams>q=0.9</fieldparams>
</transform>
</permissionMatch>
</userMatch>
</hostMatch>
</mappings>

The above rule ensures that calls for 2xx are sent to the Exchange server, and that sipX only communicates with it using SIP/TCP. It also enables diversion to Voicemail for calls to the sipX extensions (3xx). This is independant of the procedure to setup Trixbox/Asterisk to divert to voicemail. The sipX and Asterisk diversion configurations are completely independant of each other.

Now we need to tell sipX that it is responsible for routing calls to 2xx. Without this the calls would be rejected. At the sipx command prompt, type

wget -P /etc/sipxpbx/ http://lithiumblue.com/config/external_authrules.xml

to download the preconfigured authrules file. Type nano /etc/sipxpbx/external_authrules.xml to modify the hostname in this file.

<?xml version="1.0" encoding="UTF-8"?>
<mappings xmlns="http://www.sipfoundry.org/sipX/schema/xml/urlauth-00-00">
<hostMatch>
<!--ExchangeDialRule-->
<hostPattern>dc1.lithnet.local</hostPattern>
<userMatch>
<userPattern>2xx</userPattern>
<permissionMatch/>
</userMatch>
</hostMatch>
</mappings>

In order for sipX to use these files we created, we need to add some lines into the config file. Type nano /etc/sipxpbx/sipxconfig.properties.in, scroll through the file, and locate the following lines or add them to the end of the file.

mappingRules.externalRulesFileName=/etc/sipxpbx/external_mappingrules.xml
authRules.externalRulesFileName=/etc/sipxpbx/external_authrules.xml

Restart the server using the following command

reboot

After the server reboots, open your browser and navigate to the sipX server i.e. http://sipx.lithnet.local. If all goes well, you should be presented with the screen below


Click Configuration, and accept the SSL certificate warning.
NOTE: There is approximately a 2 minute delay between the sipX services starting and being available. If you get an error message when loading the page, wait 2 minutes and try again.
Login with the username superadmin, no password is required. First things first, let's set the superadmin password. Click on Users on the top menu, the Users submenu, then on superadmin. Change the value for PIN to something secure. We won't be using the superadmin account to connect to the sipX server over the phone, so it's ok to use an alphanumeric password. Press OK when you are done.

Gateway Configuration

Now we need to add a gateway to allow sipX to communicate with the Exchange Server. Click Devices on the top menu, Gateways, and select Unmanaged Gateway from the Add New Gateway drop down list. Type the following information and press OK.

Name: ExchangeUMServer
Address: dc1.lithnet.local
Serial Number: Leave Blank – not used for unmanaged gateways


If you want to make calls out of Exchange then we need to add another unmanaged gateway back to the Asterisk server. Type the following information and press OK.

Name: AsteriskServer
Address: asterisk.lithnet.local
Serial Number: Leave Blank – not used for unmanaged gateways

Dial Plans

Now we need to configure the dial plan. Dial rules are used to route incoming calls to the appropriate gateway. Click System on the top menu, followed by Dial Plans. In the Add New Rule drop down box, select Custom as our dialing rule type. Enter the following information and press OK.

Tick the Enabled box
Name: AsteriskDialRule
Description: Forward calls for 4xx-8xx to the Asterisk Server
Dialed Number, prefix: 4, and select 2 digits from the drop down list. Click Add to add new lines.
Dialed Number, prefix: 5, and select 2 digits from the drop down list
Dialed Number, prefix: 6, and select 2 digits from the drop down list
Dialed Number, prefix: 7, and select 2 digits from the drop down list
Dialed Number, prefix: 8, and select 2 digits from the drop down list
Resulting Call, Prefix: Leave the prefix blank, and select Entire Dialed Number from the drop down list
In the More Actions drop down box, select AsteriskServer under Existing Gateways.


Press OK to save and return to the dial plans list. Move the new dial plan to the top of the list, by ticking the box next to the new plan, and pressing Move up repeatedly. Order does matter, so it is at the top. If you don't plan on using the sipX server for any other SIP traffic, you can delete the other dial plans.

Activate the new plans by clicking the Activate button, and pressing OK when prompted for confirmation.

Add an Extension

We will now add an extension for testing purposes. This will help in your troubleshooting efforts should something not work. Click on Users on the top menu, click the Users menu item, and click Add User. Click Show Advanced Settings at the top of the page. Change the user ID to 300, assign a first name, last name, PIN, and SIP password to the account. Take note of the SIP password or change it to something you are going to remember. Press OK when you are done.


Configure the Fully Qualified Domain Name

Click the System menu and the Domain menu item, and enter the fully qualified domain name that the sipX server will use. When prompted, ensure you activate the new dial plans for our configuration changes to take effect.

Please note that the FQDN must be the same as the value you configured for the gateway on the Exchange Server. When Exchange sends a request to the gateway, it appends the given hostname or IP address to form a SIP address. I'll use the example of the Exchange Server making an outbound call to extension 400. If you have the sipX server's IP of 192.168.0.50 configured in the Exchange Server as the gateway address, then Exchange will address the SIP packets to
400@192.168.0.50
If you have the hostname configured, it will address the SIP packets to
400@sipx.lithnet.local

If sipX is configured with the domain name sipX.lithnet.local, but the packet is addressed to 400@192.168.0.50, sipX will NOT recognize that it should process the packet. Your Exchange Server's event log will contain "483 Too Many Hops" error events logged by the Unified Messaging Service, and calls to the Exchange Server will fail.

This took me DAYS to work out what was going on here, so please, save your sanity by going back now and double-checking this.

We have now completed the configuration of the sipX server.



35 comments:

RKingslan said...

On page 5, the detail starts out as sipX, changes to Asterix, then back to sipX.

Was this page intended fully for sipX, or for Asterix as well? I suspect sipX with thoughts toward Asterix, which doesn't seem to be posted yet. True?

Ryan said...

Hi RKingslan,

If you don't plan on using Asterix, you can just leave out the Asterix parts of this guide. You can use sipX on its own. You only need Asterix if you want to connect to a PSTN network.

Ryan

Nate said...

I followed the directions pretty closely and get the following message when getting to the config part...

HTTP ERROR: 404
/sipxconfig Not Found
RequestURI=/sipxconfig


Any help???? I am a MS guy so this is all greek to me :)

Thanks,
Nate

Mame said...

Hi, I am trying to set up the sipX Server and always getting an connection error on accessing for updating the repositories. Is the posted link still valid? If I login on the sipfoundry page it does not seems to be...
Many thanks for support.
Mame

Ryan said...

Hi nate/mame,

I followed up with the sipX team, and the repos have been moved to a new location - but were also missing. The problem has been fixed, and I have updated the post with the new location

http://sipxecs.sipfoundry.org/pub/sipXecs/sipxecs-stable-centos.repo

Ryan

Anonymous said...

Hi,
I am having a bit of trouble getting the Exchange to work correctly even though I think the sipX is the issue. I can call from phone to phone. From one phone I can call voicemail and I get that box's personal voicemail. I can call auto-attendant fine as well. The problem is when I call from ext to ext I get the general voicemail box not the ext. actual personal box. I have call forwarding on to box 222 and voicemail on sipx off. I have inserted the external mapping rules and am still having no luck. Any help you could give would be great!!!! It's driving me nuts, had this problem for 3 days. I can be emailed at joshg@vodaci DOT com

Thanks
Josh

Anonymous said...

Hi Ryan,
Thanks for sucha quick answer...worked fine :-)
Now I am facing same issue as Nate do. In fact I have a problem in installing my certifikate. (followed your very clear instructions)
Message is:
SSL certificate not found.
SSL certificate: sipx.xy.com.crt
cp: cannot stat 'sipx.xy.com.crt': No such file or directory

Do you have any help for me in that case. I never ever used Linux/Unix before....therfore I am lost at all.

Cheers,
Mame

Ryan said...

Hi Mame,

Remember that linux is case sensitive, so double check that the certificate file doesn't have any capital letters in it. type ls -l at the command line to see a list of the files in the folder.

Were there any problems or errors reported when actually creating the certificate?

Best to email me - ryan at lithiumblue dot com - if we uncover a problem, I will post the details for everyone else as well.

James said...

Hi Nate,

Did you find a resolution to your problem? I get the same message after many attempts:

HTTP ERROR: 404
/sipxconfig Not Found
RequestURI=/sipxconfig

I do not receive any error messages up until this point and the updates downloaded ok.

James.

Ryan said...

Hi James,

I am working on this problem with the sipX team at the moment. It might be a problem with the build. Will keep you posted.

Ryan

Aaron said...

Before you run yum -y update sipxpbx

you need to edit the sipxecs-stable-centos.repo file in /etc/yum.repos.d/

Change gpgcheck from =1 to =0 and the update will work.

One of the files isn't signed properly.

-Aaron

Ryan said...

Hi Aaron,

I have had the sipX guys fix the repo file. It should be fine now.

I have also updated the "yum update" commands to better handle dependencies since the repos have been changed.

Ryan

Anonymous said...

udsvqzvHi,

I have a problem with the external mapping rules and the Auth rules. I worked down te configuration of the SipX server. Everything goes well, even after installing the security-certificate, but untill adding the rules. I copied and pasted the rules from the site with Putty and entered my Exchange Server into the file as shown in your guide. The SipX config website runs untill the moment I add them. After that, the website is offline. Even after removing the files completely again and removing the lines in the "sipxconfig.properties.in" file, I can't get the website to work again.
The first problem that arises during the configuration I have, is that in your guide the path is "/etc/sipXpbx/" with a capital X. However, when I type this in nano, it says this file doesn't exist. With a lower case x I can add the files. Is this of influence? Or could it be, the http paths given in the rules (http://www.sipfoundry.org/sipX/schema/xml/urlauth-00-00) don't exist anymore?

With regards, Roel

Ryan said...

Hi Roel,

I'd avoid cutting and pasting into Linux altogether. Windows and linux have different carriage return/line feed characters. I'm not sure how putty handles this, but my advice would be to first retype out the mapping rules into nano manually. It might take a bit longer, but at least you know it is right. They definitely work.

I do apologise for the capital X in the path. You are correct, in that it should be lowercase. Autocorrect on my blog editor has kicked in a few times where it should not have.

The schema URL is just a place holder, there is no file at that location and never has been. The sipX team have confirmed this in the past with me.

Ryan

Anonymous said...

Hi Ryan,

manually adding did the trick. Now I went on configuring the SipX server. I added the dialplans and added the testing extension of 300.
After doing so I went on testing this. i can call myself, the call comes in to the second line. I think I can call the trixbox as well. however when dialling to the Exchange Server I don't get an error number on Xlite, just the message that the "Call failed: forbidden". What could cause this to happen?
Is something still misconfigured or could it be that the Exchange Evaluation version (32-bit) doesn't support this?

Regards, Roel

Anonymous said...

In addition to my earlier post, I just now noticed a failure during reboot.

The failure is:
sipXpbx configuration problems found:

check sipregistrar
/etc/sipxpbx/fallbackrules.xml

error at file /etc/sipxpbx/fallbackrules.xml, line 17
message: Datatype error: Type: InvalidDatatypeValue exc
Value'' does not match regular expression facet "({<>ä-zA-Z0-9[\]?{}\-]+)'

Attempting to start despite configuration problems

Could this be of any influence and if yes, what to do about it?

regards, Roel

Ryan said...

Hi Roel,

There is no difference between the 32 and 64 bit version of Exchange from a technical point of view. One is licensed for use in a production environment, the other is only for testing purposes.

You need to find the illegal character that is in your fallbackrules.xml file. The error means that there is a character in line 17 of this file that is not one of the allowed characters - ({<>ä-zA-Z0-9[\]?{}\-]+). If you can't find the problem, I would suggest copying and replacing that XML file with the one out of the original sipx VMDK.

Ryan

Anonymous said...

Hi Ryan,

Your link to external mappings:

http://lithiumblue.com/config/external_mappingrules.xml

is coming accross as 'not authorized'

Jay

Anonymous said...

Hi Ryan,

Your link to the external mappings to force TCP is coming across as 'not authorized'...

i found another file at http://track.sipfoundry.org/secure/attachment/11560/external_mappingrules.xml

is this valid/the same?

Ryan said...

Sorry guys,

All fixed. ACLs didn't inherit from the previous folder because i cut+pasted instead of copy+pasted.

And no, that link is a different file.

Ryan

Anonymous said...

Hi again Ryan,

I was able to get the SipX server working with Exchange last night, but only after creating a second 'dial plan' with prefix 2 (2 digits from drop down) and then pushing that to the unmanaged ExchangeUMServer Gateway, which you advised us to set up in a previous step. You may want to add that to the tutorial.

Jay

Ryan said...

Hi Jay,

Thats very strange. The data in external_mappingrules.xml contains the same information generated by the sipxconfig dial plan page, with the addition of 'transport=tcp' appended to the URI. You shouldn't have had to add those rules in, but I did update this guide on the weekend, and its possible I have made a mistake somewhere. Would you be able to send me your external_mappingrules.xml, mappingrules.xml and fallbackrules.xml files so I can see why this happened? ryan@lithiublue.com

Ryan

Ryan said...

Thanks for sending those files Jay,

There was a mistake in the guide that I have now corrected. A question mark was missing from the end of the first line

<?xml version="1.0" encoding="UTF-8">

Should have been

<?xml version="1.0" encoding="UTF-8"?>

The file that was unavailable for download at the time was ok, but something must have happened in the cut+paste to this guide.
I have fixed this, just nano your external_mappingrules.xml file, add this in, and delete the dial plan you configured and all should be fine again.

Thanks very much for taking the time to send this in.

Ryan

Benn Hailes said...

Hi, i have followed your guide and I have run into problems, when starting sipx, the hostname, apache and ssl tests fails, also i get "syntax error on line 30 of /etc/sipxpbx/httpd-sipxchange-common.conf"
AuthName takes one argument, the authentication realm.

I have tried to edit this, but gets overwritten when sipX starts,

Any help would be appreciated

Anonymous said...

Hi Ryan,

Tried that last night, no go... I still had to have the rule in sipX to push 2xx along to ExchangeUM gateway. I have tried adding the '?' via nano, completely deleting the file and redownloading/editing i, and restarting the machine between changes.

Ryan said...

Hi Ben,

That file is generated from /etc/sipxpbx/httpd-sipxchange-common.conf.in.

If you make the required change to that file, and restart the sipx service, that should hopefully fix the problem.

Ryan

Ryan said...

Hi,

At the command prompt, type

sipx-validate-xml /etc/sipxpbx/external_mappingrules.xml

This will tell you if there are any errors in the file. Delete the mappingrules.xml file, and reactivate your dial plans.

Ryan

Nate said...

Hey Everyone,

I am starting my sipX portion from scratch. This week we just cut a PO for Cisco VoIP, Exchange UM and OCS to control all of our voice functionality. That comes with a price tag of near $1mil. So far I haven't spent anything on my implementation at home :). Hopefully I can get this working to get some pre-exposure before start working on it. Hopefully the update fix as mentioned (about a month ago) does the trick. I appreciate all of the posts. Definately helpful...

Later!
Nate

Nate said...

Well a couple more issues. I can't get to the management page. I followed the instructions almost to the "T". The only difference was a 4xxx for extensions and 9xxx for voicemail. The following "services" (?) show as failed when starting:
smartd
sipregistrar
sipproxy

Any help would be great.

Thanks!
Nate

Ryan said...

Hi Nate,

Can you find us all jobs at your work? ;)

Sounds great. A good investment by your employer.

Ryan

Nate said...

It seems another reboot cleared up the issues. I did make one minor adjustment. I retyped a couple lines in the mappings xml. When running the verification command on that file it was yelling about something. Maybe a space in the wrong spot or something? Either way that was the only thing I changed.

My next hurdle is getting this Registration Error 405 when trying to connect X-lite.

... as far as work it does have it's trade offs. However we are looking at expanding our group in the next year. So if anyone is in SE Wisconsin watch monster.com for it. :)

Tom said...

Hello Ryan,

I also Ran in some trouble the following 2 solutions might come handy for other people.

Solved 1
When performing "sipx-validate-xml /etc/sipxpbx/external_mappingrules.xml
"
I got 3 problems on 5 / 6 and row 7. It's something like "InvalidDatatypeValueException" I replced the Variables with solid information so something like
@hostPattern@sipx.lithnet.local@/hostPttern@
@hostPattern@sipx@/hostPttern@
@hostPattern@192.168.0.50@/hostPttern@

Now the "sipx-validate-xml" worked fine.

Solved 2
You are allready mentioning tha DNS is important. I tried to run the sipx server with some adjusted Hots file instead of a proper DNS server. I changed the DNS ip to the IP of the Exchange server. I also added a A record sipx.lithnet.local to the DNS server.
It solved a 503 Error in X-Lite

So people DNS is importand, it solved the 503 error and it solved a problem that you don't hear anything when calling 222. Calling 300 works fine, calling 222 only silence, not an error, only silence..

I had to use the two mentioned methods.

Regards Tom, hope it helps Someone

Ryan said...

Hi Tom,

Thanks for your comment. You are correct, there is a problem with sipX 3.6's sipx-validate-xml that generates an InvalidDatatypeException when processing the variables you mentioned. This error is safe to ignore, but errors on lines other than the <hostPattern> statements should be corrected.

Thanks also for the info on DNS/hosts files. I think this confirms that DNS is definitely the way to go when configuring any SIP solution.

Cheers

Ryan

Anonymous said...

Ryan,
I have all working good but one thing. When using owa there is a link in the options for voicemail config and a link on it to call a phone to setup greetings. Using extension 300 on the SipX server works fine, but i can't get the call to go to asterisk extension. I have some sip debug and it looks like the sipx does not stay in the conversation to do the conversion TCP->UDP Do you know any trick i can do to help it happen?

Thanks
Ficeto

Ryan said...

Hi Ficeto,

Can you send me your SIP/RTP traces.

Regards,

Ryan