Sun Open Telecommunications Platform 2.0 Developer's Guide

Chapter 6 Installing Sun OTP As Part of Existing Solution Deployment

This chapter describes how to invoke the deployment plans from existing installation environments.

The following topics are discussed:

Calling N1 SPS Plans From Shell Scripts

You can invoke the N1 SPS plans through the Command-Line Interface (CLI) by using the cr_cli binary. On a host that has Sun OTP 2.0, cr_cli is located in the /var/js/spsotp/N1_Service_Provisioning_System_5.2/cli/bin/cr_cli directory. For detailed description of the N1 SPS CLI, see Sun N1 Service Provisioning System 5.2 Command-Line Interface Reference Manual.

A typical workflow of invoking the N1 SPS plan from a script consists of three steps. The script performs the following tasks:

Creates a variable setting for the components that are installed as part of the plan. Alternatively, you can also use the default values of variables for a component.
Invokes the pe.p.run command through the N1 SPS CLI, which runs the specified plan with either the default values for variables or using specified variable settings.

Note –
The choice between the default values and variable settings is done for each component that is installed as part of the plan.
Waits until the running plan is completed and checks for errors.

Examples

An example for creating the variable settings for component foo is as follows:

/var/js/spsotp/N1_Service_Provisioning_System_5.2/cli/bin/cr_cli -cmd cdb.vs.add -u otpadmin -p adminadmin -comp NM:/path/to/component/foo -name foo-varset1 -vars "var1=value1;var2=value2"

The above example creates a variable setting for the component foo with the name foo-varset1. You can use the foo-varset1 variable in the vs parameter of the pe.p.run command for plans that execute an install block on component foo.

An example for running the InstallSecurity plan from Sun OTP 2.0 plug-in is as follows:

/var/js/spsotp/N1_Service_Provisioning_System_5.2/cli/bin/cr_cli -cmd pe.p.run -u otpadmin -p adminadmin -PID NM:/com/sun/OTP/security/plans/InstallSecurity -tar "H:NM:otp-eng-x11;H:NM:otp-eng-x11;H:NM:otp-eng-x11" -comp "+;+;+,+,+,+,+,+,+,+" -vs "+;+;+,+,+,+,+,+,+,+" -pto 9000 -nto 9000

In the above example, the InstallSecurity plan is run on a host named host otp-eng-x11. The user name is otpadmin and password is adminadmin. The default values for component variables are used and the time out is set to 9000 seconds.

Note the syntax of the vs parameter specifying the variable settings to use. The InstallSecurity plan consists of three sub plans. Each sub plan takes a part of the vs parameter value and delimits it by semicolons, that is, the first sub plan takes +, the second takes + and the third takes +,+,+,+,+,+,+,+. The third sub plan calls eight install blocks on various components. For each of these blocks, the default variable values are being used, which is specified by the 8 (+) plus signs and (,) comma as a delimiter. Similar rules apply to the comp parameter. The tar parameter specifying the target host consists of three parts that specify the target for each of the three sub plans.

For detailed information about the pe.p.run command, see Sun N1 Service Provisioning System 5.2 Command-Line Interface Reference Manual.

If you use the correct syntax, the command will complete successfully and return a ID. You can use this ID to check the plan status by running the pe.p.lo command. Error checking needs to parse the pe.p.lo command output.

The following example waits for running task ID 010018158098-1200908797135-01929-1300304153.

/var/js/spsotp/N1_Service_Provisioning_System_5.2/cli/bin/cr_cli -cmd pe.p.lo -u otpadmin -p adminadmin -ID 010018158098-1200908797135-01929-1300304153

The output of this example lists the sub-tasks that run in the background before completing this task.

Calling N1 SPS Plans From C/C++

Since there is no N1 SPS C/C++ interface available, you can invoke the plans using N1 SPS CLI. Two N1 SPS CLI invocations are required.

The code runs the plan first. The N1 SPS CLI returns the ID of the newly created running task on a standard output.
To wait for task completion and check on the task progress, the code runs the N1 SPS CLI command with the -cmd pe.p.lo parameter and the ID of the task from the previous step.

For detailed information about N1 SPS CLI, see Sun N1 Service Provisioning System 5.2 Command-Line Interface Reference Manual.

The following sample code illustrates how to run a plan from the C++ code.

/*
 * Example of running an N1SPS plan from C++ code.
 *
 * To simplify this example, not all possible errors have been handled
 * properly.
 */

///////////////////////////////////////////////////////////////////////////////

#include<iostream>
#include<sstream>
#include<cstdlib>

///////////////////////////////////////////////////////////////////////////////

//path to N1SPS CLI
#define N1SPS_CLI "/var/js/spsotp/N1_Service_Provisioning_System_5.2/cli/bin/cr_cli"

//plan to run
#define PLAN "/com/sun/OTP/security/plans/InstallSecurity"

//variable setting version string - see N1SPS CLI doc for more info
#define PLAN_COMP_DEFAULT_VS "+;+;+,+,+,+,+,+,+,+"

//component version string - N1SPS CLI doc for more info
#define DEFAULT_COMP DEFAULT_VS

//timeout in seconds - see N1SPS CLI doc (pto and nto parameters) for details
#define TIMEOUT_SEC 600

#define BUFF_SIZE 100

///////////////////////////////////////////////////////////////////////////////

using namespace std;

/**
 * prints usage message
 */
void usage() {
	cerr << "Usage:" << endl
		 << "listTasks <login> <password> <target>" << endl;
}

///////////////////////////////////////////////////////////////////////////////

/**
 * main function
 * expected argv content: login, password, target
 */
int main(int argc, char **argv) {

	if( argc != 4 ) {
		//incorrect number of parameters, so print usage information
		usage();
	} else {
		cout << "Running plan " << PLAN << ":" << endl << endl;

		//prepare string for invocation of N1SPS CLI to run a plan
		stringstream s;
		s << N1SPS_CLI << " -cmd pe.p.run -u " << argv[1] << " -p " << argv[2]
		  << " -tar H:NM:" << argv[3] << " -PID NM:" << PLAN
		  << " -comp " << DEFAULT_COMP << " -vs " << DEFAULT_VS
		  << " -pto " << TIMEOUT_SEC << " -nto " << TIMEOUT_SEC;

		FILE *f = NULL;
		if( (f = popen(s.str().c_str(), "r")) == NULL ) {
			//popen failed (fork() or pipe() failed), so print error message
			cerr << "Error running plan " << PLAN << ": popen() failed" << endl;
		} else {
			//read N1SPS CLI output (i.e. Task ID of running plan)
			char buff[BUFF_SIZE];
			fgets(buff, BUFF_SIZE, f);

			//wait for N1SPS CLI to finish
			if( pclose(f) != 0 ) {
				cerr << "Error running plan " << PLAN << ": N1SPS CLI failed" << endl;
				return -1;
			}

			cout << "Plan " << PLAN << "execution started." << endl
				 << "Task ID:" << buff << endl;

			/*
			 * prepare a new string for N1SPS CLI invocation to check on progress
			 * of the running task
			 */
			s.str("");
			s << N1SPS_CLI << " -cmd pe.p.lo -u " << argv[1] << " -p " << argv[2]
			  << " -ID " << buff;

			cout << "Checking progress of task ID " << buff << endl; 

			/*
			 * wait for the running task to finish
			 *
			 * return the same return code N1SPS CLI returns
			 */
			return system(s.str().c_str());
		}
	}
	return -1;
}

To get a code in plain C, replace all stream related C++ specific code to equivalent code in C.

Calling N1 SPS Plans From Java

You can invoke the N1 SPS plans through the Java API by using the sps-api.jar library. This library is located in the /var/js/spsotp/N1_Service_Provisioning_System_5.2/cli/lib/ directory. For more information about the API documentation, see Sun N1 Service Provisioning System JavaDoc.

A sample code indicating the running of the InstallSecurity plan from Sun OTP 2.0 plug-in and waiting for running plan of given ID is as follows:

Note –

This example does not handle all plan execution scenarios. Consider a case where there are 20 tasks that should be completed after the task that you specify completes. Before you check the status of task, the array that the pe.p.la command generates does not contain any information regarding the task. However, in case the array does not contain any information corresponding to your task, you can rerun the pe.p.la command specifying a higher result array size or by specifying a plan name for the tasks to match.

For more information about the pe.p.la and pe.p.lo commands, see Sun N1 Service Provisioning System 5.2 Command-Line Interface Reference Manual.

package spsapitest;

import com.sun.n1.sps.client.*;
import com.sun.n1.sps.model.executor.RunningPlanBean;
import com.sun.n1.sps.model.executor.TaskID;
import com.sun.n1.sps.model.util.ClientException;
import java.io.File;
import java.util.HashMap;
import java.util.Map;
import java.util.logging.Level;
import java.util.logging.Logger;

public class SPSTest {

    public static void main(String[] args) {
        try {
            CommandManagerBuilder cmb = new com.sun.n1.sps.client.CommandManagerBuilder();            
            cmb.setCLIInstallationDir(new File("/var/js/spsotp/N1_Service_Provisioning_System_5.2/cli"));
            CommandManager cm = cmb.build();
            
            //running the plan
            Map<String, String> arguments = new HashMap<String, String>();
            arguments.put("u", "otpadmin");     //user
            arguments.put("p", "adminadmin");   //password         
            arguments.put("PID", "NM:/com/sun/OTP/security/plans/InstallSecurity"); 		//plan name
            arguments.put("tar", "H:NM:otp-eng-x11;H:NM:otp-eng-x11;H:NM:otp-eng-x11");	//target
            arguments.put("vs", "+;+;+,+,+,+,+,+,+,+");   	//variable settings
            arguments.put("comp", "+;+;+,+,+,+,+,+,+,+"); 	//components versions
            arguments.put("pto", "9000");       //plan timeout
            arguments.put("nto", "9000");       //native call timeout
            TaskID taskID = (TaskID)cm.execute("pe.p.run", arguments);  //see pe.p.run in N1SPS CLI doc
            
            //waiting for plan to complete
            arguments.clear();
            arguments.put("u", "otpadmin");
            arguments.put("p", "adminadmin"); 
            arguments.put("ID", taskID.toString());                                     
            cm.execute("pe.p.lo", arguments);
                                    
            //checking plan status
            arguments.clear();
            arguments.put("u", "otpadmin");
            arguments.put("p", "adminadmin");   
            arguments.put("max", "20");         //maximum numbers of tasks to get info
            RunningPlanBean[] rpba = (RunningPlanBean[]) cm.execute("pe.p.la", arguments);
            for (RunningPlanBean rpb : rpba) {                
                if (taskID.equals(rpb.getTaskID())) {
                    System.out.println("Task ID: "+rpb.getTaskID().toString()+"\n"+
                            "Plan name: "+rpb.getName()+"\n"+
                            "Status: "+rpb.getTaskStatus().toString()+"\n"+
                            "Start date: "+rpb.getStartDate().toString()+"\n"+
                            "Complete date: "+rpb.getCompleteDate());
                }                
            }                        
        } catch (ConfigurationException ex) {
            Logger.getLogger(SPSTest.class.getName()).log(Level.SEVERE, null, ex);
        } catch (ClientException ex) {
            Logger.getLogger(SPSTest.class.getName()).log(Level.SEVERE, null, ex);

        }
    }    
}

Using N1 SPS From JumpStart

To invoke N1 SPS through JumpStart, perform the following steps.

Place the flash archive binary into the right location. The flash archive for Sun OTP is included in the bootable DVD that can be copied to jump start the system.

Create the JumpStart profile for flash archive.

# cat profile-flash
install_type            flash_install
archive_location nfs    <flash_archive_location>
partitioning            explicit
filesys                 c0t0d0s0 free /
filesys                 c0t0d0s1 4096 swap
filesys                 c0t0d0s3 512 /globaldevices
filesys                 c0t0d0s7 128

Modify the rule file to point to the profile you created.

hostname otpclient37    sparc   -       profile-flash

Update the JumpStart rules file by running the ~/rules_directory/check command.
Update the JumpStart server using the addclient command to enable booting of the system.
Log in to the system console and type:

ok boot net - install
After the OS is installed, set up the Sun OTP Provisioning Service. See To Install Sun OTP Using Sun OTP Bootable DVD Image in Sun Open Telecommunications Platform 2.0 Installation Guide.
Deploy the Sun OTP AHE environment through the Sun OTP Provisioning Service. See To Install Sun OTP Using Sun OTP Bootable DVD Image in Sun Open Telecommunications Platform 2.0 Installation Guide.

A sample JumpStart profile for a flash archive is as follows:

sample jumpstart profile for flash archive

samplel@sr1-usca-22:/net/otpinstall/export/jumpstart# cat profile-flash
install_type            *flash_install*
archive_location nfs    *anew20:/export/Flashes/sample_otp_sun4u*
partitioning            explicit
filesys                 c0t0d0s0 free /
filesys                 c0t0d0s1 4096 swap
filesys                 c0t0d0s3 512 /globaldevices
filesys                 c0t0d0s7 128

Modify the rules files to point to archive.

hostname otpclient37    sparc   -       profile-flash

Using N1 SPS From JET

You can add additional JET modules to the Solaris boot and install (JET) server. Although the process is described in the context of a flash module, the logic extends to other JET modules. For instructions on how to add a flash module, see How to Add a Flash Module in Sun N1 Service Provisioning System User’s Guide for OS Provisioning Plug-In 3.1.