Appendix A Example Plug-In

This appendix contains example code for a plug-in. This sample is based on the Solaris plug-in, which is provided with the Sun N1 Service Provisioning System 5.2 software.

Note –

For example purposes, this sample refers to version 1.1 of the Solaris plug-in. This sample does not reflect the functionality of the Solaris plug-in provided with the Sun N1 Service Provisioning System 5.2 software.

Description of the Sample Plug-In

The sample plug-in includes the following files and directories in the com.sun.solaris_1.1.jar file:

META-INF/
META-INF/MANIFEST.MF
1.1/
1.1/components/
1.1/components/com/
1.1/components/com/sun/
1.1/components/com/sun/solaris/
1.1/components/com/sun/solaris/Container.xml
1.1/components/com/sun/solaris/container_util.xml
1.1/components/com/sun/solaris/Patch.xml
1.1/plans/com/
1.1/plans/com/sun/
1.1/plans/com/sun/solaris/
1.1/plans/com/sun/solaris/Container-create
1.1/resources/
1.1/resources/com/
1.1/resources/com/sun/
1.1/resources/com/sun/solaris/
1.1/resources/com/sun/solaris/container_util/
1.1/resources/com/sun/solaris/container_util/sps_svcwait.sh
1.1/resources/com/sun/solaris/container_util/sps_sysidwait_zhalt.sh
1.1/resources/com/sun/solaris/container_util/sps_zattach.sh
1.1/resources/com/sun/solaris/container_util/sps_zboot.sh
1.1/resources/com/sun/solaris/container_util/sps_zcreate.sh
1.1/resources/com/sun/solaris/container_util/sps_zdelete.sh
1.1/resources/com/sun/solaris/container_util/sps_zdetach.sh
1.1/resources/com/sun/solaris/container_util/sps_zhalt.sh
1.1/resources/com/sun/solaris/container_util/sps_zinstall.sh
1.1/resources/com/sun/solaris/container_util/sps_zmatch.sh
1.1/resources/com/sun/solaris/container_util/sps_zra.sh
1.1/resources/com/sun/solaris/plugin-com.sun.solaris.jar
gui/
gui/pluginUI.xml
gui/solaris.gif
plugin-descriptor.xml
readme.txt

Sample Plug-In Descriptor File

The plugin-descriptor.xml defines the sample plug-in. Refer to the following items in the example below:

Most attributes to the <plugin> element use standard values. The three exceptions are the name,version, and description attributes.
The <dependencyList> element tells you that the system plug-in, version 1.0 is required for the sample plug-in to work correctly. The system plug-in is a core part of the Sun N1 Service Provisioning System software and should always exist.
The <folder> element creates a folder in which Solaris objects can be stored.
The <hostType> element declares the global_zone host type to be referenced by the plug-in. A set of variables are associated with this host type in the varlist attribute.
The <hostSearch> element defines a set of criteria for identifying target hosts to which this plug-in can provision.
The <hostSet> element defines the subset of target hosts to which this plug-in can provision.
The first <component> element defines a component with the resource solaris/container_util.xml.
The second <component> element includes the Container component in the plug-in.
The third <component> element creates a new component type, Patch. This component type has the following characteristics.
- The Patch component type will be displayed in the solaris group.
  
  If you want to prevent a component type from appearing in the drop down menu of component types on the Component Create page, change the group value to hidden.
- The backing component for the Patch component type is 1.1/components/com/sun/solaris/Patch.xml.
The <plan> element identifies the plan Container-create.xml as a part of the plug-in.

<?xml version="1.0" encoding="UTF-8"?>
<plugin name="com.sun.solaris"
		description="Solaris plugin @buildtag@"
		version="1.1"
		vendor="Sun Microsystems Inc"
		xmlns="http://www.sun.com/schema/SPS"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://www.sun.com/schema/SPS plugin.xsd"
		schemaVersion="5.2">
    	<readme jarPath="readme.txt"/>
    	<serverPluginJAR jarPath="1.1/resources/com/sun/solaris/plugin-com.sun.solaris.jar"/>
    	<gui jarPath="gui/pluginUI.xml"/>
    	<dependencyList>
      		<pluginRef name="system" version="1.0"/>
       </dependencyList>
    	<memberList>

    		<folder name="/com/sun/solaris" description="Solaris plugin folder"/>
					<hostType name="global_zone" 
					  description="a physical host from which partitioned 
					  local zones can be created"> 
						 <varList>
	    					<var name="local_zone_base_path" default="/export/zones"/>
	    					<var name="local_zone_default_name" default=""/>
	    					<var name="local_zone_default_filesystem" default="SPARSE"/>
	    					<var name="local_zone_connection_type" default="RAW"/>
	    					<var name="local_zone_port" default="1131"/>
	    					<var name="local_zone_advanced_params" default=""/>
	    					<var name="n1sps_cli_host" default="masterserver"/>
	    					<var name="n1sps_cli_path" 
								default="/opt/SUNWn1sps/N1_Service_Provisioning_System_*/cli/bin/cr_cli"/>
						</varList>
    			</hostType>

    			<hostSearch name="global_zones" 
					  description="matches Solaris global zone hosts">
						<criteriaList>
	    					<criteria name="sys.OS" pattern="SunOS"/>
	    					<criteria name="sys.OSVersion" pattern="5.10"/>
	    					<criteria name="sys.hostType" 
								pattern="com.sun.solaris#global_zone"/>
						</criteriaList>
						<appTypeCriteria ra="true"/>
						<physicalCriteria physical="true"/>
   			 	</hostSearch>

    			<hostSet name="global_zones" description="Solaris global zones">
						<hostSearchRef name="global_zones"/>
    			</hostSet>

    ...

					<component jarPath="1.1/components/com/sun/solaris/container_util.xml" 
						majorVersion="true">
      					<resource jarPath="1.1/resources/com/sun/solaris/container_util/" 
								name="/com/sun/solaris/container_util" type="DIRECTORY" 
								majorVersion="true"/>
					</component>

					<component jarPath="1.1/components/com/sun/solaris/Container.xml" 
						majorVersion="true"/>

					<component jarPath="1.1/components/com/sun/solaris/Patch.xml" 
						majorVersion="true">
						<componentType name="Patch" group="solaris" order="000000-000000-000001" 
							indentLevel="1" />
						</component>
     ...

    			<plan jarPath="1.1/plans/com/sun/solaris/Container-create.xml" 
						majorVersion="true"/>

    ...

  			</memberList>
</plugin>

Sample Composite Component

The sample plug-in contains the Container.xml file in the components directory. This component is untyped, and is designed to partition a system running the Solaris 10 OS into separate zones.. The following example creates a component with the following elements.

The path, name, description, and platform attributes to the <component> element provide specific information about the component type.
The <varlist> element defines several variables that enable the user to customize components based on this component type.
The <componentReflList> element calls the container_util component to perform several component tasks.
The <installList> element calls the <exceNative> step to run the LinSolaris commands to create zones.
The <uninstallList> element calls the <exceNative> step to run the Solaris commands to delete zones.
The <controllList> element calls the <exceNative> step to run shell scripts that perform a variety of system checks.

<?xml version="1.0" encoding="UTF-8"?>
<component platform='system#Solaris 10' 
  installPath=':[installPath]' 
  xmlns='http://www.sun.com/schema/SPS' 
  name='Container' version='5.2' 
  description='Solaris Container' 
  xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
  limitToHostSet='com.sun.solaris#global_zones' 
  softwareVendor='Sun Microsystems' 
  path='/com/sun/solaris' 
  xsi:schemaLocation='http://www.sun.com/schema/SPS component.xsd'>
		<varList>
			<var name='installPath' default=':[target:local_zone_default_name]' 
				prompt='Zone Name'></var>
			<var name='local_zone_filesystem' default=':[target:local_zone_default_filesystem]' 
				prompt='SPARSE,FULL'></var>
			<var name='local_zone_connection_type' default=':[target:local_zone_connection_type]' 
				access='PRIVATE'></var>
			<var name='local_zone_port' default=':[target:local_zone_port]' 
				access='PRIVATE'></var>
			<var name='local_zone_advanced_params' default=':[target:local_zone_advanced_params]' 
				access='PRIVATE'></var>
			<var name='n1sps_cli_host' default=':[target:n1sps_cli_host]' 
				access='PRIVATE'></var>
			<var name='n1sps_cli_path' default=':[target:n1sps_cli_path]' access='PRIVATE'></var>
			<var name='zoneIfaceDetails' default='' 
				prompt='Semicolon separted network_interface,IPAddress/netmask pairs. 
				Example: hme0,123.123.123.123/24;eri0,124.124.124.124/8.'></var>
			<var name='zoneFsLayout' default='' 
				prompt="Semicolon separted filesystem infos. 
				Example: dir=/usr/local special=/opt/local raw=/dev/rdsk/c0t0d0s7 
				type=lofs [ro,nodevices];dir=/opt/mystuff special=/empty type=lofs ro. 
				(see 'man zonecfg')"></var>
			</varList>
			<targetRef hostName=':[installPath]' typeName='com.sun.solaris#local_zone'>
				<agent params=':[local_zone_advanced_params]' ipAddr=':[installPath]' 
					port=':[local_zone_port]' connection=':[local_zone_connection_type]'></agent>
			</targetRef>
			<componentRefList>
				<componentRef name='container_util' installMode='TOPLEVEL'>
					<component name='container_util' path='/com/sun/solaris' 
						version='1.1'></component>
				</componentRef>
			</componentRefList>
			<installList>
				<installSteps returns='false' name='create'>
					<varList>
						<var name='raHomeDir' default=':[target:sys.raHomeDir]'></var>
						<var name='raDataDir' default=':[target:sys.raDataDir]'></var>
						<var name='raTmpDir' default=':[target:sys.raTmpDir]'></var>
						<var name='binPath' 
							default=':[target:sys.raDataDir]:[/]systemcomps:[/]com.sun.solaris:
								[/]container_util'></var>
						<var name='local_zone_base_path' 
							default=':[target:local_zone_base_path]'></var>
					</varList>
					<try>
						<block>
							<checkDependency>
								<toplevelRef name='container_util'></toplevelRef>
							</checkDependency>
						</block>
						<catch>
							<install blockName='default'>
								<toplevelRef name='container_util'></toplevelRef>
							</install>
						</catch>
					</try>
					<createDependency name='local_zone'>
						<toplevelRef name='container_util'></toplevelRef>
					</createDependency>
					<execNative userToRunAs='root' timeout='10800'>
						<exec cmd=':[binPath]/sps_zcreate.sh'>
							<arg value=':[installPath]'></arg>
							<arg value=':[local_zone_base_path]'></arg>
							<arg value=':[local_zone_filesystem]'></arg>
							<arg value=':[zoneIfaceDetails]'></arg>
							<arg value=':[zoneFsLayout]'></arg>
						</exec>
					</execNative>
					<execNative userToRunAs='root'>
						<exec cmd=':[binPath]/sps_zinstall.sh'>
							<arg value=':[installPath]'></arg>
							<arg value=':[raHomeDir]'></arg>
							<arg value=':[raDataDir]'></arg>
							<arg value=':[raTmpDir]'></arg>
							<arg value=':[local_zone_connection_type]'></arg>
							<arg value=':[local_zone_port]'></arg>
							<arg value=':[local_zone_advanced_params]'></arg>
						</exec>
					</execNative>
					<execNative userToRunAs='root'>
						<exec cmd=':[binPath]/sps_zboot.sh'>
							<arg value=':[installPath]'></arg>
						</exec>
					</execNative>
					<execNative userToRunAs='root'>
						<exec cmd=':[binPath]/sps_sysidwait_zhalt.sh'>
							<arg value=':[installPath]'></arg>
						</exec>
					</execNative>
				</installSteps>
					<installSteps returns='false' name='markOnly'></installSteps>
			</installList>
			<uninstallList>
				<uninstallSteps returns='false' name='delete'>
					<varList>
						<var name='binPath' 
							default=':[target:sys.raDataDir]:[/]systemcomps:[/]com.sun.solaris:
								[/]container_util'></var>
					</varList>
					<dependantCleanup>
						<uninstall blockName='unprep'>
							<thisComponent></thisComponent>
						</uninstall>
					</dependantCleanup>
					<checkDependency>
						<toplevelRef name='container_util'></toplevelRef>
					</checkDependency>
					<call blockName='deactivate'>
						<thisComponent></thisComponent>
					</call>
					<execNative userToRunAs='root'>
						<exec cmd=':[binPath]/sps_zdelete.sh'>
							<arg value=':[installPath]'></arg>
						</exec>
					</execNative>
				</uninstallSteps>
				<uninstallSteps returns='false' name='markOnly'>
					<dependantCleanup>
						<uninstall blockName='unprep'>
							<thisComponent></thisComponent>
						</uninstall>
					</dependantCleanup>
				</uninstallSteps>
			</uninstallList>
			<controlList>
				<control returns='false' name='activate'>
					<varList>
						<var name='raHomeDir' 
							default=':[target:sys.raHomeDir]'></var>
						<var name='binPath' 
							default=':[target:sys.raDataDir]:[/]systemcomps:[/]com.sun.solaris:
								[/]container_util'></var>
					</varList>
					<checkDependency>
						<toplevelRef name='container_util'></toplevelRef>
					</checkDependency>
					<execNative userToRunAs='root'>
						<exec cmd=':[binPath]/sps_zboot.sh'>
							<arg value=':[installPath]'></arg>
						</exec>
					</execNative>
					<execNative userToRunAs='root'>
						<exec cmd=':[binPath]/sps_svcwait.sh'>
							<arg value=':[installPath]'></arg>
							<arg value='/milestone/multi-user'></arg>
						</exec>
						<successCriteria></successCriteria>
					</execNative>
					<if>
						<condition>
							<equals value2='SSH' value1=':[local_zone_connection_type]'></equals>
						</condition>
						<then></then>
						<else>
							<execNative userToRunAs='root'>
								<exec cmd=':[binPath]/sps_zra.sh'>
									<arg value=':[installPath]'></arg>
									<arg value=':[raHomeDir]'></arg>
									<arg value='start noprompt'></arg>
								</exec>
							</execNative>
						</else>
					</if>
					<try>
						<block>
							<retarget host=':[n1sps_cli_host]'>
								<varList>
									<var name='sessionID' 
										default=':[session:sys:sessionID]'></var>
								</varList>
								<execNative timeout='60'>
									<inputText><![CDATA[

/bin/pkginfo -q SUNWspscl

if [ $? -eq 0 ]; then
    N1SPS_CLI=`/bin/pkginfo -r SUNWspscl`/cli/bin/cr_cli
else
    N1SPS_CLI=`/bin/ls :[n1sps_cli_path] | /bin/tail -1`
    if [ -z "$N1SPS_CLI" ]; then
        echo "N1 SPS cli not found"
        exit 1
    fi
fi

echo "Testing connection to RA on local zone ':[installPath]'" 

index=1
while [ $index -le 3 ];do
   output=`$N1SPS_CLI -cmd net.ping -d :[installPath]::[local_zone_port] -s :[sessionID]`
   echo $output | grep "Succeeded"
   if [ $? -eq 0 ]; then
      exit 0
   fi
   index=`expr $index + 1`
done
exit 1

		]]></inputText>
							
									<exec cmd='/bin/sh'></exec>
								</execNative>
								<execNative>
									<inputText><![CDATA[

/bin/pkginfo -q SUNWspscl

if [ $? -eq 0 ]; then
    N1SPS_CLI=`/bin/pkginfo -r SUNWspscl`/cli/bin/cr_cli
else
    N1SPS_CLI=`/bin/ls :[n1sps_cli_path] | /bin/tail -1`
    if [ -z "$N1SPS_CLI" ]; then
        echo "N1 SPS cli not found"
        exit 1
    fi
fi

echo "prep local zone ':[installPath]'"
$N1SPS_CLI -cmd pe.h.prep -tar NM::[installPath] -s :[sessionID]

		]]></inputText>
								<exec cmd='/bin/sh'></exec>
							</execNative>
						</retarget>
					</block>
					<catch></catch>
				</try>
			</control>
			<control returns='false' name='deactivate'>
				<varList>
					<var name='raHomeDir' default=':[target:sys.raHomeDir]'></var>
					<var name='binPath' default=':[target:sys.raDataDir]:
						[/]systemcomps:[/]com.sun.solaris:[/]container_util'></var>
				</varList>
				<checkDependency>
					<toplevelRef name='container_util'></toplevelRef>
				</checkDependency>
				<execNative userToRunAs='root'>
					<exec cmd=':[binPath]/sps_zhalt.sh'>
						<arg value=':[installPath]'></arg>
						<arg value=':[raHomeDir]'></arg>
					</exec>
					<successCriteria></successCriteria>
				</execNative>
			</control>
		</controlList>
</component>

Sample Simple Component

The sample plug-in contains the container_util.xml file in the components directory. This file defines the container_util component, which defines several utilities for installing, booting, and managing Solaris containers. The following example creates a simple component with the following elements.

The path, name, description, and platform attributes to the <component> element provide specific information about the component type.
The <extends> element indicates that the container_util component extends the features available in the system#directory component type.
The <varlist> element defines several variables that enable the user to customize components based on this component type.
The <resourceReflList> element references the container_util resource.
The <installList> element deploys the container_util resource, and creates a snapshot of the target host after the resource is deployed.

<?xml version="1.0" encoding="UTF-8"?>
<component platform='system#Solaris 10' xmlns='http://www.sun.com/schema/SPS' 
   name='container_util' version='5.2' description='Solaris Container Utilities' 
   xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
   softwareVendor='Sun Microsystems' path='/com/sun/solaris' 
   xsi:schemaLocation='http://www.sun.com/schema/SPS component.xsd'>
			<extends>
				<type name='system#directory'></type>
			</extends>
			<varList>
				<var name='installPath' 
					default=':[target:sys.raDataDir]:[/]systemcomps:[/]com.sun.solaris'></var>
				<var name='installPermissions' default='555'></var>
				<var name='installDiffDeploy' default='FALSE'></var>
			</varList>
			<resourceRef>
				<resource name='/com/sun/solaris/container_util' version='2.0'></resource>
			</resourceRef>
			<installList>
				<installSteps returns='false' name='default'>
					<deployResource></deployResource>
					<createSnapshot blockName='default'></createSnapshot>
				</installSteps>
			</installList>
</component>

Sample Plan

The sample plug-in includes the Container-create.xml file in the plans directory. This file defines the steps to be performed by the plug-in, and the components to use in these steps.

This sample plan contains the following elements.

The simpleSteps element calls the install block create.
The component element directs the plan to use the create install steps specified in the Container component

<?xml version="1.0" encoding="UTF-8"?>
<executionPlan xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
		name='Container-create' version='5.2' 
		xsi:schemaLocation='http://www.sun.com/schema/SPS plan.xsd' 
		xmlns='http://www.sun.com/schema/SPS' path='/com/sun/solaris'>
			<simpleSteps>
				<install blockName='create'>
					<component name='Container' path='/com/sun/solaris'></component>
				</install>
			</simpleSteps>
		</executionPlan>

Previous: Chapter 4 Using the Application Programming Interfaces