Building a Configuration Policy

2 Building a Configuration Policy

This chapter discusses configuration policy concepts and explains how to use the Oracle Communications IP Service Activator Software Development Kit (SDK) to create configuration policies. Configuration policies are implemented in a Service Activator installation using service cartridges. Refer to IP Service Activator SDK Service Cartridge Developer Guide for details about creating service cartridges.

A brief overview of the steps required to build configuration policies is given, followed by detailed sections explaining all the required activities. Included are steps to try out the procedures on the supplied bannerSample sample configuration policy source files.

Note:

For details about installing the SDK and the required third party tools, plus a detailed overview of all SDK concepts, a discussion of cartridge components, and an explanation of how cartridges integrate with the network processor, refer to IP Service Activator SDK Developer Overview Guide.

Table 2-1 lists the directory placeholders used in this guide.

Table 2-1 Directory Placeholders

Placeholder	Description
SDK_home	The directory in which the SDK is installed.
Service_Activator_home	The directory to which IP Service Activator is deployed. Typically C:Program Files\Oracle Communications\IP Service Activator

This guide assumes:

That the required versions of additional third party tools to support the SDK are installed correctly.
That you have set up the required environment variables to support the SDK functions.

For details on installing the SDK and the third party tool versions, refer to IP Service Activator SDK Installation and Setup Guide.

Building a Configuration Policy

This section lists the steps required to build a configuration policy. Following a brief introduction to these steps, each of the steps and all the activities required to execute them are covered in detail.

The steps to build a configuration policy are:

Creating a Configuration Policy Source Directory and Skeleton Properties File

In order to create your own configuration policy, you need to establish a uniquely named directory structure for the source files, and create the skeleton properties file that will be used to generate the starting source files.

Defining the Configuration Policy and Customizing the Properties File

This step involves determining the specific details of the configuration policy to be created and specifying the information needed to apply the desired configuration to the device. Refer to "Configuration Policy Generation Properties" for complete details on the properties.

Generating the Configuration Policy Source Files

This step uses the SDK tools to read the skeleton properties file and create the skeleton cartridge source files.

Customizing the Configuration Policy Source Files

This step is where most of your development effort will be spent. The key configuration policy source components include:

Schema for configuration policy data: see "Customizing the Configuration Policy Source Files" for details.
HTML GUI form: see "Creating an HTML GUI Form" for details.

Compiling and Packaging the Configuration Policy

This step uses the SDK tools to compile and package the configuration policy.

Performing End-to-End Tests

Use a service cartridge to deploy the configuration policy into a test Service Activator environment as an extension to a base or core cartridge. See IP Service Activator SDK Service Cartridge Developer Guide for information about creating service cartridges.

About the Provided Sample Configuration Policies

This section describes the sample configuration policies provided.

Components of the Provided Sample Configuration Policies

The SDK includes resources for two sample configuration policies: bannerSample and staticrouteSample.

Included with each sample are:

A skeleton.properties file used to generate the source files for the sample configuration policy. For more information, see "Generating the Configuration Policy Source Files".
A pre-edited sample schema used to demonstrate the edits required by the generated schema to produce a working sample configuration policy.

The provided sample schema is located in:

SDK_home\samples\configPolicy\bannerSample\...

The generated sample schema is placed in:

SDK_home\configPolicies\bannerSample\...

Completing the Sample

To complete the sample, you can either copy the provided files over their generated counterparts or edit the generated files.

Purpose of the Provided Sample Configuration Policies

The main values provided by the configuration policy sample are:

You can inspect the generated schema to see how a simple, working, configuration policy is constructed.
You can complete, compile and package the superceded generated sample source files into a working configuration policy and deploy it in a test system. The bannerSample configuration policy is implemented by the ciscoBanner service cartridge.
You can take a copy of the provided skeleton properties file, relocate and rename it, and use it as the starting point to generate your own skeleton configuration policy source files.

Note:

Configuration policies are not supported on every router type/OS. For example, not every router supports the banner sub-command banner slip-ppp command. Users must ensure that the router supports the configuration policy commands that they are trying to implement.

Sample Skeleton Properties File

The sample skeleton properties file that is used to create the source files for the bannerSample sample configuration policy is called:

SDK_home\samples\configPolicy\bannerSample\skeleton.properties

This properties file is pre-populated with the information needed to construct the starting source files for the bannerSample sample configuration policy.

Some of the generated source files will require editing or you can overwrite them with the provided source files.

As you read through the configuration policy creation steps, instructions are given on how to use the sample to test some of the SDK tools and commands.

Refer to "Configuration Policy Generation Properties" for details on all the properties implemented in the sample properties files which create the source files for the sample.

Sample Configuration Policies

The configuration policy samples are:

BannerSample
StaticrouteSample

Sample bannerSample Configuration Policy

The bannerSample sample contains a schema for a consolidated banner Configuration Policy that allows you to configure a sequence of one or more of each possible banner command.

Key concepts illustrated by the sample include:

Filling out the skeleton properties for a configuration policy
Architecting the configuration policy schema
Dealing with versioning and upgrades

It is assumed that only one occurrence of each banner type can exist on a device.

The banner types that can occur are:

Exec: exec process creation banner
Incoming: incoming terminal line banner
Login: login message banner
MOTD: message of the day banner
Slip-ppp: slip-ppp message banner

Each banner is configured with a message which must begin and end with a delimiting character of your choice. The delimiting character must not otherwise appear in the message. The message may be single-line or multi-line. New line characters are allowed.

An example banner follows:

Type:    motd
Message: #Enter text for message of the day here.#

A configuration policy requires a service cartridge implementation. For details on the ciscoBanner service cartridge, refer to IP Service Activator SDK Service Cartridge Developer Guide.

Sample staticrouteSample Configuration Policy

The staticrouteSample sample contains a schema that allows you to configure one or more static routes. Static routes are routes that cause packets moving between a source and a destination to take a specified path. Such routes are useful for specifying a gateway of last resort to which all unroutable packets will be sent.

Key concepts illustrated by the sample include:

Filling out the skeleton properties for a configuration policy
Architecting the configuration policy schema
Dealing with versioning and upgrades

Static route configuration parameters are:

Destination Prefix: IP address for the destination network in dotted decimal notation
Destination Mask: subnet mask for the destination address in dotted decimal notation
Next Hop IP: next hop IP address in dotted decimal notation
Exit Interface Name: exit interface name
Distance Metric: metric value as the distance metric for this route

A configuration policy requires a service cartridge implementation. For details on the ciscoStaticRoute service cartridge and its parameters and options, refer to IP Service Activator SDK Service Cartridge Developer Guide.

Creating a Configuration Policy Source Directory and Properties File

To create your own configuration policy, you will need to establish a directory structure for the source files, and create a skeleton properties file to generate the starting source files.

The simplest method is to copy the sample skeleton.properties file and edit it for your own use.

To copy and edit the sample skeleton.properties file:

Create a unique name that identifies the configuration policy. This name will be referred to as this_config_policy.
Create a new directory to hold your source files. For example:

SDK_home\configPolicies\this_config_policy

Copy the sample skeleton.properties file into your directory:

copy SDK_home\samples\configPolicy\bannerSample\skeleton.properties
SDK_home\configPolicies\this_config_policy

Edit your skeleton.properties file and change bannerSample to the this_config_policy in the following entries:

## config policy name
sdk_global_configPolicyName=this_config_policy
. . .
## packaging structure
sdk_global_package=com.metasolv.serviceactivator.configpolicies.this_config_policy
## configuration policy schema
sdk_schema_namespace=http://www.metasolv.com/serviceactivator/this_config_policy
sdk_schema_namespaceAbbr=bn
sdk_schema_topLevelTag=this_config_policy
sdk_schema_topLevelType=this_config_policy
 
sdk_xmlbeans_package=com.metasolv.serviceactivator.this_config_policy

Defining the Configuration Policy and Customizing the Properties File

You must perform this step before creating your Configuration Policy. This involves determining the specific details of the configuration policy to be created and specifying the information needed to apply the desired configuration to devices.

The configuration policy may require application across multiple operating systems or device types. This can affect the definition of the configuration policy and/or require separate configuration policies to be defined to achieve the desired end-goal.

A single configuration policy to implement a generic type of service may be subscribed to by multiple service cartridges, each implementing it on a specific vendor's device.

Once the configuration policy is designed, use one of the sets of sample skeleton configuration policy source files as a starting point to creating a configuration policy.

Generating the Configuration Policy Source Files

The SDK provides a tool for generating the configuration policy source files from the skeleton properties file. Once the source files are generated, you will need to edit them to complete your configuration policy.

Generating the bannerSample Configuration Policy Source Files

To generate the bannerSample configuration policy source files using the data from the sample skeleton properties file:

Set the configuration policy version string variable. For example, if the configuration policy version is 1.0, on a Windows host, type the command:
```
set VERSION_STRING=1.0
```
Do one of the following:
- In the SDK directory, run the cartridge generator script by running the included batch file:
```
gencp samples\configPolicy\bannerSample\skeleton.properties
```
  or
- Type in the command to run the cartridge generator script:
```
ant -DtemplateType=configPolicy -DpropFile=SDK_home\samples\configPolicy\bannerSample\skeleton.properties
```

Note:

To use the batch file, you must first add SDK_home\bin to your PATH variable where SDK_home is the SDK directory.

Result of the Generation Process

The directory structure you created previously (see "Creating a Configuration Policy Source Directory and Properties File") has been extended using the sdk_global_configPolicyName value from the skeleton properties file. The source files generated under SDK_home\configPolicies\sdk_global_configPolicyName\ include:

build.xm: ant build file to build the configuration policy.
src\...\schema\bannerSample.xsd: contains the configuration policy schema that will be used to validate the data entered through the Service Activator client.
src\ConfigPolicyRegistry.xml: contains registry information for the configuration policy used to integrate it with a service cartridge.

The skeleton source file generation process also creates a log file is within the logs directory at SDK_home\logs\generator.log.

To continue working with the sample configuration policy, go to "Compiling the Configuration Policy".

Generating Your Own Configuration Policy Source Files

When you create your own configuration policy, the configuration policy name and the root folder for the generated source are based on the sdk_global_configPolicyName property value in the skeleton properties file. See "Creating a Configuration Policy Source Directory and Properties File" for details. The property value is incorporated into the source files in place of sdk_global_ConfigPolicyName.

To generate your own configuration policy source files using your customized skeleton properties file:

Set the configuration policy version string variable. For example, if the configuration policy version is 1.0, on a Windows host, type the command:
```
set VERSION_STRING=1.0
```

Do one of the following:

In the SDK directory, run the cartridge generator script by running the included batch file:
```
gencp configPolicies\<sdk_global_configPolicyName>\skeleton.properties
```
or

Type in the command to run the generator script:

ant -DtemplateType=configPolicy -DpropFile=SDK_home\configPolicies\sdk_global_configPolicyName\skeleton.properties

Note:

To use the batch file, you must first add SDK_home\bin to your PATH variable where SDK_home is the SDK directory.

Result of the Generation Process

This extends the SDK directory structure in a similar manner to what is described in "Generating the Configuration Policy Source Files".

Note:

It is possible to use a different name for the skeleton properties file. If you choose to do this, supply the new name instead of skeleton.properties in the ant commands.

Troubleshooting Configuration Policy Generation

This section discusses where to find information to help you resolve configuration policy generation issues.

Using an Alternate Directory Structure

If you are not using the standard directory structure to lay out all the configuration policies, base cartridges and service cartridges being developed using the SDK, then you must modify the Java sample build.xml file to ensure that all instances of sdkDir are replaced with valid paths to the respective files. The preferred way to do this is to set sdkDir to the top level directory for all the SDK-based artifacts.

Configuration Policy Generator Message Logging

The logging level of the configuration policy generator can be controlled by editing the settings in the SDK_home\config\logging.properties file.

The default is to log debug level messages. Output is sent to both stdout and a logging file: SDK_home\logs\generator.log.

For details on troubleshooting property file attributes, see IP Service Activator SDK Base Cartridge Developer Guide.

Customizing the Configuration Policy Source Files

When creating a configuration policy, you will need to make appropriate edits to the schema to support the particular functionality you want to implement. You will also need to create an HTML GUI form.

Completing the Configuration Policy Source Files

You will need to make appropriate edits to the schema to complete the configuration policy source files.

Note:

The provided schema is located in SDK_home\samples\configPolicy\bannerSample\src\...\schema\schema.xsd and the generated schema is located in SDK_home\configPolicies\bannerSample\src\...\schema\bannerSample.xsd.

Completing the bannerSample Configuration Policy Schema

To complete the bannerSample configuration policy schema:

Do one of the following:
- Copy the provided schema over the generated schema.
  
  or
- Edit the generated schema to complete its content development.
  
  The provided schema demonstrates the edits required to complete the generated schema to produce a working sample configuration policy.

Completing the staticrouteSample Configuration Policy Schema

To complete the staticrouteSample configuration policy schema:

Do one of the following:
- Copy the provided schema over the generated schema.
  
  or
- Edit the generated schema to complete its content development.
  
  The provided schema demonstrates the edits required to complete the generated schema to produce a working sample configuration policy.

Completing Your Own Configuration Policy Schema

Once you have created your configuration policy schema using the process described in "Generating Your Own Configuration Policy Source Files", edit your schema to add the elements to describe the details of your Configuration Policy.

Creating an HTML GUI Form

The SDK includes a Configuration Policy HTML GUI builder tool. It builds an HTML file from the XML Bean of a configuration policy that can be used in the Service Activator client to create or edit an instance of that configuration policy.

Figure 2-1 illustrates the flow of data between the GUI extensions specified in the extension XSD file (i.e. SDK_home\schema\cartridge.xsd)and the object model.

Figure 2-1 Data Flow Between GUI Extensions and Object Model

Description of "Figure 2-1 Data Flow Between GUI Extensions and Object Model"

GUI Extension Schema API

A service model extension schema embeds GUI extension information for all the elements that have an HTML representation. HtmlGuiBuilder relies on the GUI extension information to translate a schema element into an HTML widget, a text area, an input box, a drop-down, a JavaScript import, or other output.

The GUI extension information is defined in guiextensions.xsd. The following example shows how to add GUI extension information to any schema element.

<xs:schema targetNamespace="http://www.metasolv.com/serviceactivator/banner"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:bn="http://www.metasolv.com/serviceactivator/banner" xmlns:lib="http://www.metasolv.com/serviceactivator/devicemodel"
xmlns:app="http://www.metasolv.com/serviceactivator/guiextensions"
xmlns:ipsa="http://www.metasolv.com/serviceactivator/documentation"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="banner" type="bn:Banner" minOccurs="0" maxOccurs="unbounded">
  <xs:annotation>
    <xs:appinfo>
      <app:gui>
        <!-- displayName become the label on the field -->
          <app:displayName>Banner</app:displayName>
          … …
      </app:gui>
    </xs:appinfo>
  </xs:annotation>
</xs:element>

Table 2-2 lists the possible schema types and their HTML widget equivalents.

Table 2-2 GUI Extension Schema Element Details

Schema Type	HTML Widget
<app:displayName>	Field label
<app:defaultValue>	Field default value
<xs:enumeration>	Dropdown menu label and value
<app:textarea>	text area
<app:size>	Field size
<app:optional>	Reserved
<xs:choice>	Not supported

Note:

There are three points to note with regard to the schema elements:

A field can be an input box or a drop-down list.
If an element has minOccurs="0", and it is a drop-down list, an empty item will be added to the list and selected as the default.
If an object has multiple elements, an Add button and a Delete will be added to the HTML file, to create or delete an instance of the object.

Compiling the Configuration Policy

Configuration policy source files are compiled using ant. The compilation process creates the required XML beans for it and packages them into a .zip file.

Note:

A classpath environment variable may interfere with the classpath required by the SDK. It is therefore recommended that the classpath environment variable be unset in the window or where the SDK is being used.

Compiling the bannerSample Configuration Policy Source Files

To compile the bannerSample configuration policy source files:

Set the configuration policy version string variable. For example, if the configuration policy version is 1.0, on a Windows host, type the command:
```
set VERSION_STRING=1.0
```
Compile the bannerSample configuration policy source files with the command:
```
ant package -fSDK_Home\configPolicies\bannerSample\build.xml
```

Compiling the staticrouteSample Configuration Policy Source Files

To compile the bannerSample configuration policy source files:

Set the configuration policy version string variable. For example, if the configuration policy version is 1.0, on a Windows host, type the command:
```
set VERSION_STRING=1.0
```
Compile the bannerSample configuration policy source files with the command:
```
ant package -fSDK_Home\configPolicies\staticrouteSample\build.xml
```

Compiling Your Own Configuration Policy Source Files

To compile your own configuration policy source files when you are done editing them:

Set the configuration policy version string variable. For example, if the configuration policy version is 1.0, on a Windows host, type the command:
```
set VERSION_STRING=1.0
```

Compile the configuration policy source files with the command:

ant package -fSDK_Home\configPolicies\sdk_global_configPolicyName\build.xml

This will result in the following additions to the Configuration Policy directory structure:

SDK_home\configPolicies\sdk_global_configPolicyName
build.xml
beansrc
classes
html
lib
  sdk_global_configPolicyName.jar
package
  sdk_global_configPolicyName-configPolicy-${env.VERSION_STRING}.zip

Troubleshooting Configuration Policy Compiling

Compilation problems will be caused by schema errors. To debug these problems, load the schema into an XML schema aware editor. This will make it much easier to find and correct problems in the schema.

Manifest File

When a Configuration Policy is built, a manifest file is created listing all of the files that are packaged into the Configuration Policy zip file. Installation of the Configuration Policy places the manifest in the uninstall directory of the IP Service Activator installation.

Creating Interface Management Properties

In IP Service Activator the following has been implemented for configuration policies related to interface or sub-interface creation and decoration.

Whenever an interface or sub-interface is created or decorated through IP Service Activator, if the user specifies the IP address and netmask in the HTML page, the user can see the IP address and netmask in the interface properties immediately. Both IPv4 and IPv6 address formats are supported.

For configuration policies shipped with IP Service Activator, the location of ipaddress and ipnetmask is fixed in the subinterface.xsd.

The path of the elements is as follows:

ipaddress: root Node/primaryAddress/ipAddress
ipNetMask: root Node/primaryAddress/ipNetMask

If you are using the SDK to create your own configuration policies related to interface or sub-interface creation and decoration, you may wish to change the element names (other than ipaddress and ipnetmask).

To change the element names:

Implement a new mappings tag.

The tag has the following constraints:
- The tag must be present in your XSD file.
- The tag is always related to a target. The only valid target is Interface.

The layout of the tag is:

 <xs:annotation> 
        <xs:appinfo> 
            <model:mappings  target="Interface"> 
                <model:mapping direction="export"> 
                    
<model:source_path>primaryAddress/ipAddress</model:source_path> 
                    
<model:target_attribute>ipAddress</model:target_attribute> 
                </model:mapping> 
                <model:mapping direction="export"> 
                    
<model:source_path>primaryAddress/ipNetMask</model:source_path> 
                    
<model:target_attribute>ipNetMask</model:target_attribute> 
                </model:mapping> 
            </model:mappings> 
        </xs:appinfo> 
    </xs:annotation>

Under mappings, you can specify a list of mappings. Each mapping contains a direction attribute. The supported direction is export.

Each mapping has source_path and target_attribute as sub-tags. The source_path can tell the path of the attribute from the root.

The target_attribute is fixed. The only supported target attributes are ipAddress and ipNetMask.

Deploying Configuration Policies

The generated SDK configuration policy zip file needs to be deployed on a Service Activator Network Processor host as well as on a Service Activator client host.

To deploy the configuration policy to a Network Processor host:

Unzip the sdk_global_configPolicyName-configPolicy-${env.VERSION_STRING}.zip file to the runtime environment of the Network Processor in the Service_Activator_home directory. The configuration policy schema, for example bannerSample.xsd, is installed in Service_Activator_home\Config\schema.
If the Network Processor is already running, restarted it to load sdk_global_configPolicyName.jar.

To deploy the configuration policy to the policy server host:

Unzip the sdk_global_configPolicyName-configPolicy-${env.VERSION_STRING}.zip file to the Service_Activator_Home directory.
Using the IP Service Activator client, right-click the Domain object and select Properties.

The Properties dialog appears.
Select Setup.
Click Browse and select the sdk_global_configPolicyName.policy file.
Click OK.
Click Load and commit.

The configuration policy is now deployed.

Configuration Policy Version

Once the configuration policy is deployed, any newer version of the configuration policy which includes schema edits should be built with another version number.

To up-version the configuration policy:

Modify the version value in ConfigPolicyRegistry.xml to supply a service model XQuery transform referenced from the <upgrade> tag in ConfigPolicyRegistry.xml.
Rebuild the package.

For example, with version 1.0 of a configuration policy deployed, a configuration policy concrete may be created. Now version 2.0 is built and deployed and the Network Processor is restarted. At the time that modifications to the configuration policy concrete are committed, the Network Processor will compare the currently registered version 2.0 with version 1.0 in the previously saved service model and detect a version mismatch. An upgrade exception will be thrown causing a fault to be raised and the device state to change to Intervention Required. NpUpgrade should be used by an administrator to perform the required service model upgrade transforms.

NpUpgrade

The SDK includes the file config_policy_registration.xsd under SDK_home\schema. NpUpgrade calls the XQuery pointed to by the <upgrade> tag in the ConfigPolicyRegistration.xml file. The purpose of the XQuery is to upgrade the configuration policy data from the old version to the new version inside the service model document in the database. An XQuery is provided with each sample (e.g. bannerSample_upgrade.xq).

The ConfigPolicyUpgradeTest.java file runs the XXX_upgrade.xq XQuery on the XXX_invalid.xml and XXX_valid.xml files. These files can be modified and run to test variations of the xquery and xml input. You can build and run these tests using ant unitTests from the ipsaSDK/configPolicies/XXX folder. The result of running the test goes into file reports/TEST---.xml underneath this folder.

The sample XQuery for banners (bannerSample_upgrade.xq) does the following:

Replaces any <bannerType> elements that have the text tmotd with the text motd
Removes any <bogus> or <obsolete> elements
Keeps all other elements as is

The sample XQuery for static routes (staticrouteSample_upgrade.xq) does the following:

Replaces any <ipa> element found with an <ip> element with the same content
Removes any <bogus> or <obsolete> elements
Keeps all other elements as is

Uninstalling Configuration Policies

Configuration policies are uninstalled using the uninstallCartridge.sh script, which resides in the bin directory of the IP Service Activator installation. This script takes the name of the manifest file, which contains a list of all installed configuration policy files, as a parameter, and uses its contents to uninstall the configuration policy. (See "Troubleshooting Configuration Policy Compiling".)

You can include the base directory or the IP Service Activator installation as a parameter to the script. If you do not, the script queries the ORCHcore package to locate the base directory of the IP Service Activator installation.

The uninstallCartridge.sh script sorts the manifest file in reverse order, then deletes files, and then directories. Only empty directories are removed; this ensures that the script will not remove directories used by other cartridges.

Note:

you can use a relative path to specify the manifest file, but it must be relative to the current directory (i.e. where you are running the uninstall script from). You can also use an absolute path. To verify that the manifest file is in the directory, use the command "ls<manifest>" using the same value that is provided to the script.

To uninstall configuration policies:

Use the following command:
```
uninstallCartridge <manifest_file> [Service_Activator_home] [-k | -v]
```
Use the -k option to leave empty directories. The -v (verbose) option produces extra output from the script.
Once uninstallation is complete, restart the Network Processor.

Note:

Uninstalling a cartridge or configuration policy developed using the SDK does not remove the network processor's device model entries that reference this cartridge or configuration policy. This information is maintained because it is unknown whether you are uninstalling the cartridge or configuration policy to remove it or to upgrade it.

To uninstall a configuration policy HTML GUI form from a Service Activator GUI host:

Delete the configuration policy HTML file from the Service_Activator_home directory.
Edit Service_Activator_home\Config\ ConfigurationPolicy.cfg to delete the policytypeReference name and reference to the configuration policy html file.

To remove a generated configuration policy from the SDK installation:

Delete all contents under SDK_home\configPolicies\sdk_global_configPolicyName

To uninstall the SDK:

Delete all contents under SDK_home.