Free Whitepapers

Transcoder release Installation on a Distributed System

    1. Sangoma Media Transcode Package Installation
    2. Hardware & Ethernet Driver Installation & Configuration
    3. Sangoma Transcode Installation
    4. Sangoma Codec Installation for Asterisk
    5. Sangoma Codec Installation for FreeSWITCH
    6. Transcode Hardware Auto Configuration
    7. Sangoma Codec Module Auto Configuration
    8. Configuring Routing Information
    9. Asterisk Sangoma Transcoding Operation
    10. FreeSWITCH Sangoma Transcoding Operation
    11. FAQ

    When using the Sangoma transcoder for a distributed network, the transcoding hardware and SOAP server are installed on one machine, and all remote instances of Asterisk/FreeSWITCH installed throughout your network will act as SOAP clients to the transcoder.    The requirement includes the SOAP server (sngtc_server) to be installed ONLY on the machine that contains the hardware transcoder and the Sangoma codec module to be installed ONLY on the machine(s) that host Asterisk/FreeSWITCH .  When Asterisk/FreeSWITCH requires transcoding sessions, it will send HTTP requests to the machine with the transcoder, then the sngtc_server will create transcoding sessions with the local transcoding module.  It is important that the sngtc_server is listening on the correct network interface in order to receive these requests before being able to send them to the vocallo module for transcoding.  By default, the sngtc_server uses a private local IP/port configuration for local installation, however, this information must be changed in order for the sngtc server to reach the remote SOAP clients for a distributed system.

    Sangoma Media Transcode Packages

    * The following two steps are to be performed on the machine that will containing the transcoder hardware and all machines containing Asterisk/FreeSWITCH

    1. Download the Latest Sangoma Media Transcoding Release:  
      ---> sng-tc-linux-1.3.3.2.i686.tgz                   (2012-04-09)             ChangeLog
      ---> sng-tc-linux-1.3.3.2.x86_64.tgz             (2012-04-09)
      --->       sng-tc-windows-x86-1.2.3.tgz               (2010-10-13) 

      *A manual firmware upgrade is required to use the above 1.2.x releases for cards
      purchased before November 10th, 2010 
      --> Firmware upgrade Procedure 


    2. Untar the release in arbitrary directory on the system
      ---> tar xfz sng-tc-<ver>.tgz

      Release Conents:
    1. server/eth_drivers/  Broadcom and Micrel Ethernet drivers.  In case kernel does not have support for above mentioned Ethernet hardware. 
      server/libsngtc/  Sangoma transcoding (SNGTC API) library
      server/sngtc_cfg/ Configuration utility
      server/libsngtc_node Sangoma transcoding node library (SOAP API)
      server/sngtc_server Sangoma transcoding SOAP server
      client/codec Asterisk codec module (Works as a SOAP client)

          

    Hardware & Ethernet Driver Installation & Configuration

    1. Insert the D100 PCI/PCIe card into the system PCI slot and boot your Linux system
       
    2. Depending on your kernel:
      a. The Broadcom or Micrel kernel ethernet driver will automatically load and
            additional ethernet device will appear in: 
            --> cat /proc/net/dev    (proceed to step 5 in this case)
      OR

      b. The kernel does not support Broadcom or Micrel drivers.
           Drivers will have to be compiled and installed manually as shown in the following step

    3. Installing Broadcom/Micrel Driver Manually (case: step 2b)
      Run this step only if the kernel does not support the above Ethernet drivers.

      --> cd sng-tc-<ver>/server/eth_driver
      --> ./install.sh 
             The install script will auto detect Broadcom & Micrel support. 
             If drivers are not found it will try to build them for the currently running kernel.
         
             The build steps below will be automatically executed by the install.sh script.     

             For Broadcom                                    For Micrel
             --> Latest Driver tg3-3.116j
             --> cd tg3                                          --> cd   ks8842_pci
             --> make                                           --> make
             --> make install                                 --> make install
    • Note: the contents of the following chart will be covered by the install.sh script and is presented for FYI purposes only

    Broadcom driver (tg3) detection in available driver list
    ->  modprobe -l  | grep tg3 

    If Broadcom driver exists it should have loaded on boot up.
    -> lsmod | grep tg3

    If Broadcom driver is loaded then proceed to configure the ethX device

    Load Broadcom driver into the kernel
    -> modprobe tg3                (load tg3 driver)
    -> lsmod | grep tg3             (confirm tg3 driver is in loaded list)
    -> tail -f /var/log/messages  (confirm tg3 driver has loaded )
    -> cat /proc/net/dev           (confirm new eth device is available)

    Micrel driver (ks8842_pci) detection in available driver list
    ->  modprobe -l  | grep ks8842_pci

    If Micrel driver exists it should have loaded on boot up.
    -> lsmod | grep ks8842_pci

    If Micrel driver is loaded then proceed to configure the ethX device

    Load Micrel driver into the kernel
    -> modprobe ks8842_pci     (load ks8842_pci driver)
    -> lsmod | grep ks8842_pci (confirm ks8842_pci driver is in loaded list)
    -> tail -f /var/log/messages  (confirm ks8842_pci driver has loaded )
    -> cat /proc/net/dev           (confirm new eth device is available)

     

        4.  Configuring ethernet devices and assigning IP addresses
              * Note this step is distro-dependent

      RedHat/Fedora/CentOS

    --> run: system-config-network
    --> Select new eth device created on eth driver module load
    --> Specify a private IP address that is on different subnet than your local LAN.           
           eg: 10.1.1.1  netmask 255.255.255.0   
    --> Leave gateway ip empty 

    To apply network settings run:
    --> /etc/init.d/network restart

    If there are more than one D100 devices in the machine, each D100 eth device must have its own subnet IP.
    Eg: D100 card1 - IP 10.1.1.1
           D100 card2 - IP 10.1.2.1

    Sangoma Transcode Installation

    The following will perform a complete installation of the Sangoma transcoder, which includes the Sangoma transcoding library (SNGTC API), the Sangoma transcoding configuration utility (sngtc_cfg) and the Sangoma SOAP library & server (sngtc_server).

    * These steps are to be performed ONLY on the machine containing the Transcoding hardware
     
    1. Untar the release in arbitrary directory on the system
      ->       tar xfz sng-tc-<ver>-<arch>.tgz
    2. cd sng-tc-<arch>-<ver>/
    3. make
    4. make install

       4.  Proceed to the following step for Asterisk installation, otherwise skip to Sangoma codec installation for FreeSWITCH


      

    Sangoma Codec Installation for Asterisk

    Perform the following steps on ONLY the Asterisk machines that will be acting as SOAP clients to the remote Transcoder .  This step is required on all Asterisk machines on the network

    *In order to perform these steps, you must have Asterisk already installed along with its headers (ie: /usr/include/asterisk/)

    1. cd sng-tc-<arch>-<ver>
    2. make asterisk
    3. make install

    Proceed to Transcode Hardware Auto Configuration

    Sangoma Codec Installation for FreeSWITCH

    Perform the following steps on ONLY the FreeSWITCH machines that will be acting as SOAP clients to the remote Transcoder .  This step is required on all FreeSWITCH machines on the network

    The Sangoma FreeSWITCH codec is part of the FreeSWITCH git repository.  It can be easily attained by running the following command in linux CLI:

    --> git clone git://git.freeswitch.org/freeswitch.git

    Note*  You must have git installed

     In the FreeSWITCH source code edit:

    --> modules.conf and uncomment:

            --> # codecs/mod_sangoma_codec

    Then compile FreeSWITCH Sangoma codec module:

        1.  make mod_sangoma_codec    
        2.  make mod_sangoma_codec-install


    Transcode Hardware Auto Configuration

    This step will auto detect all configured D100 cards. The utility used to configure is called "sngtc_cfg".

    This utility will probe all the ethernet interfaces looking for transcoding modules. Be aware it will attempt to bring up all interfaces in the system in order to transmit some special ethernet frames
    to discover transcoding modules. It will then ask for configuration for each interface where transcoding modules were detected.

    1. On the machine containing the transcoder hardware, type:
      --> sngtc_cfg --server

      The above command will create transcoder configuration file located:      -->  /etc/sngtc/sngtc_server.conf.xml
       
    2. The above file must now be edited so that the sngtc_server will be able to listen on all ethernet interfaces in order to receive the transcoding requests from the remote SOAP clients for a distributed system.  Type:

      --> vi /etc/sngtc/sngtc_server.conf.xml 

      Add the following lines of code to the beginning of the file just inside of the "configuration" tag:
      <settings>

                    <param name="bindaddr" value="0.0.0.0" /> 
                    <param name="bindport" value="9000" />
            </settings>

    If you wish to have the sngtc_server listen on a specific network interfaces, then change the "bindaddr" value to the specific interface IP

    Sangoma Codec Module Auto Configuration

    This step will create Asterisk and/or FreeSWITCH codec module configuration files.  Perform the following step ONLY on the Asterisk/FreeSWITCH machine(s) that will be SOAP clients to the remote transcoder. 

    Perform only step 1 if your SOAP client is Asterisk, otherwise perform step 2 for FreeSWITCH

    1. Asterisk Sangoma Transcoding Configuration: 
      --> sngtc_cfg --asterisk 
      or
      --> sngtc_cfg --asterisk --astdir=/etc/asterisk

      The above commands will generate Asterisk codec configuration files in:               
      /etc/asterisk/sangoma_codec.conf

    2. FreeSWITCH Sangoma Transcoding Configuration: 
      --> sngtc_cfg  --freeswitch  
      or
      --> sngtc_cfg--freeswitch --fsdir=/usr/local/freeswitch/conf/autoload_configs

      The above command will generate FreeSWITCH codec configuration files in:
      /usr/local/freeswitch/conf/autoload_configs/sangoma_codec.conf.xml

    3. After the above configuration file has been created, it must be edited in order to specify:
      a.  the location of the SOAP server on the network from this particular SOAP client in order to send transcoding session requests 
      b.  the return location of the transcoded session(s) from the remote transcoder hardware 

      For Asterisk:
      --> vi /etc/asterisk/sangoma_codec.conf
      add the following lines:
      --> soapserver= <LAN IP of machine with transcoder>:<Port of machine with transcoder>
      --> rtpip= <LAN IP of Asterisk SOAP client> 

      For FreeSWITCH:
      --> vi /usr/local/freeswitch/conf/autoload_configs/sangoam_codec.conf.xml
      add the following lines:
      --> <param name="soapserver" value= <"LAN IP of machine with transcode>:<Port of machine with transcoder">
      --> <param name="rtpip" value=<"FreeSWITCH network interface">

      The PORT information for the soapserver specified above must match the information you selected in /etc/sngtc/sngtc_server.conf for 'bindport".  If you also decided to specify a unique "bindaddr" in the same file, then you must match that IP address with the value for "soapserver" above

    4. Start the SOAP server so that the SOAP server clients can interact with the transcoder hardware
      --> sngtc_server_ctrl start  

      If any changes are made to any of the above files, the SOAP server must be restarts:
      --> sngtc_server_ctrl restart 


     

    Configuring Routing Information

    Now that your distributed network is setup for transcoding, it is important to make sure that you have your routes properly defined so packets reach their destination without being denied by permissions. For the purpose of this topic,  Host A will represent the machine with the SOAP client (Asterisk/FreeSWITCH) and Host B will represent the machine containing only the transcoder hardware and SOAP server (sngtc_server).


    1. Verify that IP forwarding is enabled on Host B. The transcoded rtp stream leaving the transcoder's vocallo module must be able to route back to the Asterisk/FreeSWITCH SOAP client located remotely on the network.  Enabling this option will allow the rtp stream to be forwarded by the ethernet device located on the transcoder hardware (ex. 10.1.1.1), which will then be routed by the machine's routing table.  If this option is disabled, the packets will be dropped as soon as they reach the ethernet device on the transcoder which will result in no audio.

      To check if IP forwarding is enabled on your system, type the following command in the Linux CLI:

      -> cat /proc/sys/net/ipv4/ip_forward

      The output will either return a '0' or a '1', which indicates the option is disabled (0) or enabled (1) respectively

      If you need to enable IP forwarding, edit /etc/sysctl.conf:

      ->  vi /etc/sysctl.conf,     and add the following line:
      ->  net.ipv4.ip_forward = 1, or if this line is already present, then make sure the value =1

      run the following command to enable changes:
      -> sysctl -p /etc/sysctl.conf
      or
      -> service network restart on Redhat distributions
      ->/etc/init.d/procps.sh restart on Debiun/Ubuntu distributions

    2. When Host A requires a transcoding session from the remote transcoder hardware, it will require to know how to route to the transcoder's internal vocallo module (ex. 10.1.1.151).  Since the vocallo module IP is unknown to Host A, a route must be added in Host A's routing table.  To add a route to the routing table in Host A, type the following in the Linux CLI:

      -> route add -net 10.1.1.0 netmask 255.255.255.0 gw <LAN IP of Host B> dev <ethX> , where "ethX" represents the ethernet device of Host A's main LAN

      ---> Multiple routes can be added in Host A if you have multiple connections to the network and want more than one access point for transcoding requests.  Simply add a new route with the ethX of the next ethernet interface to configure
      ---> Perform Step 2 for all SOAP clients

      A route in Host B's routing table will NOT be required because when the returning transcoded RTP stream from the vocallo module cannot find its destination through Host B's routing table (i.e. rtpip=HostA) it will route to Host B's default gateway, which will know about Host A and send the stream back to Host A.

      *        If you are certain that your default gateway does not know about Host A, then you will require to add the route:
      -> route add -net <first 3 octets of Host A. 0> netmask 255.255.255.0 gw <gateway> dev <ethX> ,where "ethX" represents the ethernet device of Host B's main LAN

    Asterisk Sangoma Transcoding Operation

    Once the sangoma transcoding configuration file is created by sngtc_cfg configurator we can start Asterisk and load codec_sangoma.so module from the Asterisk CLI.

     Asterisk CLI> module load codec_sangoma.so

    An alternative for production systems is add the line load => codec_sangoma.so to Asterisk configuration modules.conf to get the codec module loaded at startup.

    At this point the module will read the sangoma_codec.conf configuration and load the configured codec translators. Asterisk will make use of the translators as necesary.

    WARNING: There is a bug in Asterisk that may lead to crashes when loading codecs if there are 2 different modules providing the same translation paths. See this bug report for more information:

    http://issues.asterisk.org/view.php?id=17092

    And also read the sample configuration comments in sng-tc-<version>/codec/asterisk/sangoma_codec.conf.sample to learn more about work-arounds in case you face the problem.

    Once the module is loaded Asterisk will use the translation resources when needed. You can see which translators were registered by the Sangoma module using:

    Asterisk CLI> sangoma show translators

    You can monitor the usage of the translation resources using Asterisk CLI commands:

    This command display all the transcoding sessions currently active along with some statistics per session like Tx/Rx packet counters and average Rx/Tx times in milliseconds.

    Asterisk CLI> sangoma show transcoding sessions

    This command display the lost RTP packets statistics for all sessions.

    Asterisk CLI> sangoma show rtp statistics

    FreeSWITCH Sangoma Transcoding Operation

    Once the sangoma transcoding configuration file is created by sngtc_cfg configuratior we can start FreeSWITCH and load mod_sangoma_codec.so module from the FS CLI.

     FS CLI> load mod_sangoma_codec

    An alternative for production systems is add the line <load module="mod_sangoma_codec"/> to conf/autoload_configs/modules.conf.xml to get the codec module loaded at FS startup.

    At this point the module will read the sangoma_codec.conf.xml configuration and load the configured codecs. FreeSWITCH will make use of the codecs as necessary.

    You can verify which codecs were registered by the module using the FS native command to list codecs:

    FS CLI> show codecs

    Several codecs will be listed, all codecs prefixed with "Sangoma" are registered by the module, for example: "Sangoma G729" or "Sangoma G.726 32k".

    You can use several commands to monitor the usage of the codecs:

    This command will show each vocallo configured settings.

    FS CLI> sangoma_codec settings

    This command will show all current RTP transcoding sessions created by FreeSWITCH along with some statistics about Rx/Tx and lost RTP packets and read average times that can be used for debugging purposes. The first column show the session unique identifier for the transcoding session, you can use that identifier to query more information about that particular session using "sangoma_codec stats".

    FS CLI> sangoma_codec sessions

    This command will show the FreeSWITCH RTP statistics in the transcoding sessions. Each transcoding session has a RTP connection associated. You can dump the RTP counters with this command:

    FS CLI> sangoma_codec stats <session number>