Sun N1 Service Provisioning System 5.2 Plug-in Development Guide

Plug-In Packaging

A plug-in is packaged as a Java Archive (JAR) file. The contents and instructions for interpreting the contents of the JAR file are contained in an optionally signed plugin-descriptor.xml file located in the top-level directory of the JAR file. The syntax of the plug-in descriptor is specified using XML Schema as per the May 2, 2001 W3C Recommendation (http://www.w3.org/TR/2001/xmlschema-0-20010502/). The schema can be used in conjunction with a development IDE, such as Sun Studio^TM or NetBeans, to determine the syntactical validity of a plug-in descriptor file.

Recommended Naming

To avoid potential conflicts, you should use a Java package naming convention for plug-ins (com.companyname.productname, for example, com.sun.solaris). Any objects that can be in a folder should be placed in a folder directory structure that mirrors the plug-in name, such as /com/sun/solaris. The plug-in JAR file name should use the convention pluginname_version.jar, for example com.sun.solaris_1.1.jar.

Installation Considerations

To install a plug-in, service provisioning administrators load the plug-in JAR file. Plug-ins can be imported into the N1 SPS environment through both the browser interface or the command-line interface. When you import a plug-in, the plug-in descriptor file and the contents of the plug-in are validated. Any errors with the import operation are highlighted in the browser interface.

For more information about how to import a plug-in, see Sun N1 Service Provisioning System 5.2 System Administration Guide.

Plug-In Upgrade Considerations

To upgrade from an existing version of a plug-in to a newer version of a plug-in, you provide a patch JAR file that contains only the contents needed for the patch . For example, if you only changed two component types between version 1.2 and version 1.3, then your upgrade patch would contain only those new component type XML files. Define your patch so that it can be applied in series to upgrade multiple versions . For example, to upgrade from version 1.0 to version 1.2, a user would first apply the upgrade from 1.0 to 1.1, then apply the upgrade from version 1.1 to version 1.2. Update patches are strictly additive with respect to the previously loaded version of the plug-in. You can also create a patch that would upgrade from a specific existing version (for example, 1.0) to a specific newer version (for example, 1.3). However, you cannot create a patch to upgrade from any arbitrary version to a higher version.

Uninstalling Plug-Ins

To uninstall a plug-in, you must perform the following tasks.

Uninstall all the components of the plug-in
Uninstall all the system services that are installed on target hosts as a part of the plug-in deployment
Delete from the Master Server component repository all component instances, including hidden instances, that were created from the plug-in component types

For more information about how to uninstall a plug-in, see Sun N1 Service Provisioning System 5.2 System Administration Guide.

Uninstalling Plug-In Versions

You cannot uninstall an individual patch of a plug-in, and you cannot delete objects created by previous versions of a plug-in. To remove this content, you would need to uninstall the current version of the plug-in and reinstall the older version of the plug-in. Alternatively, you could create an anti-patch that would install the old plug-in version's code while creating new versions of the plug-in defined objects.

Component Versions and Dependencies

Objects that are defined by a plug-in are loaded at installation time in the order in which they are defined in the plug-in descriptor file. These objects may only reference other objects that were defined either earlier in the plug-in or in a plug-in on which the defining plug-in directly depends. Any dependencies must be declared in the plug-in descriptor file.

Versioning Considerations

The N1 SPS software enables you to capture versions of plans and components. When you modify the plans and components in your plug-in and check these objects in to your N1 SPS environment, the objects are assigned a new version number. As a part of your plug-in deployments, you can choose to use the most current version of the plug-in plans and components, or previous versions.

If a plug-in attempts to create a versioned object that matches a same typed and named object existing in the system, a new version of the object is created. The minor version of this object is incremented unless the plug-in definition explicitly defines the object as requiring a major version increment.

To avoid naming conflicts, a plug-in cannot locate versioned objects, such as components and plans, into directories that were created by other plug-ins.

The following objects are not versioned.

Component types
System services
Host types
Host searches
Host sets

If a plug-in attempts to create a non-versioned object that matches a same typed and named existing object, the plug-in name is prepended to the name of the object to avoid naming conflicts.

Certificates

If the plug-in descriptor file is signed for one version of a plug-in, then the file must be signed for any subsequent versions of that plug-in. Use the standard jarsigner tool to sign the plug-in descriptor file. If the file is signed, the signature will be verified against the public certificate when the plug-in is installed. When upgrading a plug-in, the certificate used to sign the newer version is matched against the certificate used to sign the existing version in the system. The upgrade will not succeed if certificates have expired between plug-in versions.

You should sign all entries in the plug-in JAR (not just the plug-in descriptor file) with the same certificate. Only a single certificate may be attached to each entry.

Security Considerations

A plug-in does not include facilities for defining groups or permissions. This is because permission management depends highly on the environment into which the plug-in is loaded, and cannot be effectively modeled for all environments.

The administrator who adds the plug-in must decide what permissions are appropriate. The general expectation is that plug-ins are designed to be used by everyone. However, certain clients may wish to limit the use of a plug-in to a certain group. Plug-ins may also have certain folders that are meant to have different execution permissions.

Plug-In Display in the Browser Interface

The N1 SPS provisioning software controls the display order of plug-ins in the browser interface. You cannot control the display order of your plug-in in the plug-in definition.

Plug-In `readme.txt` File

You should provide a readme.txt file with your plug-in. The plug-in readme.txt file is intended as the holding place for instructions on configuring the system for a plug-in, as well as any copyright notice that applies to the plug-in. In general, the readme.txt file should document the permissions, session variables, and other instance-specific settings required for the plug-in to function. Specifically, the readme.txt should contain instructions for setting permissions on plug-in created folders, as well as enumerating expected session variables, their descriptions and encryption methods.