Chapter 5 Copying Objects Between Master Servers

In this release of the N1 Service Provisioning System, a new Import-Export feature has been provided to enable you to easily copy various Service Provisioning System objects at once from your development master server to your testing server, to your staging master server, and from there to your production master server. Service Provisioning System objects can include:

• Component Types

• System Services

• Host Types

• Host Sets

• Host Searches

• Folders

• Components

• Plans

Overview of the Import-Export Feature

Service Provisioning System objects such as components, plans and host sets can now easily be copied from one master server into a single file and on to another master server. This is done as follows:

1. On the source master server, create a bundle template.

   A bundle template contains an ordered list of search criteria that add your selection of service provisioning system objects such as the following:

   • Component Types

   • System Services

   • Host Types

   • Host Sets

   • Host Searches

   • Folders

   • Components

   • Plans

   The ordering of these objects is important, because you export these objects in to the bundle template, using search criteria, in the order of the objects' mutual dependencies: matched objects are exported into the bundle template in the order of the search criteria that they match. See Declaring Search Criteria for a Bundle Template for details. If the objects are not exported in the correct order, the export succeeds but the subsequent import operation can fail.

2. When you have created and saved the bundle template, export the bundle template in to a bundle jar. See Exporting a Bundle Template to a Bundle Jar for details.

   You can manually create a bundle jar, or modify it after it has been automatically created by the system. This is on the condition that the jar contents are always consistent with the bundle descriptor file. See Contents of a Bundle Jar for details.

3. On the destination master server, test to see if the import of the bundle jar would work, using the validate feature. See Example 5–8 for details.

4. If the validation succeeds, import the bundle jar. See Example 5–9 for details.

All users can use the import-export feature.

Creating a Bundle Template

Create a bundle template using the bdb.b.add command. Use the following arguments with the bdb.b.add command:

name

The name of the bundle template

desc

A description of the bundle template

criteria

Search criteria for entities to be included in the bundle template.

The result of the bdb.b.add command is the generation of a unique bundle ID.

For full usage of this command, see Appendix A, Appendix — New Commands.

The bundle ID can be a cumbersome ID to enter at the command-line. Consider substituting the ID for a shorter term using the NM command as described in Using NM: to Perform ID Substitution in Sun N1 Service Provisioning System 5.2 Command-Line Interface Reference Manual.

A bundle template cannot contain another bundle template.

Declaring Search Criteria for a Bundle Template

When you create the bundle template, specify search criteria for plans, components or other objects in the correct order of their dependencies.

To specify search criteria for the bundle template, use the bdb.b.add command.

The order in which you declare search criteria using the bdb.b.add command is important. Matched objects are exported into the bundle jar in the order of the search criteria that they match. The search criteria must be in the correct order of the matched object's dependencies.

The ordering of systemService and componentType search criteria is not significant. The component to which they refer must be included in the same bundle template.

Search criteria can be specified as set out in the following table.

For example, it is possible to specify the name and description search criteria for system services.

If you specify a search criterion for an entity and the entity does not exist, the creation of the bundle template is successful but the export to a bundle jar does not succeed.

Bundle templates can have zero or more search criteria.

Criteria are declared as attribute=value pairs, separated by a comma. Multiple similar criteria are separated by a semicolon. Pattern strings that contain a comma, semicolon or an equals character in them can be included by the use of '\' (backslash) as an escape character. Backslash itself could be specified as '\\' in the pattern. Attributes are declared as follows:

name

The name of the entity or object to be searched for.

desc

The description of the entity or object to be searched for. This corresponds to the description property of the entity searched for.

vis

Visibility of the entity or object to be searched for.

ver

The version of the entity or object to be searched for.

ct

extendsType. Refers to the componentType the sought component is extending. This helps search components that extend a particular Component Type. This attribute is only applicable to the component search.

lab

The label of the entity or object to be searched for.

Search Criteria Validation

Search criteria are validated internally using the following character limits.

• Name: 512 characters

• Description: 1024 characters

• Folder path: 512 characters

• Type: 129 characters

• Label: 32 characters

• Visibility: this can be either hidden or, by default, visible.

Example 5–1 Creating a Bundle Template

This example shows a bundle template being created with the bdb.b.add command. Note that the search criteria are separated by semicolons, and attribute value pairs are separated by = as described in Declaring Search Criteria for a Bundle Template.

bdb.b.add -name b1 -desc d1 -criteria "C:name=comp*;P:name=myPlan;F:name=myFolder;"

The result of the command is that the bundle template is created and the associated bundle ID is returned.

129158239041-1163688372443-00830-2096382958

For full usage of this command, see Appendix A, Appendix — New Commands.

Viewing and Listing Bundle Templates

This section explains how to view a bundle template and how to list all bundle templates on the master server.

Listing All Bundle Templates

To list all bundle templates, use the bdb.b.la command.

The output of the bdb.b.la commands is as follows:

BundleID

The ID of the bundle template

Bundle Name

The name of the bundle template

Bundle Description

The description of the bundle template.

Last Updated

The date, time, and time zone information for when the bundle template was last updated.

For full usage of this command, see Appendix A, Appendix — New Commands.

Example 5–2 Output of the bdb.b.la Command

This example shows a sample output returned after issuing the bdb.b.la command, which lists all bundle templates on the master server.

|------------------|----------|------------|--------------------------------------|
|BundleID |Name |Description |LastUpdated |
|-----------------------------------------|----------|------------|----------------------------|
|129158239109-1160744183744-00241-1568077714|bplan4 |bundes1 |Fri Oct 13 18:26:24 IST 2006|
|129158239109-1160744183744-00241-1568077712|bplan3 |bundes3 |Fri Oct 13 12:26:24 IST 2006|
|-------------------------------------------|----------|------------|--------------------------|

The output shows that there are two bundle templates. The first string of numbers is the bundle ID. Looking at the first of the two bundles, its ID is 129158239109-1160744183744-00241-1568077714 and its bundle name is bplan4. Its bundle description is bundles1.

Viewing a Single Bundle Template

To display the details of a single bundle template, including the defined search criteria and the corresponding elements or objects, use the bdb.b.lo command with the -ID argument, where ID is the ID of the bundle template. You can substitute the ID as explained in Creating a Bundle Template.

The default output of the bdb.b.lo command is the same as that of the bdb.b.la command.

In addition, with the bdb.b.lo you can use the -o option to obtain a more detailed summary. The following information is displayed in tabular form:

BundleID

The ID of the bundle template

Bundle Name

The name of the bundle template

Bundle Description

The description of the bundle template.

Last Updated

The date, time, and time zone information for when the bundle template was last updated.

Criteria Pattern Details

The search criteria of the bundle template.

Entities Matched

The objectType, ID, name and version of entities that matched the search criteria of the bundle template.

For full usage of this command, see Appendix A, Appendix — New Commands.

Example 5–3 Output of the bdb.b.lo Command

This example shows a sample output returned after issuing the bdb.b.lo command to list the details of a specified single bundle template. In this example, the command is issued with the -o option, and the NM command has been used to replace the bundle ID with a shorter term.

bdb.b.lo -ID NM:b3 -o detail

The result is as follows.

BundleID : 129158239041-1162211396014-00217-0193112936
Name : b3
Description : bundes3
LastUpdated : Mon Oct 30 17:59:56 IST 2006
Criteria Pattern Details :
|----------|------|----------|------------|-------|----------|------------|-----------|
|CriteriaType|Select ALL|Name |Description |Version|Label |FolderPath|ExtendsTypeName|
|----------|------|----------|------------|-------|----------|------------|-----------|
|HostType |False |bundleHost2|descBundle2 | | | | |
|HostType |False |bundleHost1|descBundle1 | | | | |
|----------|------|----------|------------|-------|----------|------------|-----------|
Entities Matched :
|---------------|---------------|----------|-------|
|ObjectType |ObjectID |Name |Version|
|---------------|---------------|----------|-------|
|HostType |129158239041-1162211393799-00201-0215113755|bundleHost1-2-1162211393664| |
|HostType |129158239041-1162211393838-00205-0238623680|bundleHost2-3-1162211393830| |
|---------------|---------------|----------|-------|

The bdb.b.lo command can be used without the -o option, to get a summary of the details of a single bundle template.

bdb.b.lo -ID NM:b3

The result is as follows.

BundleID : 129158239041-1162211396014-00217-0193112936
Name : b3
Description : bundes3
LastUpdated : Mon Oct 30 17:59:56 PST 2006

Modifying a Bundle Template

Once you have created a bundle template, you can edit its name, description and search criteria. Use the bdb.b.mod command to modify the bundle template. Use the following arguments with the bdb.b.mod command:

ID

The ID of the bundle template.

desc

The new description of the bundle template.

criteria

Search criteria for entities to be included in the bundle template. Criteria are declared as indicated in Declaring Search Criteria for a Bundle Template.

The bdb.b.mod command does not change the ID of the bundle template.

Once you are satisfied with the bundle template, save it and export it in the form of a bundle jar.

The bdb.b.mod command overwrites existing search criteria.

To delete a single search criteria, all existing criteria except the one to be deleted, need to be provided to the bdb.b.mod command.

When you use the bdb.b.mod command with the -criteria option, all existing are overwritten, even if you do not declare them with the bdb.b.mod command. Criteria that you do not declare are removed.

For full usage of this command, see Appendix A, Appendix — New Commands.

Example 5–4 Using the bdb.b.mod Command to Modify a Bundle Template By Overwriting Existing Criteria

This example shows how to use the bdb.b.mod command to modify a bundle template, overwriting all existing search criteria.

bdb.b.mod -ID 129158239041-00830 -criteria
"CT:name=myCompType;HS:name=myHostSet;HR:name=myHostSearch;HT:name=myHostType;"

The output of the command is the bundle template ID.

129158239041-00830

The ID remains that same as it was before the bundle template search criteria were modified.

Example 5–5 Using the bdb.b.mod Command to Modify a Bundle Template and Remove Existing Criteria

This example shows how to use the bdb.b.mod command to modify a bundle template, removing all existing search criteria.

bdb.b.mod -ID NM:b1 -desc  "modified" -criteria "empty"

The following command also works.

bdb.b.mod -ID NM:b1 -desc  "modified" -criteria ""

The output of the command is the bundle template ID.

129158239041-1163688372443-00830-2096382958

The ID remains that same as it was before the bundle template's search criteria were removed.

Deleting a Bundle Template

Delete a bundle template using the bdb.b.del command.

The bdb.b.del command takes the ID of the bundle template as an argument. You can delete a bundle template without deleting the entities that it references. This is because the entity search criteria, and not the entities themselves, are saved in the bundle template.

Example 5–6 Using the bdb.b.del Command to Delete a Bundle Template

This example shows how to use the bdb.b.del command to delete a bundle template.

bdb.b.del -ID NM:myBundle

For full usage of this command, see Appendix A, Appendix — New Commands.

Exporting a Bundle Template to a Bundle Jar

When you have created the bundle template, you are ready to export it to a bundle jar.

Specify the file system path in which to save the bundle jar. The maximum size of a bundle jar is 2GB.

Use the bdb.b.exp command to export a bundle template to a bundle jar: This command takes the ID of the bundle template as an argument. The path argument is also used, to specify the path to the file system in which to save the bundle jar.

For full usage of this command, see Appendix A, Appendix — New Commands.

During the export of the bundle template, if the resultant bundle jar would exceed 2GB, the export operation fails.

If more than one search criteria match the same object, only the first criteria is considered.

Only a saved bundle template can be used to export a bundle jar.

Bundle template search criteria must refer to a single version of objects that can have versions. Export of multiple versions of the same object is not supported.

The default value for the visibility filter is visible therefore, unless specified otherwise in the command criteria, only visible entities are exported.

Do not export directories that have symbolic links within them. Export of a directory containing a symbolic link fails.

On export, the resource version number is set to 1.0, if it is already not 1.0 in the component XML. If the resulting bundle jar was imported to a master server that did not already have this resource checked in, import would have failed. To avoid this, the version is set to 1.0 implicitly.

The export operation fetches the bundle template immediately, hence any subsequent edit or delete operations on the bundle template do not impact the export operation.

Example 5–7 Using the bdb.b.exp Command to Export a Bundle Template

This example shows how to use the bdb.b.exp command to export a bundle template to a Bundle Jar. The jar path is input as /aa/aa/abc.jar

bdb.b.exp -ID NM:myBundle -path "/aa/aa/abc.jar"

The result is as follows.

Processed:Folder=1, Plan=1

The output shows that the operation was successful.

Importing a Bundle Jar

A bundle jar can be imported by selecting it from the local filesystem. If the operation is successful, its entities are added to the destination master server in the order specified in the bundle descriptor file.

Ensure that all entities satisfy the usual requirements of the provisioning system, and that any plugins on which they depend are already imported.

Use the bdb.b.imp command to import a bundle jar from the local file system. This command takes the following arguments:

• path: The path to the file system from which to import the bundle jar.

• owner: The group destined to be owner of folders created through the import operation. Use this to specify the owner group of all folders to be created by the bundle jar. When a new leaf or interior folder is created, ownership is by the same group.

• v: Default value is false. Set this to true if you want to validate the import, but do not want to actually execute the import operation. Setting the value to true simulates the import, and returns any possible errors. If no errors would occur, this returns the number of entities that would be imported. Setting this value to true means that the actual import operation does not take place.

For full usage of this command, see Appendix A, Appendix — New Commands.

On each master server, you can only import one bundle jar at any time.

After the import operation, the newly imported objects are visible, but are not categorized. Any previous versions of these objects are implicitly hidden.

Entities added or updated by the import operation have no record that they were checked in by a bundle jar.

If plans or components owned by a plugin and that depend on elements in the plugin, are included in a bundle jar, the plans or components might not function after the import operation, unless all elements on which they depend are also imported. By default, therefore, search criteria in bundle templates exclude entities that are contained in plugins.

Folder paths for plans or components in the bundle jar cannot be owned by a plugin that is already imported on the master server. Best practice is not to include versions when referring to subplans, subcomponents and targeters, because subplans, subcomponents and targeters may not work reliably after import in different environments.

Only one import operation is permitted for a master server at any time.

Example 5–8 Using the bdb.b.imp Command to Validate the Import of a Bundle Jar

This example shows how to use the bdb.b.imp command with the -v option to test if the import of a bundle jar would be successful. The jar path is input as /bb/bb/bundle.jar

bdb.b.imp -v true -owner NM:myGroup -path "/bb/bb/bundle.jar"

The result is as follows.

Processed:Folder=1, Plan=1

The output shows that the operation would be successful.

Example 5–9 Using the bdb.b.imp Command to Import a Bundle Jar

This example shows how to use the bdb.b.imp command to import a bundle jar. The jar path is input as /bb/bb/bundle.jar

bdb.b.imp -v false -owner NM:myGroup -path "/bb/bb/bundle.jar"

The result is as follows.

Processed:Folder=1, Plan=1

The output shows that the import operation was successful.

Contents of a Bundle Jar

The contents of a bundle jar are described in an XML descriptor file, located in the top level directory of the bundle jar file. The rest of the jar file is composed of XML representations of the entities that were the result of bundle template's search criteria.

The XML descriptor file is enclosed in the <bundle> element. The <bundle> element is a new element for this release, and is not described in the XML Schema Guide.

You can manually create a bundle jar, or modify it after it has been automatically created by the system. This is on the condition that the jar contents are always consistent with the bundle descriptor file.

Attributes of the <bundle> Element

The <bundle> element has the following attributes.

Child Elements of the <bundle> element

The <bundle> element has the following child element.

memberList: List of member objects to create as part of the bundle. These member objects can include 1 or more objects of:

• folder

• hostType

• hostSet

• hostSearch

• component

• plan

Child Elements of the <memberList> Element

The <memberList> element has the following child elements:

• <folder>

• <hostType>

• <hostSet>

• <hostSearch>

• <component>

• <plan>

<folder> Element

The <folder> element is a child of the <memberList>element. It is used to declare a folder to be referenced by the bundle. The owner of these folders is the group you choose when importing.

Attributes of the <folder> Element

The <folder> element has two attributes:

• name – The name of the folder to be referenced by the bundle jar.

• description – The optional description of the folder. Default is none.

<hostType> Element

The <hostType> element is a child of the <memberList>element. It is used to declare a hostType to be referenced by the bundle.

Attributes of the <hostType> Element

The <hostType> element has two attributes:

• name – The name of the hostType to be referenced by the bundle jar.

• description – The optional description of the hostType. Default is no description.

<varList> Element

The <hostType> element contains an optional <varList> child element. The <varList> element specifies a list of variables to be added to the <hostType> element and later used by hosts in configuration.

The <varlist> element contains one or more <var> child elements. The <var> element provides <hostType> element variable declaration through two required attributes:

• name – The name of the variable

• default – The default value of the variable

<hostSet> Element

The <hostSet> element is a child of the <memberList> element and is used to declare a host set to be referenced by the bundle. The <hostSet> element cannot contain hosts, since bundles cannot define hosts.

The <hostSet> element contains two optional child elements:

• <hostSetRef>

• <hostSearchRef>

Attributes for the <hostSet> Element

The <hostSet> element has two attributes:

• name – The name of the host set.

• description – An optional description of the host set

<hostSetRef> Element

The <hostSetRef> element is a child of the <hostSet> element. It specifies a sub-host set. This host set must have been previously defined either in this bundle or in the master server on which the bundle is being imported.

Attributes for the <hostSetRef> Element

The <hostSetRef> element has one attribute, name. This attribute provides the name of the host set reference.

<hostSearchRef> Element

The <hostSearchRef> element is a child of the <hostSet> element. It specifies a sub-host search. This host search must have been previously defined either in this bundle or in the master server on which the bundle is being imported.

Attributes for the <hostSearchRef> Element

The <hostSearchRef> element has one attribute, name. This attribute provides the name of the host search reference.

<hostSearch> Element

The bundle <hostSearch> element is a child of the <memberList> element and is used to declare a host search to be referenced by the bundle.

The <hostSearch> element contains at least one of the following child elements:

• <criteriaList>

• <appTypeCriteria>

• <physicalCriteria>

Although the <criteriaList>, <appTypeCriteria>, and <physicalCriteria> elements are each optional, one of the three must be provided.

Attributes for the <hostSearch> Element

The <hostSearch> element has two attributes:

• name – The name of the host search.

• description – An optional description of the host search. The default is no description.

<criteriaList> Element

The <criteriaList> element is a child of the <hostSearch> element. It specifies a list of criteria to be added to the <hostSearch> element. The <criteriaList> element must be specified if <appTypeCriteria> and <physicalCriteria> are not specified.

The <criteriaList> element contains one or more <criteria> elements. The <criteria> element specifies a search criteria, including name, match type, and pattern.

Attributes for the <criteria> Element

The <criteria> element has three attributes:

• name – The name of the host variable to match.

• pattern – The pattern to match.

• match – The match type of the criteria. Valid values are EQUALS or CONTAINS. The default is EQUALS.

<appTypeCriteria> Element

The <appTypeCriteria> element is a child of the <hostSearch> element. It specifies a list of application type criteria to be added to the <hostSearch> element. The arguments of the <appTypeCriteria> element are expressed as attributes, and order is not important. If all values are false or the element is empty or unspecified, the search disregards this criteria when performing the search. The <appTypeCriteria> element must be specified if <criteriaList> and <physicalCriteria> are not.

Attributes for the <appTypeCriteria> Element

The <appTypeCriteria> element has three optional attributes:

• ms – If true, match MasterServer application type in host search. The default is false.

• ld – If true, match LocalDistributor application type in host search. The default is false.

• ra – If true, match RemoteAgent application type in host search. The default is false.

<physicalCriteria> Element

The <physicalCriteria> element is a child of the <hostSearch> element. It specifies a list of physical type criteria to be added to the <hostSearch> element. The arguments of the <physicalCriteria> element are expressed as attributes, and order is not important. If all values are false or the element is empty or unspecified, the search disregards this criteria when performing the search. The <physicalCriteria> element must be specified if <criteriaList> and <appTypeCriteria> are not.

Attributes for the <physicalCriteria> Element

The <physicalCriteria> element has two optional attributes:

• physical – If true, match physical host types in host search. The default is false.

• virtual – If true, match virtual host types in host search. The default is false.

<component> Element

The <component> element is a child of the <memberList> element and is used to declare a component in the bundle jar. All objects referenced by this component must have been previously defined either in this bundle or on the master server on which the bundle is being imported.

The <component> element contains three optional child elements:

• <systemService>

• <componentType>

• <resource>

Attributes for the <component> Element

The <component> element has two attributes:

• jarPath – The location of the component XML file, relative to the root of the bundle jar (leading / or . characters are not permitted). The format of the component XML is specified by the Plan and Component Language specification. See Chapter 3, Component Schema, in Sun N1 Service Provisioning System 5.2 XML Schema Reference Guide for more information.

• majorVersion – An optional attribute that determines whether to check in the component as a new major version. The default is false.

<systemService> Element

The <systemService> element is a child of the <component> element and is used to declare a system service backed by the containing component. This element may not be used with the <componentType> element. When the <systemService> element is used in a <component> element, a component is loaded and a <systemServiceRef> that references that component is created.

Attributes for the <systemService> Element

The <systemService> element has two attributes:

• name – The name of the system service

• description – An optional description of the system service

<componentType> Element

The <componentType> element is a child of the <component> element and is used to declare a component type backed by the containing component. The <componentType> element may not be used with the <systemService> element. When the <componentType> element used in a <component> element, a component is loaded and a component type that is backed by that component is created.

Attributes for the <componentType> Element

The <componentType> element has five attributes:

• name – The name of the component type.

  A name has a maximum of 64 characters. The name must start with a letter or underscore, followed by any number of letters, digits, or special characters, such as underscore (_), period (.), plus (+), minus (-), and space ( ). Unicode letters and digits are permitted.

• description – An optional description of the component type.

• group – The group name of the component type.

• order – A number that identifies where to put this component type.

• indentLevel – A number between 0 and 10 that identifies the level to which to indent this component type in a hierarchy of component types.

<resource> Element

The <resource> element is a child of the <component> element. It specifies a resource file name and location in the jar. A resource is always checked in as a either a file-typed or a directory-typed resource. The component that contains the <resource> element must be a simple component whose <resourceRef> element refers to the resource created by the <resource> element. No component variables are automatically added to the component that contains the <resource> element, regardless of the value of the config attribute.

Attributes for the <resource> Element

The <resource> element has three attributes:

• jarPath – The location of the resource file, relative to the root of the bundle jar. Leading / or . characters are not permitted. For directory-type resources, this path is assumed to be a directory, and is expected to end with a /. Everything in this directory defines the contents of this resource.

• majorVersion – An optional attribute that determines whether to check in the resource as a new major version. The default is false.

• name – An optional attribute that is the name of the resource. If not specified, the name will default to the absolute jarPath, which is converted to absolute if specified as relative.

• config – An optional attribute that specifies whether this resource is a configuration template.The default is false.

• type – An optional attribute that specifies whether the resource is a file or a directory. Use FILE for a file resource. Use DIRECTORY for a directory resource. If omitted, the default is FILE.

• checkInMode – An optional attribute that specifies whether a directory-type resource should be replaced or appended. Use REPLACE if the check in of this resource should replace an existing version. Use ADD_TO if the check in should add to the resource. The default is REPLACE. This attribute only applies to a resource that has a type of DIRECTORY.

• descriptorPath – An optional attribute that specifies the path to a resource descriptor file, relative to the root of the bundle jar. Leading / or . characters are not permitted. The format of the resource descriptor file follows the Resource Descriptor schema, as described in Chapter 5, Resource Descriptor Schema, in Sun N1 Service Provisioning System 5.2 XML Schema Reference Guide.

  If no resource descriptor file is specified, permissions information is used from the default file system settings of the master server. In this case, owner and group are not stored. This is also the case for settings that are omitted from a descriptor (either no entry or a partial entry for a file within the resource).

<plan> Element

The <plan> element is a child of the <memberList> element and is used to declare a plan in the bundle jar. All objects referenced by this plan must have been previously defined either in this bundle or on the master server on which the bundle is being imported.

Attributes for the <plan> Element

The <plan> element has two attributes:

• jarPath – The location of the plan XML, relative to the root of the bundle jar. Leading / or . characters are not permitted. The format of the plan XML is specified by the Plan and Component Language specification. See Chapter 4, Plan Schema, in Sun N1 Service Provisioning System 5.2 XML Schema Reference Guide for more information.

• majorVersion – An optional attribute that determines whether to check in the plan as a new major version. The default is false.