WELCOME [ Log In · Register ]        SITE [ Search · Page Index · Recent Changes ]    RSS

Sangoma Linux NetBorder SIP-PSTN Gateway

  1. Requirements
  2. Download Netborder
  3. Installing Netboder
  4. Configuration
  5. Operation
  6. Routing
  7. Troubleshooting
  8. Uninstall
  9. Advanced Configuration

Requirements

At this point CentOS is the only supported distribution, any RedHat-based distribution (Fedora, CentOs etc) has good chances of working without changes, as long as you install the required packages, however you will be in your own if you use other distribution than CentOS and things do not work. Netborder includes its own set of libraries but the C runtime across distributions (libc version) may vary and other distributions may need to install a different runtime.

The Linux Sangoma Wanpipe drivers are included with Netborder and only the included version of the drivers is supported, you must not try to install a different Wanpipe version. The following CentOS packages are required:

  • ncurses
  • ncurses-devel
  • libtermcap
  • libtermcap-devel
  • bison
  • libtool
  • flex
  • gcc
  • gcc-c++
  • automake
  • autoconf
  • imake
  • kernel
  • kernel-devel

The kernel and kernel-devel packages may have different names if you are using a modified kernel like kernel-pae (physical address extension kernel) or kernel-xen (XEN virtualization kernel). In any case the matching kernel and headers must be installed in order to compile the Wanpipe drivers. You can verify that the proper kernel and headers are installed by executing:

# ls -la /lib/modules/`uname -r`/build

The build file should be a symbolic link to a valid directory having the kernel headers.

The installer will attempt to verify that your packages are installed, but if you installed manually any of those packages and is not listed in the RPM database the installer won't be able to verify it. Please also make sure your kernel and kernel-devel packages version match.

Sangoma NetBorder Express is also referred to as NBE. In this guide we will refer as netborder.tar.gz to the distribution file, the exact file name will vary according to the downloaded version.

During the guide is assumed that NBE is installed in the default location /usr/local/netborder, if you decide to install in a different location it's up to you to determine the right file paths in this guide.

Download Netborder

Versioning WARNING: NBE for Linux has been already released and no-one should continue to use beta versions (any package with version 2.0.99x is beta). To download NBE for Linux go to Sangoma web page: 

http://www.sangoma.com/products/software_building_blocks/netborder_suite/netborder_express.html

Once you have your tar.gz file, untar the downloaded file.

#> tar -xzf netborder.tar.gz

#> cd netborder

Installing Netborder

Run the installation script Setup.sh with the "install" command.

# ./Setup.sh install

This step will install NBE files along with Sangoma Wanpipe drivers. Default install location for NBE is /usr/local/netborder, this can be changed with the --prefix option, but doing so requires to manually update the sample netborder.conf file at /etc/sysconfig/netborder.conf

At this point you need a license to continue. Please request your license here: sales@sangoma.com

Once you get your license file you must place the license and its signature (the .txt and .txt.sig files) in /usr/local/netborder/config/netborder-express-gateway-license.txt and /usr/local/netborder/config/netborder-express-gateway-license.txt.sig

Configuration

The first thing to configure is the basic network settings. During the first execution of NBE, the init script will try to set the right IP address automatically in the configuration files, but if you have more than one network card or you want to verify the right IP address is in place you need to follow this instructions.

Open /usr/local/netborder/config/gw.properties and set the following properties to your IP address:

netborder.net.primaryIPAddress=x.x.x.x

netborder.media.rtp.IPAddress=x.x.x.x

netborder.sip.userAgent.IPAddress=x.x.x.x

Now it's time to start the NBE configuration web server.

Start netborder-webconfig service.

#> service netborder-webconfig start

This command will start the init script at /etc/init.d/netborder-webconfig and will launch a web server to configure and control NBE. The default port where it listens for connections is 7783.

You can now open your favorite web browser and go to http://localhost:7783/

You should see a screen like this:

gw1_little.png

If you are not able to see the configuration web page then probably the web server did not start. See the Troubleshooting section to determine the problem.

In the web panel you have 4 tabs: "Status and control", "Configuration", "Quick Setup" and "Help". In order to generate the XML configuration needed by the SIP and PSTN protocols we need to click in "Quick Setup" and follow the Wizard. The Wizard can be summarized as:

1. Add boards in your system.

Here you will be asked to add the Sangoma boards that are installed in your system.

2. PSTN configuration.

Provide interface type, framing, encoding and ISDN Switch variant.

3. SIP configuration.

Configure contact URL (The URL which will handle the incoming PSTN calls), the SIP port to listen for calls and whether you want to use UDP or TCP.

At the end the Wizard will ask you whether you want to restart the gateway. You can run the Wizard anytime you want to configure NBE express Sangoma boards (for example if you add a new Sangoma board). If an old pstn-config.xml file is found it will be backed up in pstn-config.<time>.xml. If you want to see the generated configuration files or need to tweak them by hand you can do so going to /usr/local/netborder/config/pstn-config.xml

Operation

There is 2 ways to start NBE. You can either start it from the web panel by pressing the "Start Gateway" button. Be aware that starting the gateway may take several seconds depending on the number and type of Sangoma boards installed on the server.

starting_little.png

You can also start NBE using the "service" command available in RedHat-based distributions (Fedora, CentOS etc) with:

#> service netborder-gateway start

In the web panel you can verify that NBE has started by going to the tab "Status and Control", when the gateway is up you will see a screen like this:

yellow-alarm_little2.png

In this case the Gateway is up but the 2 configured spans have yellow alarm. When the T1 or E1 is up and running the status will change to something like this:

mid-load_small.png

If the NBE service does not start, please check the Troubleshooting section to determine the problem.

At this point the gateway is ready to forward SIP->PSTN calls or PSTN->SIP calls.

Routing

NBE comes with default routing rules to allow moving all traffic from the PSTN to a specific SIP destination and viceversa. However once in a while you may want to be a bit more specific about where to route incoming or outgoing calls. The routing rules decide where and how to send calls in/out from the gateway. You can edit the routing rules file from your web panel by clicking in "Configuration" -> "Routing Rules". 

Here we will explain just one common scenario: "I want to define outgoing channel groups and decide which group to use based on the dialed number". In order to do this we need to follow these 3 steps:

1. Create the channel groups. Go to "Configurations" -> "PSTN Config" -> "Call Control" and click in "Channel Groups". The current channel groups will be listed. By default just 1 channel group exists called "default". We will create 2 additional channel groups called g1 and g2. You can click in "Add ChannelGroup" at the bottom of the screen and follow the popup instructions.

2. Add new ISDN configuration profile. Once the channel groups are created now we must decide which channels belong to which group. In this case we will assume we have an A108 Sangoma board (8 T1/E1 ports) and we want to use all channels from span 1 to span 4 for g1 and all channels from span 5 to 8 for g2. Click in "ISDN Configurations" to display the defined configurations (be sure to click on the left arrow of "ISDN Configuration"). Then select the ISDN configuration that was created for your board. At the bottom you will se a button saying "Assigned BChannel(s)". Click on it and a popup will appear showing the spans used by that ISDN configuration. You can click on the "Group ID" field of each span to decide whether that span will use g1 or g2.

3. Finally we must edit the routing rules to match the desired pattern and set the group that will be used for the outgoing PSTN connection. Click on "Configuration" -> "Routing Rules" and create 2 rules like this:


 <!-- PSTN OUT Group 1 -->
  <rule name="pstn_out_g1" outbound_interface="pstn" qvalue="0.001">
    <condition param="transfer" expr="false"/>
    <condition param="sip.in.requestUri.canonical"
      expr="sip:80([0-9]+)@GW_HOST_IP:GW_SIP_PORT"/>
    <out_leg name="" media_type="sendrecv">
      <param name="pstn.out.phoneNumber" expr="%0"/>
      <param name="pstn.out.channelGroup" expr="g1"/>
      <param name="pstn.out.cpa.enable" expr="false"/>
    </out_leg>
  </rule>

  <!-- PSTN OUT Group 2 -->
  <rule name="pstn_out_g2" outbound_interface="pstn" qvalue="0.001">
    <condition param="transfer" expr="false"/>
    <condition param="sip.in.requestUri.canonical"
      expr="sip:90([0-9]+)@GW_HOST_IP:GW_SIP_PORT"/>
    <out_leg name="" media_type="sendrecv">
      <param name="pstn.out.phoneNumber" expr="%0"/>
      <param name="pstn.out.channelGroup" expr="g2"/>
      <param name="pstn.out.cpa.enable" expr="false"/>
    </out_leg>
  </rule>

 

The most important parameters are those in bold. The sip:80([0-9]+) is the regular expression matching the number dialed on the SIP side. The pstn.out.channelGroup is the parameter set to specify which group should be used for such outgoing call. In this case prefix 80 is used for calls to g1 and prefix 90 for g2. Note how the prefix is NOT enclosed in brackets, otherwise the dialed number through the trunk would include the prefix as well (most likely something you don't want).

The routing rules changes do not require to restart the gateway to take effect, however the channel group changes and ISDN profile need the gateway to be restarted.

Troubleshooting

NBE log files are located at /usr/local/netborder/logs/, however, by default it will log only fatal errors and warnings, which are often not enough to determine the root cause of a service not starting.

There are 2 different services that you may want to troubleshoot. The NBE service which is responsible for routing the calls and the NBE web panel service which can be used to monitor and configure the NBE service.

== NBE Web Panel Service Logs ==

The default log file for the web server is /usr/local/netborder/logs/OAMWebServerRollingFile.out, this file will only save warning, error and fatal messages which is recommended for production environments. The file will be rotated according to the properties found in /usr/local/netborder/config/oamWebServer-prod-logger.properties

There is a debug mode that can be enabled by changing the logger properties file in /usr/local/netborder/config/oamWebServer.properties, in that file you will find this property:

netborder.run.mode=production

Change that property to have the value "development", just like this:

netborder.run.mode=development

This change causes the file /usr/local/netborder/config/oamWebServer-dev-logger.properties to be used to configure the logger, therefore from now even debug messages will be logged. The location of the debug output file is /usr/local/netborder/logs/OAMWebServerDebug.out, this file IS NOT rotated, is overwritten each time the web server service is started.

In a healthy system the following message should be shown in the debug file after starting the web server service:

netborder.turboGears.cherrypy.msg : HTTP: Serving HTTP on http://0.0.0.0:7783/

If you don't see that message it means the web server was not started, try looking for clues in the debug file.

== NBE Service Logs ==

The default log file for the web server is /usr/local/netborder/logs/GatewayRollingFile.out, this file will only save warning, error and fatal messages which is recommended for production environments. The file will be rotated according to the properties found in /usr/local/netborder/config/prod-logger.properties

There is a debug mode than can be enabled by changing the logger properties file in /usr/local/netborder/config/gw.properties, in that file you will find this property:

netborder.run.mode=production

Change that property to have the value "development", just like this:

netborder.run.mode=development

This change causes the file /usr/local/netborder/config/dev-logger.properties to be used to configure the logger, therefore from now even debug messages will be logged. The location for the NBE debug output file is /usr/local/netborder/logs/GatewayDebug.out, this file is NOT rotated, is overwritten each time the NBE service is started.

== Known Issues ==

These are some known issues that are in the process of being fixed and/or improved.

Echo Canceller Settings. The automatic configuration wizard will generate pstn-config.xml file assuming echo cancellation devices are available. NBE will fail to start if is configured to use echo cancellation but echo cancellation hardware is not available. The solution is to disable the echo cancellation after running the configuration wizard by going to: Configuration -> PSTN Config -> Physical configurations -> Echo cancellation Configuration and setting Mode: DISABLED.

Starting the gateway. When starting NBE from the web panel, the web page may show an error saying: "Your last operation failed, please contact support if the problem persists". This is sometimes not a problem itself, but is just that NBE is taking a long time to start, not an uncommon scenario when you have several Sangoma devices. You can refer to the gateway logs to see if the gateway really failed to start or is just in the process of starting. Tail -f /var/log/messages should also give you some information about whether or not the Sangoma devices are starting up and delaying the gateway startup process. If NBEis still trying to start you can just ignore the web error message, once NBE is started the web interface will realize of this and properly update the view.

Uninstall

In order to uninstall NBE you need to go to the directory where the .tar.gz was decompressed and execute the ./Setup.sh script (the same that was used to install netborder) with the remove option. You will be prompted for confirmation, just type "yes".

# ./Setup.sh remove

This step will uninstall NBE, except for configuration files and logs. If you wish to remove everything from your system you need to execute.

# ./Setup.sh remove --removeall

Be careful with that option though, you may lose configurations or logs you really wanted to keep. The switch "--nowanpipe" is also available to keep the wanpipe drivers.

Advanced Configuration

In this section we will describe how to create advanced configurations. The default configurations created by the installation wizard assume all analog or digital ports will use the same analog or digital configuration. However, there is times when 2 given analog or digital ports, need a different configuration. The next steps describe how to create a different configuration and then apply that configuration to the ports that you want.

We start assuming we have an A200 with 4 interfaces.

nbe_a200_interfaces-01.jpg

 

By default, the wizard creates a single analog configuration for the 4 interfaces in the A200.

nbe_a200_default_config-01.jpg

Clicking in the "Assigned interfaces" button for the analog configuration we can see that all the interfaces of the A200 were assigned to this configuration.

nbe_a200_default_config_interfaces.jpg

However, we can manually create a new analog configuration and assign interfaces to it. 

1. First, click "Analog configurations" -> "Add analog config"

nbe_a200_add_config.jpg

2. A popup window will be launched. Select "FXO" (the only option at this time) and click "Add". Note how a new configuration is listed in the "Analog configurations" window.

nbe_a200_new_config_assigned_interfaces.jpg

3. Click the "Assigned interface(s)" button. Then from the popup window click "Add Analog Interface" button. Each time you click the button a new row is added to the interfaces table, each row represents a new analog interface. Each row has a "Board ID", "Interface ID" and "Channel Group ID" column. The board id and the interface id are the columns that really identify the underlying physical sangoma interface. In this case, we have an A200 with 4 interfaces, numbered 1 to 4. You can always consult the interface and board id in the "Boards" section of the "PSTN Config" interface.

In this example we will split the A200 in 2 configurations. The original created configuration will keep interfaces 1 and 2 and the new configuration we created will control interfaces 3 and 4. Therefore in this case you should click "Add Analog Interface" twice to create 2 interface rows. Then edit the board id and interface id to match the board and interfaces you want to assign. In this case we just need to edit the interface id given that we just have 1 board ( 1 A200 ).

Don't forget to click "Save" in the popup window.

nbe_a200_new_config_assign_interfaces_window.jpg

Be aware that the web interface does not verify conflicts or availability of hardware. That means that you can assign an interface to 2 configurations or assign an interface that does not exist. Is up to you to be sure there is no conflicts (don't try to assign the same interface to 2 configurations nor assign an interface number that does not exist). 

4. Now to avoid conflict of interfaces, we must remove the interfaces 3 and 4 from the original analog configuration. Click in the original configuration and then "Assigned Interface(s)". Select interface 3 and click "Delete" and do the same for interface 4.

You are done, now interfaces 1 and 2 have one analog configuration and interfaces 3 and 4 have a new configuration. You can proceed to edit the analog parameters as required.