Skip to end of metadata
Go to start of metadata

This page describes a typical deployment workflow where a sample "master" Sonus SBC 1000/2000 configuration is to be applied or copied onto hundreds or thousands of Sonus SBC 1000/2000 nodes. This can be very desirable when system administrators are trying to deploy numerous Sonus SBC 1000/2000 systems in a network sharing the exact same configuration for all resources other than the system specific information.

Note: This is only applicable for Sonus SBC 1000/2000 nodes sharing the same hardware configuration and release version.

The following steps outline the deployment scenario:

  1. Bootstrap the node. This step is the initial set up of the node using the WebUI. This step will create the admin user that can be used for performing the REST APIs.
    1. If any additional routes need to be setup for performing REST requests, they can be configured after the initial setup through the WebUI.
    2. If a specific user needs to be created for running the REST requests, it can be added after the initial setup through the WebUI.
  2. Login with the REST user from the REST client.
  3. Import the master configuration file using the REST API. 
    If the request is successful, the node will reboot.
  4. Login from the REST client again.
    This is necessary the previous session was destroyed when the node rebooted as part of Step 3.
  5. Perform REST API requests to do any other system specific configuration on any resource.

Sample Code to Perform Deployment Workflow

Prerequisite - Setting up the HTTP Options

Sonus SBC 1000/2000 Web Service (REST) runs on a secure channel i.e. HTTPS, which requires Web Services clients to establish secure communication channel with the service.

If you're not using PHP+libcurl, please refer to documentation of the library you are using to determine the HTTP configuration necessary to properly import and trust the server certificate for secure HTTP

Setup cURL Options
// initialize curl
$curlHandle = curl_init();

// uncomment for debug porposes
//curl_setopt($curlHandle, CURLOPT_VERBOSE, true)

// set the appropriate timeout
curl_setopt($curlHandle, CURLOPT_TIMEOUT, 10);

curl_setopt($curlHandle, CURLOPT_HEADER, false);
// Set so curl_exec returns the result instead of outputting it.
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);

// This example blindly accepts any server certificate, without doing any
// verification as to which CA signed it, and whether or not that CA is trusted.

// For the sake of simplicity, configure cURL to accept any server(peer) certificate
curl_setopt($curlHandle, CURLOPT_SSL_VERIFYPEER, false);

// Following captures the details on how libcurl options can be configured to use secure HTTP.

//curl_setopt($curlHandle , CURLOPT_SSL_VERIFYPEER, true);

// 2, means, check that the common name exists and that it matches the host name of the server
//curl_setopt($curlHandle , CURLOPT_SSL_VERIFYHOST, 2);

// previously downloaded server cert
//$certLocation = getcwd() . "/CAcerts/sbc_rest.crt";
//curl_setopt($curlHandle , CURLOPT_CAINFO, $certLocation);

How to Acquire a Sonus SBC 1000/2000 Session Token

Upon successful authentication via /rest/login, HTTP response HEADER carries the session token in a cookie. REST clients need to lookup this cookie in the response header and cache it to use it for subsequent REST calls by setting the cookie back in the HTTP request header.

The REST client cookie session expires after 10 minutes of idle session

POST Request to /rest/login Resource and Extract Session Token
// define an array where we would cache the Session Token Cookie with value
$cookieArr = array();

// Sonus SBC 1000/2000 REST login resource URL
$loginResource = "https://sbc_host_or_ipaddress/rest/login";

// set the login resource url in curl
curl_setopt($curlHandle, CURLOPT_URL, $loginResource );

// setup a callback handler for reading and processing the response header fields
// that would come in response to REST login resource POST call
curl_setopt($curlHandle, CURLOPT_HEADERFUNCTION, array($this, 'responseHeaderCallback'));

// tell cURL that we are doing a HTTP POST
curl_setopt($curlHandle, CURLOPT_POST, true);

// set the login resource POST params. The user must be of the REST access level and created from the WebUI prior to using the API.
$loginPropsArr = array('Username'=>'admin', 'Password'=>'admin');
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, http_build_query($loginPropsArr, '', '&'));

// exec the HTTP/REST request
$response = curl_exec($curlHandle);

// HTTP response header callback function which processes the header fields
function responseHeaderCallback($curlHandle, $header) {
    if(!strncmp($header, "Set-Cookie:", 11)) {
        $cookiestr = trim(substr($header, 11, -1));
        $cookie = explode(';', $cookiestr);
        $cookie = explode('=', $cookie[0]);
        $cookiename = trim(array_shift($cookie));
        $cookieArr[$cookiename] = trim(implode('=', $cookie));
    }
    return strlen($header);
}

How to Use the Session Token for Import Configuration Request

POST on System Resource (/rest/system?action=importconfig) Using the Session Token
// init cURL handle
$curlHandle = curl_init();

$cookieHeader = '';
// previously extracted cookies in $cookieArr (above), is used to add the
// session token in HTTP request header for subsequent REST call
foreach ($cookieArr as $key=>$value) {
    $cookieHeader .= "$key=$value; ";
}
if (!empty($cookieHeader)) {
    curl_setopt($curlHandle, CURLOPT_COOKIE, $cookieHeader);
}

// set other relevant HTTP option as shows in above section _Setting up the HTTP Options_
$headerArr = array('Accept: ' . $this->acceptType, 'Expect: 100-continue');
$requestBody = array('Filename'=>'@'.$fileName);
curl_setopt($this->curlHandle, CURLOPT_POST, true);
curl_setopt($this->curlHandle, CURLOPT_HTTPHEADER, $headerArr);
curl_setopt($this->curlHandle, CURLOPT_POSTFIELDS, $requestBody);

// Sonus SBC 1000/2000 REST system resource URL
$systemResource = "https://ux_host_or_ipaddress/rest/system?action=importconfig";

// set the system resource url in curl
curl_setopt($curlHandle, CURLOPT_URL, $systemResource );

// exec the HTTP/REST request
$response = curl_exec($curlHandle);

How to Close a Sonus SBC 1000/2000 Session

It is recommended that an explicit POST is done on logout resource to cleanup session specific resources the Sonus SBC 1000/2000 node.

POST on logout Resource (/rest/logout)
// init cURL handle
$curlHandle = curl_init();

$cookieHeader = '';
// previously extracted cookies in $cookieArr (above), is used to add the
// session token in HTTP request header for this REST call
foreach ($cookieArr as $key=>$value) {
    $cookieHeader .= "$key=$value; ";
}
if (!empty($cookieHeader)) {
    curl_setopt($curlHandle, CURLOPT_COOKIE, $cookieHeader);
}

// tell cURL that we are doing a HTTP POST
curl_setopt($curlHandle, CURLOPT_POST, true);

// set other relevant HTTP option as shows in above section _Setting up the HTTP Options_

// Sonus SBC 1000/2000 REST logout resource URL
$logoutResource = "https://sbc_host_or_ipaddress/rest/logout";

// set the system resource url in curl
curl_setopt($curlHandle, CURLOPT_URL, $logoutResource);
// logout resource does not require any POST parameter.

// exec the HTTP/REST request
$response = curl_exec($curlHandle);

// any subsequent REST call should result in HTTP Error 401 Unauthorized status