Chapter 5 Components

This chapter discusses the Component object model. It describes the basic concepts of components, the approaches for modeling components, the component schema (the system of XML tags) that the N1 Service Provisioning System software uses for modeling components, and CLI commands that can be used to manage components.

This section discusses the following topics:

• Working with Components

• Working with Component Types

• General Purpose Extended Control Services

Working with Components

Basic Concepts for Components

A Component is a logical grouping of source information (file(s) and/or directory structures or other components) that define an application and a set of instructions specifying how to handle the source information. A component can be a collection of files and directories, an autonomous archive such as a J2EE Enterprise Archive (EAR) or a COM component, a complete application such as BEA WebLogic, or an operating system-level update such as a patch or service pack. Components can also reference other components.

N1 Service Provisioning System software makes components more manageable by:

• Creating component models that include a carefully defined group of software resources for each component, along with information about how the component should be installed, configured, and analyzed

• Storing components in a repository with version control, so that you can retrieve any previous version of a component

• Making components available to plans, which perform data center operations in a step-by-step manner, taking advantage of the knowledge embedded in each component model

• Enabling components to be compared to one another as well as to installations of software

For an overview of how the N1 Service Provisioning System software manages components and plans, please see The N1 Service Provisioning System Software Object Model.

Modeling Components

The N1 Service Provisioning System software offers great flexibility in modeling components. Depending on the application that you are modeling, you may choose to use any of the following approaches:

• Fully automated modeling

• Extending built-in resource types with XML authoring

• Authoring component models in XML

Fully Automated Modeling

You can check in a component from a gold server or source code control system, have the provisioning software automatically generate a component model, and then use the component model for installation, configuration, and comparison procedures. You can do all this without ever viewing or editing the XML contents of the component model yourself.

We recommend this approach for modeling components in the Windows environment. The provisioning software's built-in resource types can be used to automatically model the most common resources that make up Windows application components. The resource type templates even include built-in procedures for basic operations such as installations, so that you can perform basic operations on common types of resources without even writing a plan.

For a complete list of resource types, see Built-in Components Types.

Extending Built-in Resource Types with XML Authoring

You can begin with an automatically generated component model, as described above, and then customize the component model by editing XML. You can edit a component model's XML by using the Advanced Edit feature on the component's Component > Details page. You can also edit the XML by downloading it to your local system and editing it with an XML-schema-validating editor, such as Turbo XML.

Editing XML enables you to:

• Customize the component with additional variables

• Add calls to extended control services, such as starting and stopping IIS or Windows services

Authoring Component Models in XML

You can write a component model from scratch, using an XML editor and the component schema described in this chapter. Note, though, that you still have to check the component's XML file and the component's resources into the repository in order for the model to be useful.

Overview of Modeling Components

Table 5–1 provides an overview of the steps for modeling components through the HTML user interface and through the CLI. These steps are described in further detail in the Procedures section of this chapter.

Building a Component

A key in creating a useful component is building the component.

Building a component selects specific versions of specific resources for use in the component. It assigns a version number to the component, and ensures that version of the component is always associated with specific versions of the component's resources.

Components consist of the following attributes.

• Path - A user definable location to store components. Between the many built-in components and the ones you create, the number of components can become extremely large making it difficult to locate the one you want. To help locating and using components easier, the provisioning software allows you to organize them in a hierarchical filing system.

• Component - (Name) A user definable text string that identifies the component. In some pages the component (name) will include the associated path such as in the Component Details page. In other pages such as the Components page it does not.

• Type - A user definable name for an object (Component Type) that serves as a service that manages the acquisition and deployment of source objects such as files directories, and configurations. The component type object is just another component that is used to control how to handle source information.

  The N1 Service Provisioning System software comes with a large number of component types that support WebLogic and Windows, UNIX, and some generic models.

• Version - The provisioning software manages version control by assigning a new version number each time a component is modified. This version number has a major number—the number to the left of the decimal point—and a minor number—the number to the right of the decimal point. You have the option of incrementing the minor number or the major number.

• Platform - Specifies which operating system(s) are valid for hosts that are targets for deployment.

• Checked in - The date and time the component was checked in. When a component is checked in it time and date stamps the component.

• Checked in by - The provisioning software provides an audit trail by storing the user ID of the person checking in the component.

• Label - A user definable text string that is used to categorize or group components. Labels can be used as sorting criteria on the component page.

• Category - A user definable object that is used to filter the component list. Categories are created using the categories page accessed from the Administrative page. Categories are then applied to a component from the Components page. Categories can also be created by clicking in the “Apply Categories . . .” link. at the bottom of the components page.

• Description - An optional user defined text string that describes the component object. This attribute is not used by the provisioning software but can provide meaningful information to the user. The better a description is the more useful it is for the user.

• Source - Identifies where the component source information came from including the path. This may be an object to be deployed (simple component), other components consisting (composite component) each consisting of other components or of an object to be deployed.

• Component Variables - User definable containers that store values required to deploy a component resource. For more information on component variables see Component Variables.

• Procedures - A set of instructions that tells what to with the resources and variables.

• Hidden - A flag that marks a component for exclusion from lists. Hidden components are not included in lists unless specifically requests.

If you're using the HTML user interface to define a component, saving the component automatically builds it.

Once a component has been built, it is ready to be deployed at which point you can either:

• install the component on a single set of hosts, using the HTML user interface to directly run the install procedure

• write a plan to install the component on several sets of target hosts

Plans are described in Chapter 6, Plans.

Procedures

Component procedures contain the logic for how to install, uninstall, and control a component. A given component can define any number of procedures. For example, it can define more than one way to install or uninstall a component. An example of a control procedure might be some logic for starting and stopping a server.

The only way to add install, uninstall, and control procedures is through the advanced edit feature in the HTML user interface or through the XML check-in process using the CLI.

When you create a composite component, by default it will inherit a default install procedure and a default uninstall procedure. In general, components often inherit their procedures from their component type. For more details on inheritance see Component Inheritance.

Component Inheritance

Inheritance the characteristic of getting certain attributes from something else. For example, when a component is created, by default, it gets or inherits variables, snapshots, and/or procedures from its component type.

This makes the component model much more powerful and flexible. For example, if you have a thousand components that all extend the IIS Application Component Type and you need to add additional functionality to these components you do not need to add it a thousand times, you only need to add it to the base component type that all these components extend. All one thousand components will inherit the change from the component type.

Access Modes and Modifiers

Access modes and modifiers control how a component attributes can be used and by whom or what. Access modes and modifiers can effect contained components, component variables, procedures, and source data.

There are basically four access modes, public, private, path, and protected. While some access mode apply to all of the attributes others do not. There are two modifiers final and abstract.

Both the concept of inheritance and the access modes and modifiers function like their Java language counterparts. To understand either of these more fully, please refer to the "Plan and Component Language Specification" as well as the any books that explain these concepts for Java.

Component Access Modes and Modifiers

The access attribute for a component controls how a component can be deployed. There are two modes, path and public. If access is set to path, then the component can only be referenced by other components in the same path and cannot be directly installed by the user. If access is set to public, then no such restrictions apply. A component can be referenced by any other component regardless of its path and it can be deployed directly by a user. The default access mode for a component is public.

The modifiers, abstract and final, for a component effect deployment options. If the modifier is set to abstract then the component may not be installed. It serves only as a base component for other components to extend. Only abstract components may declare abstract child elements. If the modifier is set to final then the component may not be extended by another component. If the modifier is omitted, then the component may be extended and installed.

Component Variable Access Modes and Modifiers

The access attribute for a component variable controls what can access the variable. There are four access modes, public, private, path, and protected. If the access mode is set to public, then access to the variable is not restricted in any way. If the access mode is set to protected, then access to the variable is restricted to derived components and entities in the same path. If the access mode is set to path, then access to the variable is restricted to entities in the same path. If the access mode is set to private, then access to the variable is restricted to the component containing the variable. The default access mode for a component is public.

The modifiers, abstract and final, for a component variable effect the default values and overrides for a component variable. If the modifier is set to abstract then the variable default attribute is omitted and must be specified by non-abstract derived components. Variables can only be declared abstract if the component is also declared abstract. Abstract variables may not be private. Non-abstract variables must declare a default value. If the modifier is set to final then the variable may not be overridden by derived components. If the modifier is omitted, then derived components can choose whether or not to override the variable.

Component Source Access Modes and Modifiers

The access attribute for a component source is not supported and therefore is implied to be public.

The modifiers, abstract and final, for a component source effect the overrides for the component source location. If the modifier is set to abstract then the source location is omitted and must be specified by non-abstract derived components. The source location for a component can only be declared abstract if the component is also declared abstract. If the source location is declared non-abstract then the source location must be specified. If the modifier is set to final then the source location may not be overridden by derived components. If the modifier is omitted, then derived components can choose whether or not to override the location for the source data.

The Component Schema

The <component> Tag

The <component> tag is the basic tag for defining a component. The <component> names the component, specifies its version number, and includes optional information such as the software vendor that create the application modeled by the component.

Other Component Tags

Within the opening <component> tag and the closing </component> tag in the component's XML file are a number of other tags that define:

• the list of resources that make up the component

• what to install (by default, all the resources) in the component

• what to remove when un-installing the component (by default, all the resources that were installed)

By editing the XML definition of the component, you can add other tags that define:

• configuration variables for the component

• additional procedures that can be called to manage the component

• content that should be included or excluded when the component is analyzed

  <component attributes> component_contents </component>

Table 5–2 describes the XML tags that you can use to modify or extend a component.

For details about each of these tags, please see N1 Service Provisioning System 4.1 Reference Guide.

Component Variables

Components support the use of variables, which are user definable containers that store values used during deployment. The purpose of component variables is to make parts of the component accessible and configurable external to the component. For example, a component may have a variable named installPath that is overridden on a per host basis that defines where to install each component.

The value of the component variable can be a reference to other component variables, including variables that are defined by the component's container. When a nested component is added to a container component, the HTML user interface verifies that the referenced variable is defined within the container. If the variable is not defined within the container component, the HTML user interface automatically adds the referenced variable to the container's variable list. As an example, it is typical for simple components to define their installPath variable to have the value of the container component's installPath variable. In this example, the syntax of the referenced variable is :[container:installPath]. For more information on variable substitution, see Chapter 16, Configuration Generation in N1 Service Provisioning System 4.1 Reference Guide.

Component variables are evaluated and assigned a value at the time the component is deployed. They can be used to define host names, IP addresses, paths, or any other piece of information that is required to implement a deployment.

Variable Sets

A variable set is a list of component variables with alternate values for one or more of the variables overriding their default value. This allows the user to specify different values for component variables based on which variable set is used.

An example of using a variable set is when a component is deployed into different environments such as a production environment and a development environment. If the variables defined in a component allow for the differences between both environments then you can use different variable sets based on where the component will be installed. At plan run time, the user simply chooses which variable set to use based on which environment the component will to be installed.

Variable Overrides

Variable overrides only pertain to composite components and are not used with simple components.

When a component contains other components (children components), a variable set only effects the top-level parent component. All children components use the default values for their variables.

The way to override the defaults values for children components is to set the variable override variables when creating a component that contains children components. Each referenced component will have a set of variable overrides that you can use.

Component Reports

The N1 Service Provisioning System software provides a number of lists that provide useful information about components. It is possible to list all the places where a specific component has been installed, the resources included in a specific component, all the versions of a specific component (the component's version history).

The Components User Interface

The Components Page

The Components page allows you to list components, view component details, create components, and edit components. This page also contains controls for filtering the component list and selecting sort criteria. You can change the sort criteria for the components list by clicking on one of the sort arrows in the header area. Click either the ascending or descending arrow selects that column for sorting and the sort order.

Path

Allows you to specify where to look for or store components. Click on change path to specify a different path.

Show

Allows you to list either components or plans. If you select plans the HTML user interface displays the plans page as though you had click on the plans option in the left-hand navigation menu.

You can also narrow the list by selecting a category from the category pull down menu.

(Check Box)

Marks a component for inclusion when one of the actions are clicked in the Actions for Checked components area. When clicked, Actions for Checked components will either delete, check in, or categorize a component.

Component

A user definable text string that names the component object. By default, the components are listed in alphabetical order by component name. You can sort the components list by the items in this column by clicking on one of the sort arrows in the header area for this column. Click either the ascending or descending arrow selects this column for sorting and the sort order.

Type

A user definable object that is used to control how to handle resources.

For more information on component types see Building a Component.

Version

Displays the revision number of the component. Each time a component is modified, its version number is incremented.

You can sort the components list by the items in this column by clicking on one of the sort arrows in the header area for this column. Click either the ascending or descending arrow selects this column for sorting and the sort order.

Label

A optional user definable text string that can be used to further group components together.

You can sort the components list by the items in this column by clicking on one of the sort arrows in the header area for this column. Click either the ascending or descending arrow selects this column for sorting and the sort order.

Description

An optional user defined text string that describes the component object. This attribute is not used by the provisioning software but can provide meaningful information to the user.

Action

Links that take you to other component related pages to either create a new component, view more information about a specific component, or edit components.

Actions for Checked Component

From this area you can either delete, check in, or apply categories to the checked components.

The Components Details Page

The Component Details page allows you to view Component information and attributes. This page is organized into several general informational and functional sections and also contains buttons that allow you to show where the component is uninstalled, delete the component, go to the Component Edit page, and download XML files.

General Information

This section of the Components Details Page displays general information about the component.

Component

The name of the component. By default, the components are listed in alphabetical order by component name. You can sort the components list by the items in this column by clicking on one of the sort arrows.

Type

The name of the component type.

A user definable object that is used to control how to handle resources.

For more information on component types see Building a Component.

Version

Displays the revision number of the component.

Platform

Displays the operating system(s) that are valid targets for component deployment.

Checked In

Displays the date and time when the component was checked in. That is, created or modified.

Checked In By

Displays the user ID of the one who checked in the component. That provides an audit trail when trying to troubleshoot problems or inconsistencies.

Label

A user definable text string that can be used to control the sorting on the components page.

Category

A user definable object that is used to filter the component list. Categories are created using the categories page accessed from the Administrative page. Categories are then applied to a component from the Components page. Categories can also be created by clicking in the “Apply Categories . . .” link.

Description

An optional user defined text string that describes the component object. This attribute is not used by the provisioning software but can provide meaningful information to the user.

File/Directory Information

This section only appears if the component type is a file and displays general information about the file. The directory section is identical to this one except that it is labeled directory.

File Name

This is a the text string that names the component type. This field is called Directory Name for a directory.

Time Stamp

The date and time the file or directory was created.

Total Size

The total amount of disk storage space required to store the file or directory.

User

This is the owner of the file or directory.

Group

This is the group relationship for this file or directory.

Permissions

This shows the Read, Write, and Execute permissions for the User, Group, and everyone else not in the first two categories. The first three characters represent the R (read), W (write), and X (execute) permissions for the user (owner). The second three characters represent the R (read), W (write), and X (execute) permissions for the group. The third set of three characters represent the permissions for everyone else who is not either the owner or part of the group.

Options

Displays the options that were checked when the component was created.

Referenced Components

This section of the Components Details Page displays components that are referenced by the parent component.

Resource [tree]

A user definable text string that names the component type that is a child of the parent component (resource object).

Type

This identifies the component type for the child component.

Version

Displays the revision number of the resource. Each time a resource definition is modified, its version number is incremented.

Source

Identifies the source path for the child component (resource).

Action

Allows you to either check in (define) a new resource for the component or select resources from a list of resources that already exist.

Component Variables

This section of the Components Details Page displays information about the component variables.

Variable

A user definable variable that can be used to customize deployments.

Value

A user specified value for the component variables.

Component Procedures

This section of the Components Details Page displays information about the component procedures.

Checkbox

Marks a procedure for inclusion in a plan.

Procedure

Lists the procedures defined in this component.

Actions

Generates a plan that incudes the checked

Buttons

This section of the Components Details Page displays information about the component procedures.

Edit

Takes you to the component edit page allowing you to change component information.

Advanced Edit

Takes you to the XML edit page allowing you to change component information and function at the code level.

Delete

Allows you to delete this component. If some other object references this component, the HTML user interface displays a message and will not allow you to delete the component.

Done

Takes you back to the components page.

Download

Allows you to export the component XML code to a text file.

Variable Settings

Allows you to override the default value of any variable.

Where Installed

Displays where the component has been installed.

The Components Edit Page

The Component Edit page allows you to change Component information and attributes. However, not all fields can be changed.

As with the details page, the edit page displays different fields depending on which component type is displayed. For example, the fields for a file are different from that of an IIS application. The following only discuss the fields that yo can change.

Also, as with the details page, the edit page is organized into the same several general informational and functional sections as the component details page. Each section will be discussed individually.

General Information

This is the first section of the Components Edit Page and displays general information about the component.

Component

Displays the name for the component object. This field was set when the component was created and cannot be changed.

Type

Displays the name for the component type. This field was set when the component was created and cannot be changed

Version

Displays the revision number of the component. Each time a component is modified, its version number is incremented. The version number cannot be changed by the user.

Platform

Allows you to change the operating system(s) that are valid targets for component deployment. This is done by selecting an item from the pull down menu.

Checked In

Displays the date and time when the component was checked in. This field is set by the provisioning software and cannot be change by the user.

Checked In By

Displays the user ID of the one who checked in the component. This field is controlled by the provisioning software and cannot be change by the user.

Label

A text field that allows you to enter or change the label.

Category

Displays the component category. This field was set when the component was created and cannot be changed.

Description

A text field that allows you to enter or change the component description.

File/Directory Information

This section only appears if the component type is a file and displays general information about the file. The directory section is identical to this one except that it is labeled directory. None of these fields are changeable.

Resources Included

This section of the Components Edit Page displays information about the component's resources. Some fields can be changed and some cannot.

Resource [tree]

Displays the path to the resource component.

Type

Allows you to change the resource component type by selecting a new type form the pull down menu.

Version

Displays the revision number of the resource. This field is controlled by the provisioning software and cannot be changed by the user.

Source

Identifies the source for the resource.

Action

Allows you to either check in (define) a new resource for the component or select resources from a list of resources that already exist.

(Check Box)

Marks a resource for inclusion when one of the actions are clicked in the Actions for Checked Resources area. When clicked, Actions for Checked Resources will either check in, delete, move up or down and resource, or set the resource version to the most recent one.

Component Variables

This section of the Components Edit Page displays information about the component's variables.

Variable

This field allows the user to create new variables. This column also lists existing variables.

Value

This field allows the user to set the value for new variables. This column also lists the value for all existing variables.

(Check Box)

Marks a component variable for inclusion when one of the actions are clicked in the Actions for Checked Variables area. When clicked, Actions for Checked Variables will either move up, move down, or delete variable.

Buttons

This section of the Components Details Page displays information about the component procedures.

Check in

Checks in the changed version of the component and increments the revision number.

Check in as

Checks in the changed version of the component using a different name and sets the appropriate revision number.

Cancel

Takes you to the components details page without saving any changes.

How To View Components List

Step

1. In the left-hand navigation menu, click components.

   The HTML user interface displays the components page, which lists the components already checked in to the database.

How To View Components Details

Steps

1. In the left-hand navigation menu, click components.

   The HTML user interface displays the components page, which lists the components already checked in to the database.

2. Find the row listing the component you're interested in, and click details.

   The HTML user interface displays a Components Details page for the component.

How To View A Component's Installations

Steps

1. In the left-hand navigation menu, click components.

   The HTML user interface displays the components page, which lists the components already checked in to the database.

2. Find the row listing the component you're interested in, and click where installed.

   The HTML user interface displays a Components Where Installed page for the component.

How To Create Components

Steps

1. In the left-hand navigation menu, click components.

   The HTML user interface displays the components page, which lists the components already checked in to the database.

2. In the top row of the table listing components, enter a name in the component field for the new component, and click create.

   The HTML user interface displays the Components Details Edit page for the new component. This page is slightly different from the component edit page discussed earlier in that the name and type can be changed here.

3. Use the controls on this page to specify the necessary information that will make up the component.

   • Change the name in the component field, if desired. Once the component is checked in you will not be able to change the name.

   • Select the type from the pull down menu. The component edit page fields will change to match those relevant to the component type selected.

   • Select the platform from the pull down menu.

   • Enter a label in the Label field.

   • Enter a description in the Description field.

   • Continue entering the required information. The information required from here will depend on the component type selected.

   • When finished click check in.

   The HTML user interface displays a window reporting that it is checking in the component as version 1.0.

4. Click continue to check in to finish checking in the component.

How To Edit Components

Steps

1. In the left-hand navigation menu, click components.

   The HTML user interface displays the components page, which lists the components already checked in to the database.

2. Find the row listing the component you're interested in, and click details.

   The HTML user interface displays a Components Details page for the component.

3. Click the edit button.

   The HTML user interface displays a Components Details Edit page for the component.

4. Use the controls on the Components Edit page to modify the component's configuration.

5. When you have finished your modifications, click check in.

6. When you have finished listing all the resources for the component, click check in.

   The HTML user interface displays a window reporting that it is checking in the component as version nth which will be the next incremental number.

7. Click continue to check in to finish checking in the component.

Where to Find Information Reported by the N1 Service Provisioning System Software

The following table tells you how to find some of the information reported by provisioning software.

Summary of Component CLI Commands

The cdb.c commands provide general-purpose controls for managing components.

The cdb.ic commands retrieve information about components that are already installed on hosts.

The cdb.vs commands manage variable settings for components.

Working with Component Types

Introduction

A Component Type is a user definable object that is used to control how to handle source items referenced by a component. The component type object is actually another component that manages the acquisition and deployment of source items such as files, directories, and configurations.

All components must have its component type attribute set to some component type. Even if a component does not have a defined component type, its component type is set to untyped.

The files, directories, and other tree structures referenced by a simple component is managed as a discrete unit within a component. For example, an IIS application, which the provisioning software would manage as referenced source items might include the following:

• a directory of content

• IIS Web site settings

• COM+ application

• Windows Registry settings

Some source items referenced by components, such as files and directories, can be easily copied from a gold server or data source. Others, such as IIS Web site settings or Windows registry entries, need to be intelligently extracted from a data source in order to be treated as an independent, manageable entity. With its built-in component types, the provisioning software can recognize the most common source items used for J2EE and Windows applications, and can intelligently and accurately extract data for use as a component source, store the component source in a repository, and install the source items correctly in its intended destination.

When a component contains a procedure, such as testing to verify that a web server is alive, the procedure is seen ion the procedures section of the components details page.

The provisioning software comes populated with a large number of commonly used component types. See Built-in Components Types for more information on built-in component types.

Checking In a Component Type

Checking in a resource means copying a specific piece of software from a specific location (such as a directory on a gold server) and entering it in the repository with a specific name, a version number, and a resource type.

A resource type identifies the format and in many cases the function of a resource. Examples of resource types are file, directory, IIS Web Site Settings, and COM+ Application. For a complete list, see Built-in Components Types.

The resource repository uses a hierarchical namespace. Within this namespace, individual resources are identified by their name, which must be unique, and their version number.

The CLI command cdb.rsrc.ci checks in a resource. When you check in a resource with cdb.rsrc.ci, you specify the location of the source of the resource (with the -src argument), the location (a hierarchical name) in the repository where you would like to store the resource (with the -dst argument), and the resource type (with the -type argument).

A resource may be used for more than one component. Checking in a resource with cdb.rsrc.ci does not associate the resource with any particular component.

Extended Control Services

Extended control services are procedures that perform a software operation related to a resource or component. For a description of general purpose control services, see General Purpose Extended Control Services.

Built-in Components Types

Built-in component types enable you to quickly model many of the most common WebLogic, Windows, and J2EE application components and to automatically associate install, uninstall, export, and snapshot behavior with a particular resource.

Component Type: File

Files represent an untyped single file taken from a target machine. The provisioning software deploys the files directly with no special post processing. Although files have a system component the functionality for installation, snapshot, and un-installation are built-in to the system and are not represented in the component XML.

Browsing

Extended Control Procedures

Component Type: Directory

Directories represent an untyped collection of files and folders taken from a target machine. Although Directories have a system component the functionality for installation, snapshot, and un-installation are built-in to the system and are not represented in the component XML.

Browsing

Extended Control Procedures

IIS Types Introduction

The following four IIS Types share a common implementation. All four export, Install, and delete data stored in the IIS metabase. As a result there are a common set of functions, formats, and errors.

Exported/Internal File Format

All four IIS types use an XML format to store their section of the metabase. The present XML format does not support metabase properties of type NTACL (such as AdminACL); if any are encountered while reading/writing to the metabase, they are ignored. Also, properties of type IPSec (such as IPSecurity) are written out as serialized objects, and as a result they are not human-readable (during either direct examination, or as difference results).

M-I Difference

During a snapshot the current state of the metabase is exported into an XML file. During an M-I difference the metabase is re-exported and compared against the original XML file. The standard XML differentiator is used to generate differences between these files.

Error Conditions

IIS Web Site or Virtual Directory Settings

Represents the settings for an IIS Website or Virtual Directory. Please note that this resource type only contains the settings for a website or virtual directory. The content on the web site must be checked in as a separate resource.

Browsing

Installation

Installation occurs by reading the XML file and importing into the target system metabase. If a web site with the same name exists it is overwritten. If there are multiple web sites with the same name on the system the first matching one will be removed and overwritten.

Special cases include untyped keys/nodes (see below for more info) and SSL certificates, which are not deployed. The relevant settings for SSL certs in IIS (SSLCertHash and SSLStoreName) are preserved during a deployment if they exist on the target, but if they do not exist they are not added.

To bring up a secure site after being deployed (or redeployed) requires a restart of IIS.

Un-Install

The entire web site is removed on the target system. All Virtual Directories underneath the web site are removed regardless of whether they were installed by the provisioning software. If the settings are just for a virtual directory only that directory is removed, not its containing site. Note the matching for uninstall is done via name, so the first web site with the same name found on the system will be uninstalled. Once this is complete the XML file used during installation is removed.

Component Type: IIS Global Filter Settings

Resource type is used to represent Global ISAPI filter settings. Please note that this resource type only contains the settings for a IIS Global Filter. The actual DLL implementing the filter must be installed separately.

Browsing

Installation

Installation occurs by reading the XML file and importing into the target system metabase. If a filter setting with the same name exists on the target machine it is overwritten.

Un-Install

The filter settings are removed on the target system then the XML file used during installation is removed.

Component Type: IIS Web Site Filter Settings

Please note that this resource type only contains the settings for a Web site Filter. The actual DLL implementing the filter must be installed separately.

Browsing

Installation

Installation occurs by reading the XML file and importing into the target system metabase. If a filter settings with the same name exists on the target machine it is overwritten.

Un-Install

The filter settings are removed on the target system metabase, then the XML file used during installation is removed.

Component Type: IIS Global Settings

Resource type is used to represent Global IIS Settings.

Browsing

Installation

Installation occurs by reading the XML file and importing into the target system metabase. The setting on the target system is overwritten if it exists.

Un-Install

Global settings cannot be uninstalled. Uninstalls will have no affect on the target system except to remove the *.XML file used during install.

Component Type: COM+ Application

Resource type is used to represent COM+ Applications. COM+ Applications are treated as a monolithic unit. The settings and content are installed as a group.

Browsing

Exported/Internal File Format

COM+ Applications are exported into a Windows Installer File (*.MSI) using the COM+ Admin SDK.

M-I Difference

The COM+ Application is re-exported on the target system as an MSI file and compared against the MSI file used to install the application. M-I diff will only indicate that there were differences (i.e. the two binary files are different) but will not indicate the details of the differences.

Installation

• If the COM+ Application with the same name is already installed on the target system and running as a service then it is stopped along with all of its running dependent services. The COM+ Application will then be deleted from the COM+ Catalog.

• The new COM+ Application is installed using the COM+ Admin SDK.

• To start the COM+ Application the user will have to use the startApplication call step to manually start the COM+ application.

Un-Install

The MSI used to install the COM+ Application is used to uninstall the COM+ Applications using the following command line:

msiexec /qn /x <path to msi file>

Once this is complete the msi file is removed from the target system.

Error Conditions

Extended Control Procedures

Component Type: COM Component

Resource type is used to represent COM components.

Browsing

Exported/Internal File Format

COM components are stored as a file in their native format.

M-I Difference

The COM component is compared as a binary file against the file used during installation. M-I diff will only indicate that there were differences (i.e. the two binary files are different) but will not indicate the details of the differences.

Installation

Regsvr32 is called to register the COM components in the dll using the following command line call:

regsvr32.exe /s <file path>    

Uninstall

Regsvr32 is called to unregister the COM components in the dll using the following command line call:

regsvr32.exe /s /u <file path>    

After the dll is unregistered it is removed from the target system.

Error Conditions

Component Type: Registry Keys

This resource type is used to represent registry keys and their associated values.

Browsing

Exported/Internal File Format

Registry keys are exported into an XML file.

M-I Difference

During a snapshot the current state of registry key (and its children) is exported into an XML file. During an M-I difference the registry key is re-exported and compared against the original XML file. The standard XML diff comparator is used to generate differences between these files.

Installation

The XML file representing the registry is read and imported into the target system using an execJava step. Any keys are values already existing in the target system is overwritten.

Un-Install

The execJava implementation will take the root of the exported key, and delete all keys and values beneath it. If the root is a value, it will be deleted.

Error Conditions

Component Type: Registry File

Registry files are generated by Regedit to represent exports to the metabase. *.reg files are in text format and specify the keys and values to add or remove from the registry.

Browsing

Exported/Internal File Format

COM components are stored as a file in their native text file format.

M-I Difference

M-I Differencing is not supported for *.reg files. Snapshots will not be taking during installation resulting in nothing to diff during the M-I diff. If the user would like to difference registry changes they are encouraged to use the built-in Registry keys type.

Installation

Regedit /s <file path> is called on the *.reg file to write its changes to the registry.

Un-Install

During uninstall only the *.reg file used during installation will be removed. The registry keys inside the reg file are unaffected. Users are encouraged to use the build-in Registry keys type to allow for registry un-installation.

Error Conditions

Component Type: Data Source Name

DSN Entries represent ODBC settings for connecting to a database. They can be edited by the user on the system by bringing up the “Data Source Administrator” control panel. The actual settings are stored in specific places in the registry. As a result, the Data source name Resource Type is built on top of the Registry keys resource type. The DSN Install, export, and uninstall directly use the facilities provided by the Registry Key resource handler. The DSN browser wraps the Registry browser to provide an experience closer to the “Data Source Administrator” control panel.

Browsing

Exported/Internal File Format

On export the browser will export the key containing all the DSN settings, as well as the value of the same name in the `ODBC Data Sources' key at the same level in the registry hierarchy.

Un-Install

The DSN uninstall is based on the registry uninstall with the caveat that the path being deleted is the key containing the DSN settings, but not the key the DSN GUI uses to display the available DSN settings. Special logic exists to delete this key as well. The semantics of this differ slightly from the registry uninstall semantics, though they use the same executor.

Error Conditions

The DSN system component directly calls the Install method of the registry system component. Please reference the Registry Key section of this document for further information on implementation and possible errors.

Component Type: Windows Installer File (*.msi)

Resource type used to represent Silent MSI files.

Browsing

Exported/Internal File Format

MSI files are stored as a file in their native format.

M-I Difference

M-I Differencing is not supported for Windows Installer files. Snapshots will not be taking during installation resulting in nothing to diff during the M-I diff. Since ROX does not have first-hand knowledge of the actions taken during the installer run it is not feasible to determine what needs to be captured.

Installation

The windows installer service is called on the msi file to import it into the target system with the following command:

misexec /qn /i <file path>   

Un-Install

The windows installer service uninstalls is called on the msi file used during installation to uninstall the package using the following command:

msiexec /qn /x <file path>   

After msiexec is called the msi file is removed.

Error Conditions

Component Type: Windows Batch File

Resource type used to represent *.bat and *.cmd files.

Browsing

Exported/Internal File Format

Windows batch files are stored as a file in their native text format.

M-I Difference

M-I Differencing is not supported for Windows Batch files. Snapshots are not taken during installation resulting in nothing to diff during the M-I diff.

Installation

The batch file is run during installation.

Un-Install

During uninstall the *.bat file is removed from the target system.

Error Conditions

Component Type: Windows Scripting Host Script

Windows scripting host (WSH) scripts are text files either vbscript (*.vbs) or jscript (*.js) or contained within an XML project file (*.wsf).

Browsing

Exported/Internal File Format

Stored as a file in their native text format.

M-I Difference

M-I Differencing is not supported for WSH files. Snapshots will not be taking during installation resulting in nothing to diff during the M-I diff.

Installation

The WSH script is run via cscript.exe as follows:

cscript <file path>   

Un-Install

During uninstall the script file is removed from the target host.

Error Conditions

Component Type: IIS Website (IIS Virtual Directory)

Browsing

Uses IIS Website Settings Browser.

Exported/Internal File Format

Composite Component: IIS Website/VDir Settings, IIS Virtual Directory Set, IIS Website Filter Set, Directory

Upon creation the contained entities (listed above) are created and linked to separately as appropriate.

Component Type: IIS Website Filter

Browsing

Uses IIS Website Filter Settings Browser.

Exported/Internal File Format

Composite Component: IIS Website Filter Settings, COM Object

Upon creation the contained entities (listed above) are created and linked to separately as appropriate.

Component Type: Symbolic Link

Browsing

Uses standard File Browser (with restricted export rules)

Exported/Internal File Format

Symlinks are an exception among simple component types in that they do not contain a resource. The data of a symlink is stored as a set of variables (one each for name and location) in the component.

Component Type: WebLogic WAR file

Browsing

Not directly browsable. Must be obtained through WebLogic web application browsers.

Exported/Internal File Format

This component has a dual nature. It can be either a .war archive, or the exploded version of that archive. Thus the file format is either an archive file in native format, or a package, respectively.

M-I Difference

Will use the standard file/directory MI diff approach.

Installation

Can not be directly installed. Must be installed as part of a WebLogic web application container. The file/directory is copied to the filesystem based on the install path, and then registered with the WL admin server.

Un-Install

Can not be directly uninstalled. The containing WebLogic web application container must be uninstalled, which will result in the removal of this file/dir.

Error Conditions

See Error Conditions.

Component Type: WebLogic web application settings

Browsing

Not directly browsable. Must be obtained through WebLogic web application browsers.

Exported/Internal File Format

On export the relevant settings for this webapp will be read from the admin server and stored as a custom config gen'd file.

M-I Difference

The relevant settings for the app. will be exported into a file, which will be compared to the file that contained the settings during deployment.

Installation

Can not be directly installed. Must be installed as part of a WebLogic web application container. Installation involves reading the post-configured file and applying all the settings to the admin server.

Un-Install

Can not be directly uninstalled. The containing WebLogic web application container must be uninstalled, which will result in the removal of this file and related settings of the webapp within WebLogic. Settings not specific to the webapp will not be removed.

Error Conditions

See Table 5–34.

Component Type: WebLogic Web Application

Browsing

Two browsers are supported. An admin server browser from which you can select one of the installed applications and its relevant settings, and a filesystem browser from which you can select the WAR file and a component without settings is created.

Admin Server Browser:

Filesystem Browser:

Exported/Internal File Format

Composite Component: WebLogic web application container

Installation

Must be targeted at a WL target (server/cluster) which will install the component on that target, and install the contained reg component on the admin server of the target.

Un-Install

Untargets the webapp from the target, and if not currently targeted elsewhere, removes the registration comp from the admin server.

Error Conditions

Component Type: WebLogic JAR file

Browsing

Not directly browsable. Must be obtained through WebLogic EJB browsers.

Exported/Internal File Format

This component has a dual nature. It can be either a.jar archive, or the exploded version of that archive. Thus the file format is either an archive file in native format, or a package, respectively.

M-I Difference

Will use the standard file/directory MI diff approach.

Installation

Can not be directly installed. Must be installed as part of a WebLogic EJB container. The file/directory is copied to the filesystem based on the install path, and then registered with the WL admin server.

Un-Install

Can not be directly uninstalled. The containing WebLogic EJB container must be uninstalled, which will result in the removal of this file/dir.

Error Conditions

See Component Type: WebLogic EJB.

Component Type: WebLogic EJB settings

Browsing

Not directly browsable. Must be obtained through WebLogic EJB browsers.

Exported/Internal File Format

On export the relevant settings for this EJB will be read from the admin server and stored as a custom config gen'd file.

M-I Difference

The relevant settings for the EJB will be exported into a file, which will be compared to the file that contained the settings during deployment.

Installation

Can not be directly installed. Must be installed as part of a WebLogic web application container.Installation involves reading the post-configured file and applying all the settings to the admin server.

Un-Install

Can not be directly uninstalled. The containing WebLogic web application container must be uninstalled, which will result in the removal of this file and related settings of the webapp within WebLogic. Settings not specific to the webapp will not be removed.

Error Conditions

See Component Type: WebLogic EJB

Component Type: WebLogic EJB container

Browsing

Not directly browsable. Must be obtained through WebLogic EJB browsers.

Exported/Internal File Format

Composite Component: WebLogic JAR file, WebLogic EJB container

Installation

Must be targeted at a WL Domain host. Installs the nested components, and registers the EJB with WebLogic. Can be installed as part of a retarget during installation of a WebLogic EJB.

Un-Install

Removes the EJB from WebLogic, then uninstalls the nested components.

Error Conditions

Component Type: WebLogic EJB

Browsing

Two browsers are supported. An admin server browser from which you can select one of the installed applications and its relevant settings, and a filesystem browser from which you can select the JAR file and a component without settings is created.

Admin Server Browser:

Filesystem Browser:

Composite Component: WebLogic EJB Container

Installation

Must be targeted at a WL target (server/cluster) which will install the component on that target, and install the contained reg component on the admin server of the target.

Un-Install

Untargets the EJB from the target, and if not currently targeted elsewhere, removes the registration comp from the admin server.

Error Conditions

Component Type: WebLogic EAR file

Browsing

Not directly browsable. Must be obtained through WebLogic enterprise application browsers.

Exported/Internal File Format

This component has a dual nature. It can be either a .EAR archive, or the exploded version of that archive. Thus the file format is either an archive file in native format, or a package, respectively.

M-I Difference

Will use the standard file/directory MI diff approach.

Installation

Can not be directly installed. Must be installed as part of a WebLogic enterprise application container. The file/directory is copied to the filesystem based on the install path, and then registered with the WL admin server.

Un-Install

Can not be directly uninstalled. The containing WebLogic EJB container must be uninstalled, which will result in the removal of this file/dir.

Error Conditions

See Table 5–34

Component Type: WebLogic enterprise application settings

Browsing

Not directly browsable. Must be obtained through WebLogic enterprise application browsers.

Exported/Internal File Format

On export the relevant settings for this app will be read from the admin server and stored as a custom config gen'd file.

M-I Difference

The relevant settings for the Application will be exported into a file, which will be compared to the file that contained the settings during deployment.

Installation

Can not be directly installed. Must be installed as part of a WebLogic enterprise application container. Installation involves reading the post-configured file and applying all the settings to the admin server.

Un-Install

Can not be directly uninstalled. The containing WebLogic enterprise application container must be uninstalled, which will result in the removal of this file and related settings of the webapp within WebLogic. Settings not specific to the webapp will not be removed.

Error Conditions

See Table 5–34

Component Type: WebLogic Enterprise Application Container

Browsing

Not directly browsable. Must be obtained through WebLogic enterprise application browsers.

Exported/Internal File Format

WebLogic EAR file, WebLogic enterprise application container, WebLogic List.

Installation

Must be targeted at a WL Domain host. Installs the nested components, and registers the Enterprise Application with WebLogic. Can be installed as part of a retarget during installation of a WebLogic enterprise application, or WebLogic Contained module.

Un-Install

Removes the Enterprise Application from WebLogic, then uninstalls the nested components.

Error Conditions

Component Type: WebLogic Enterprise Application

Browsing

Two browsers are supported. An admin server browser from which you can select one of the installed applications and its relevant settings, and a filesystem browser from which you can select the EAR file and a component without settings is created.

Admin Server Browser:

Filesystem Browser:

Exported/Internal File Format

Composite Component: WebLogic enterprise application container.

Installation

Must be targeted at a WL target (server/cluster) which will install the component on that target, and install the contained reg component on the admin server of the target.

Un-Install

Untargets the enterprise app from the target, and if not targeted elsewhere, removes the registration comp from the admin server.

Error Conditions

Component Type: WebLogic List

Browsing

Not directly browsable. Must be obtained through WebLogic enterprise application browsers.

Exported/Internal File Format

This component is a container component with some custom install/uninstall/snapshot blocks. In all other ways it is only a generic container component.

Installation

Does not support direct installation.

Un-Install

Does not support direct uninstallation.

Error Conditions

See contained WebLogic module types.

Component Type: Contained WebLogic web Application Container

Browsing

Not directly browsable. Must be obtained through WebLogic enterprise application browsers.

Exported/Internal File Format

Composite Component:

Contains a final WebLogic WAR file stub component, and a non-final, stub by default, WebLogic web application settings component.

Also contains a final compRef to the WebLogic enterprise application container component contained by the WebLogic enterprise application that contains the WebLogic List that contains this component.

Installation

Can be installed on a WL Domain host. Results in the installation of the WebLogic enterprise application container as well.

Un-Install

Uninstalls the WebLogic enterprise application container.

Error Conditions

Component Type: contained WebLogic web application

Same as WebLogic web application except it contains a final Contained WebLogic web application container.

Component Type: Contained WebLogic EJB Container

Browsing

Not directly browsable. Must be obtained through WebLogic enterprise application browsers.

Exported/Internal File Format

Composite Component:

Contains a final WebLogic JAR file stub component, and a non-final, stub by default, WebLogic web application settings component.

Also contains a final compRef to the WebLogic enterprise application container component contained by the WebLogic enterprise application that contains the WebLogic List that contains this component.

Installation

Can be installed on a WL Domain host. Results in the installation of the WebLogic enterprise application container as well.

Un-Install

Uninstalls the WebLogic enterprise application container.

Error Conditions

Component Type: Contained WebLogic EJB

Same as WebLogic EJB except it contains a final Contained WebLogic web application container.

System Components

In addition to the Component Types described above System Components also provide functionality available to advanced plan and component authors. The following components have additional functionality:

Windows System Service

The Windows System Component provides utilities for interacting with different windows systems, beyond those related to any specific component type described above.

Control Procedures

WebLogic Target

The WebLogic Target component provides utilities for interacting with WebLogic managed servers and clusters.

Procedures

Component Type User Interface

The component types user interface provides the functionality for users to manage component types. Users can check-in component types, view lists of all component types, view component type versions. Users can also view install information for component types such as which hosts a component is installed on and which plan installed the component.

The HTML User Interface also provides browsing of several component types. This allows for the selection of component types for remote check in.

The Component Type Page

The component type page allows you to list component types, view component type details, and create component types. This page also contains controls for filtering the component type list and selecting sort criteria. You can change the sort criteria for the component type list by clicking on one of the sort arrows in the header area. Click either the ascending or descending arrow selects that column for sorting and the sort order.

Component Types

A user definable text string that names the component object. By default, the components are listed in alphabetical order by component name. You can sort the component type list by its name by clicking on one of the sort arrows in the header area for this column. Click either the ascending or descending arrow selects this column for sorting and the sort order.

Menu Group

The component type menu is divided into several sections or groups. This field identifies which section or group within the pull down menu the component type belongs. Note: Other than the hidden menu group, this field is only used as a sort criteria and does not effect the menu list. Assigning a component type to the hidden menu group overrides the menu order causing the component type not to appear in the menu.

Menu Order

This field controls where in the component type menu a component type name appears. The provisioning software simply sorts the menu list in alpha numerical order based on this field. You can use both number and letters in this field. However, the provisioning software has only used numbers by convention. To help organize the data the provisioning software has also adopted the following numbering convention.

Assigning a component type a menu group of Any WebLogic does not effect where in the menu the component type will appear. However, by following the arbitrary convention set by the provisioning software, assigning a component type that belongs with the menu group of Any WebLogic the 000100-xxxxxx-xxxxxx will put it in the menu in the correct place.

Indent Level

This defines how many units of 2 spaces to the right the menu item will be indented.

Description

An optional user defined text string that describes the component object. This attribute is not used by the provisioning software application but can provide meaningful information to the user.

Defining Component

Displays the component that defines this component type.

Version

Displays the revision number of the component. Each time a component is modified, its version number is incremented.

You can sort the component type list by version number by clicking on one of the sort arrows in the header area for the column. Click either the ascending or descending arrow selects this column for sorting and the sort order.

Action

Links that take you to other component type related pages to either create a new component type, view more information about a specific component type, or edit component types.

The Component Type Details Page

The component types details page allows you to view Component types information and attributes. None of the fields can be changed on this page.

Component Type

Displays the name of the component type.

Menu Group

Displays the name of the menu group.

Menu Order

Displays 18 character code that controls where in the menu this component type is placed.

Indent Level

Displays how many spaces this menu item is indented.

Description

Displays the description of the component type.

Defining Component

Displays the component that defines this component type.

Version

Displays the version number for this component type.

Edit Button

A link that takes you to the component types edit page.

Done Button

A link that takes you to the component types page.

The New Component Type Edit Page

Working with Components shows the Component Edit page when creating a component. This edit page is different from the on used to edit existing components.

Component Type

Displays the name of the component type. This cannot be changed.

Menu Group

A text field that allows you to change the name of the menu group for this component type. Only predefined menu groups are allowed.

Menu Order

A text field that allows you to change the location in the menu for this component type. This field accepts any alpha or numeric character.

Indent Level

A text field that allows you to change the indentation on the menu for this component type. This field accepts number in the range of 0 through 10.

Description

A text field that allows you to change the description for this component type.

Defining Component

Displays the component that defines this component type.The View Component is a link that take you to the component details page for the defining component.

Save Button

Saves the contents of the edit page incrementing the version number.

Cancel Button

A link that takes you to the component types page.

How To View Component Types

Steps

1. In the left-hand navigation menu, click administrative.

   The HTML user interface displays the administrative page, which allows the user to select one of four administrative functions.

2. Click on the component types link on the administrative page.

   The HTML user interface displays a list of the component types.

How To View Component Types Details

Steps

1. In the left-hand navigation menu, click administrative.

   The HTML user interface displays the administrative page, which allows the user to select one of four administrative functions.

2. Click on the component types link on the administrative page.

   The HTML user interface displays a list of the component types.

3. Find the row listing the component type you're interested in, and click details.

   The HTML user interface displays a Components Types Details page for the component type.

How To Create Component Types

Steps

1. In the left-hand navigation menu, click administrative.

   The HTML user interface displays the administrative page, which allows the user to select one of four administrative functions.

2. Click on the component types link on the administrative page.

   The HTML user interface displays a list of the component types.

3. In the top row of the table listing components types, enter a name in the component types field for the new component type, and click create.

   The HTML user interface displays the Components Types Details Edit page for the new component type.

4. Use the controls on this page to specify the necessary information that will make up the component type.

   1. Change the name in the component field, if desired. Once the component is checked in you will not be able to change the name.

   2. Enter a Menu Group name.

   3. Define the menu order by entering a 18 digit number.

   4. Specify the indent level.

   5. Enter a description in the Description field.

   6. Enter a description if one is desired.

   7. Select a defining component.

   8. When finished click save.

How To Edit Component Types

Steps

1. In the left-hand navigation menu, click administrative.

   The HTML user interface displays the administrative page, which allows the user to select one of four administrative functions.

2. Click on the component types link on the administrative page.

   The HTML user interface displays a list of the component types.

3. Find the row listing the component type you're interested in, and click details.

   The HTML user interface displays a Components Types Details page for the component type.

4. Click the edit button located near the bottom of the page.

   The HTML user interface displays a Components Types Details Edit page for the component type.

5. Use the controls on this page to change any information that you want to change.

   • Enter a Menu Group name.

   • Define the menu order by entering a 18 digit number.

   • Specify the indent level.

   • Enter a description in the Description field.

   • Enter a description if one is desired.

   • Select a defining component.

   • When finished click save.

General Purpose Extended Control Services

Extended control services are procedures that perform a software operation related to a resource or component. These services include services for starting and stop the Microsoft IIS Web Server and for starting and stopping specific Windows services. The provisioning software includes two sets of extended control services that are not specific to individual resource types:

• general purpose control services, which can be called by any component or plan

• resource-type-specific control services, which are related to a specific type of resource and that can be called only by components or plans that include resources with those resource types

General purpose control services include the ability to start or stop Windows services. These control services can be called by any component or plan.

An example of a resource-type-specific control service is the startRouter procedure included with the COM+ Application resource type. This procedure starts COM+ routing services. It works only with resources that are of the COM+ Application resource type.

Extended Control Services for IIS

Table 5–47 lists the provisioning software's built-in procedures for controlling IIS.

Extended Control Services for Windows Services

A component or plan may include steps to start or stop specific Windows Services.

Table 5–48 describes provisioning software's built-in procedures for controlling Windows Services.