Friday, July 27, 2007

Understanding sipX dial plan configuration files

When troubleshooting problems with sipX configuration, it is important to understand how the configuration files are generated.

There are 3 main files that make up the sipX dial plan configuration. There are all located in the /etc/sipxpbx folder.

mappingrules.xml

Mapping rules are used to route calls based on host, usernames, and permissions. In the guide to setting up Exchange UM, we also use mapping rules to transform the SIP URI to add the transport=tcp argument required to make a successful connection to an Exchange UM Server.

authrules.xml

Authrules allow restriction of dial patterns and host by various permissions. For example, you can modify the authrules file so that extensions 300-320 require special permission to call external hosts.

fallbackrules.xml

Fallback mapping rules are processed after mappingrules.xml, and are usually used to provide mapping to external systems (for example, another SIP domain, or a SIP server used to external calls)

These files are all generated automatically by sipX. Don't bother trying to change them, because your changes will be wiped next time the sipX service starts. Each of these xml files has a corresponding .xml.in file. When you activate your dial plan in the sipXconfig web interface, it writes the .xml.in file, and restarts the required components. The .xml.in file is then taken to generate the .xml file. So don't bother trying to change the .xml.in file either!

So how do we customize the dial plan? If you followed my guide to connecting sipX to Exchange UM, you would remember making (or downloading from me) two files - external_mappingrules.xml, and external_authrules.xml. However, in order for sipX to actually process these files, we need to add a few entries into /etc/sipxpbx/sipxconfig.properties.in.

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

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

fallbackRules.externalRulesFileName=/etc/sipxpbx/external_fallbackrules.xml

This tells sipX to integrate our external files into the dial plan when generated. So when configured correctly, our main config file (ie authrules.xml) is generated by combining our .xml.in file, with our external rules file

authrules.xml.in + external_authrules.xml => authrules.xml

If there is problem with the XML code in our external rules files, sipx will ignore them and not process them. You can tell if your files are being processed correctly by viewing the main xml file, and making sure that the external rules have been incorporated into in. If the external rules are missing, go back and check the external rules file, and make sure all tags are spelt correctly, and are have matching closing tags. You can use the following command to verify your XML files:

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

No comments :