Chapter 16 Configuration Generation

Many applications are almost identical no matter what hosts they are installed and running on, apart from perhaps one configuration file containing host-specific information. These configuration files usually contain values that are specific to the host they are installed on, or are otherwise customized on a per-host or host set basis. For example, you may have different deployment environments such as QA/test, staging/burn in, and production. The configuration values used in each of these environments is probably different. The N1 Service Provisioning System software makes the deployment of each of these environments simpler by allowing you to define different variable settings objects that contain the variable values you want to use in each of those deployment environments.

Adding Substitution Variable Definitions to Components

When you use the N1 Service Provisioning System software to run a plan that deploys an application across multiple hosts, you can use the configuration generation feature to automatically insert the appropriate configuration values for each host. The provisioning software does this by parsing a template of the configuration file that you create.

To do this, you add substitution variable definitions to your components. These can be used, for example, as a way to configure the directory into which an application is installed. Using the provisioning software, you can define and manage different variable settings for application deployments on each of your target hosts.

• Each version of a component can declare its own variable definitions

• Each version of a component has its own variable settings (possibly imported from a previous version)

• Each component can be installed using any of its variable settings

Variable Substitution Values

The values that the provisioning software substitutes when you install an application can be any of the following:

• Value you specify

• Component-specific value such as name or label

• Host-specific value such as IP number or hostname

• Value specific to the target host

• Value associated with a previously installed component

• Value of a session variable

Generation Context

Variable substitution happens when a target step is run on a target host. The step can be in a plan, in a component being installed on the target host, or in a component already installed on the target host. If there is a state associated with the target host and component, it is used to determine the value of a particular substitution variable, and can include:

• Target component - The component to be installed

• Target host - The host upon which the plan is to be run

• Target variable settings source - A collection of name-value pairs that will override the the default values defined in the component

• Local variables - Any variables in the target step itself, such as those you have declared in the enclosing block or plan

Types of Variables Available for Substitution

When you create or edit a component, you can use predefined variable definitions or you can create custom ones to suit your needs.

The syntax to use when defining variable substitutions is:

:[variable]

where variable is the parameter you want to substitute the host-specific value for.

There are four basic kinds of variables you can define within a component:

• Simple substitution variables

• External component substitution variables

• Session variable substitution

• Target substitution variables

Simple Substitution Variables

You use simple substitution to define variables that you then reference later in the same component.

Simple substitution variables use the following syntax:

:[variable] 

where variable is one of the following:

• Local variable name - You can use local variable names in steps within a plan and in steps within a component's install, uninstall, and control service blocks.

• Parameter name - You can use parameter names in steps within a plan and in steps within a component's install, uninstall, and control service blocks.

• Predefined component variable name - You can only use predefined component variables in input sources associated with a component, but not for plans.

  Predefined component variables are always resolved relative to the actual component that is (or is being) installed, even if the variable reference occurs in a base component. From an accessibility standpoint, predefined component variables are treated as public variables.

  The predefined component variable names are listed in Predefined Substitution Variables for Components and Configuration Files.

• Dynamic component variable name - You can only use dynamic component variables in input sources associated with a component, but not for plans.

  A dynamic component variable name is a variable name declared by the associated component of the target component. In this case, the value to be substituted for the variable reference is either the associated override variables settings value, or else the default value defined by the component The value of this variable will be expanded before it is substituted.

External Substitution Variables

A variable setting value may include any number of external component substitution references. An external component substitution reference is one of the following:

:[primary-component:varname]
:[primary-component:secondary-component-list:varname]

An external component substitution reference does not include any white space.

Above, primary-component is one of the following:

	explicit-external-component
	secondary-component

And secondary-component is one of the following:

	nested-component
	toplevel-component
	dependee-component

The secondary-component-list is a sequence of one or more colon-separated secondary-components.

The varname is either a predefined substitution variable name, or a dynamic substitution variable name declared by the referenced component.

Explicit External Component Expansion

An explicit-external-component explicitly specifies a component that is expected to be installed on a particular host at a particular location, and has the component resolution semantics of the <installedComponent> installed component targeter described in Chapter 2, “Installed Component Targeter” section. It has the following syntax:

	component-target:explicit-component-reference

Above, component-target specifies the host on which the desired component is installed, and is one of the following:

component
component(host-redirect)

The first variant specifies the current target host in the generation context. The second variant refers to the ROX host named by host-redirect, as specified in the host redirects section.

Above, explicit-component-reference is a reference to a component already installed on the target host specified by component-target. explicit-component-reference minimally includes the installed component name, but may also include a version and an install path, as follows:

full-component-name
full-component-name#version
full-component-name@{path}
full-component-name#version@{path}

Above, full-component-name is an absolute or relative reference to the desired component. Relative references are expanded relative to the plan or component that contains the explicit-component-reference. And path is either an absolute path name representing the install path of the desired component, or a substitution variable reference that, when expanded, represents the absolute install path of the desired component. If the former includes the "}" character, it must be escaped using the sequence "}}".

Nested Component Expansion

A nested-component specifies the component that is referenced by a nested component reference declared by the current component, and has the component resolution semantics of the <nestedRef> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has the following syntax:

	nestedRef:component-reference-name

Above, component-reference-name is the name of a <componentRef> element with "NESTED" installMode within the current component.

A nested-component may only be used when the current component is a composite component, and may only be used as a primary-component when the external component substitution reference appears within a composite component. When used as a primary-component, it may not be used as the default value of a component variable or override variable setting, as the referenced component will not yet have been installed when the variable is evaluated.

Toplevel Component Expansion

A toplevel-component specifies the component that is referenced by a toplevel component reference declared by the current component, and has the component resolution semantics of the <toplevelRef> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has one of the following formats:

toplevelRef:component-reference-name
toplevelRef:component-reference-name@{path}
toplevelRef(host-redirect):component-reference-name
toplevelRef(host-redirect):component-reference-name@{path}

Above, component-reference-name is the name of a <componentRef> element with "TOPLEVEL" installMode within the current component.

Above, path and host-redirect are the location and host, respectively, at which the referenced component is expected to be installed. host-redirect has syntax as specified in the host redirects section.

A toplevel-component may only be used when the current component is a composite component, and may only be used as a primary-component when the external component substitution reference appears within a composite component. When used as a primary-component, it may not be used as the default value of a component variable or override variable setting unless the referenced component has already been installed.

Dependee Component Expansion

A dependee-component specifies the component on which the current component depends as a result of a dependency created by a <createDependency> step, and has the component resolution semantics of the <dependee> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has the following syntax:

	dependee:dependency-name

Above, dependency-name is the name of a dependency created by the current component.

A dependee-component may only be used as a primary-component when the external component substitution reference appears within a component. When used as a primary-component, it may not be used as the default value of a component variable or override variable setting, as the dependency will not yet have been created when the variable is evaluated.

System Service Component Expansion

A system-service-component specifies a system service component that is expected to be installed on the root physical host of the current target, and has the component resolution semantics of the <systemService> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has the following syntax:

systemService:system-service-name

System Type Component Expansion

A system-type-component specifies the component derived from a given component type that is most recently installed on a particular host at a particular location, and has the component resolution semantics of the <systemType> installed component targeter described in Chapter 2, "Installed Component Targeter" section. It has the following syntax:

systemType:component-type-name

systemType:component-type-name@{path}

systemType(host-redirect):component-type-name

systemType(host-redirect):component-type-name@{path}

Here, path is optional, and if specified, indicates the path in which the desired component is installed. The host-redirect is also optional, and indicates the host on which the desired component is installed, as described in the host redirects section.

Container Component Expansion

A container-component specifies the component that contains the current component as a nested reference. It has the following syntax:

	container

A container-component may only be used as a primary-component when the external component substitution reference appears within a component that has been installed as a nested component by another "container" component.

External Component Substitution Reference Resolution

The value of an external component substitution reference is computed by first resolving the component referenced by primary-component. If a secondary-component is used as a primary-component, then the component containing the external component substitution reference serves as the initial current component used when resolving the primary-component. The component resolved by primary-component becomes the new current component. Then, each secondary-component in the secondary-component-list is resolved using the last resolved component as the current component. Finally, we lookup and return the variable named varname in the last resolved component.

The value of an external component substitution reference is computed based on the value of the named variable within the referenced component as of the time it was installed. It is an error to reference a variable name that is not declared by the installed component, or to reference a component that is not installed on the target host. It is also an error to reference a variable that is not accessible to the component or plan that declares the external component substitution reference. The variable is accessible if and only if the variable is declared with an accessible access mode, and the component declaring the component is accessible, and each of the primary and secondary components traversed to get to that component are accessible.

External component substitution references are computed at the time that they are encountered during a plan run (as opposed to at the start of the plan run). Therefore, actual installed component being referenced may change based on steps executed earlier in the plan. Furthermore, references to components installed on a host other than the current target host may be affected by other plans running concurrently on the other host. For predictable results, clients should only reference hosts included in the target set of the current plan run (so that they"re guaranteed to be locked), and should synchronize any install/uninstall operations on an externally referenced host within the plan using retargeting and/or series execution mode.

Here are some examples of external component substitution references, using explicit-external components:

:[component:installApache:label]
:[component:jdk#1.3:classpath]
:[component:webApp#2.4@{/usr/local}:bannerColor]
:[component(/):IIS global settings:install_path]
:[component:webApp@{:[webAppPath]}:bannerColor]

In the second to last example, the component is resolved that is installed on the root physical host of the current target host.

In the last line, webAppPath is resolved as the name of a simple substitution variable set in the associated component of the generation context, not a variable defined in the externally referenced component.

Here are some examples of external component substitution references, using nested and toplevel-components:

:[nestedRef:ref1:label]
:[toplevelRef:ref2:name]
:[toplevelRef(/):ref3@{/usr/local}:var1]

Here is an example of external component substitution references, using dependee-components:

:[dependee:app2domain:domainName]

Session Variables Substitution Variables

Session variables allow users to enter data, such as their WebLogic credentials, once during a login session. Also, users can securely save the contents of these variables so that they don't need to re-enter them each time they log in. Session variables are integrated at the modeling level using substitution variables. Session variables have the following syntax:

session:varname

Above, varname is the name of a session variable.

Session variable references of the form session:varname will resolve to the value of the session variable in the current user's session. An attempt to resolve a session variable that is not defined in the current user's session results in an error that states that the session variable was not defined. When a failure to generate a session variable is encountered, an attempt will be made to add the session variable with an empty value to the user's current session variable set.

A session variable may be used anywhere a simple substitution variable reference may be used. However, a session variable cannot be used within the value of another session variable.

Target Substitution Variables

You can use target substitution variables to get values directly from a particular host

Target substitution variables use the following syntaxes:

:[target:varname]
:[target(hostname):varname]

Variable names that begin with target refer to the logical host upon which a plan is currently being run.

The varname parameter you add after the colon represents an attribute value that is specified in the target host's definition for the application you are installing.

If you specify a (hostname) right after target, the value for varname is retrieved from that particular host, which can be a different host than the host the plan is currently being run on. You can also specify another substitution variable for hostname that, when expanded, resolves to the name of a host.

Host Redirects

Host substitution references and external component substitution references may optionally include a host redirect, in which case the host on which the variable or component lookup will occur is redirected from the current target to a named host. A host redirect has one of the following forms:

parent-ref hostname hostname/parent-ref

Where hostname is either the name of a ROX host, or a substitution variable reference that, when expanded, resolves to the name of a ROX host.

And parent-ref is either "/", meaning the root parent host of the named host (or current target host if hostname is omitted), or a series of one or more slash-separated "..", meaning the nth parent of the named host (or current target host if hostname is omitted) where "n" is the number of ".." that appear. The parent-ref operators are meant primarily for use with virtual hosts, though they may be used with physical hosts as well. Applying either operator to a physical host is a no-op.

Here are some examples of using target substitution variables:

This example specifies to look up variable var1 on host myHost.

:[target(myHost):var1] 

This example specifies to look up variable var1 on host named by substitution variable hostName

:[target(:[hostName]):var1]

This example specifies to look up variable var1 on the logical host on which the plan is currently running.

:[target:var1]

The following are variables predefined for target hosts:

• name – the name of the target host

• description – description of the target host

• hostTypeName – the name of the host type of the target host

• raIP –the IP address of the remote agent on the target host

• raPort – port used by the remote agent on the target host

• raHomeDir - absolute path of the remote agent home directory on the target host

• raDataDir - absolute path of the remote agent data directory on the target host

• raTmp Dir - absolute path of the remote agent temporary directory on the target host

• raConfigDir - absolute path of the remote agent config directory on the target host

  ---

  Note –

  In addition to the predefined variables, you can also reference any host attribute declared by the host type of the target host.

  ---

The following is an example of the list of variables defined in a component for apache:

<varList>
	<var name="domainname" default=":[target:
domainname]" /> 
	<var name="name" default="apache" /> 
	<var name="installPath" default="/opt/apache" />
	<var name="execNativeShutdown" 
	 default=":[installPath]/bin/apachectlstop" />
	<var name="execNativeStartUp" 
	 default=":[installPath]/bin/apachectlstart" />
</varList>

This component specifies that the domain name be dynamically retrieved from the target host, defines the default value of `name' to be `apache', and then specifies a variable installPath value to use in the definition of two execNative variables.

Although you cannot use a target substitution variable within a configuration file, you can reference a host-specific value from within a configuration file. This is because the value of the variable you reference may be computed as a host-specific value. For example, you might have the following variable defined within the <varList> section of the component:

<var name="pants" value=":[target:pie]">

and then reference :[pants] from within a configuration file. When :[pants] is substituted, it will be substituted with the value of the pie variable defined by the target host.

Predefined Host Substitution Shorthands

The shorthands :[/] and :[/] can be used anywhere a host substitution reference may be used.

The shorthand :[/] is expanded to the operating system specific file separator based on the root physical host of the current target host. For example, it is expanded to “/” on UNIX-based operating systems and “\” on Windows.

The shorthand :[:] is expanded to the operating system specific path separator based on the root physical host of the current target host. For example, it is expanded to “:” on UNIX-based operating systems and “;” on Windows.

Using Substitution Variables

You can use simple substitution variables in any input source, including configuration files. You can use external component and target substitution variables in a number of places, including varList/var default values of installSteps, uninstallSteps, controlService and executionPlans.

The following is a complete list of what types of substitution variables can be used in what input sources:

The following configuration attributes of a component can include substitution variable definitions:

The following configuration attributes of steps within a component or plan can include substitution variable definitions:

The following configuration attributes of a plan can include substitution variable definitions:

The following configuration attributes of installed component targeters can include substitution variable definitions:

The following configuration attributes of repository component targeters can include substitution variable definitions:

Escape Sequences Within Files With Substitution Variable Definitions

If for some reason you want to include a sequence in a configuration file that matches the sequence defined for a substitution variable (:[), you can escape out the sequence by using another [ after the sequence. For example, if you wanted to include the text :[pants] in your configuration file, but didn't want N1 Service Provisioning System software to try and substitute a value for pants, you would use :[[pants].

The configuration generator replaces all occurrences of :[[ in the file with :[

When the input source for the variables you want to substitute is an attribute of a component component that is written in XML, use the usual rules for XML-based escape sequences:

Predefined Substitution Variables for Components and Configuration Files

N1 Service Provisioning System software supplies some predefined substitution variables for use within components and configurations files:

• name – Name of the component

• description – Description of the component

• label – Label of the component

• softwareVendor – Software vendor of the component

• author – Author of the component

• path - Path of the component

  The path variable is similar to the path attribute of the component, except that it always includes a trailing slash (/). The path variable can be directly combined with the name variable to create the full name of the component as follows:

  :[path]:[name]

• rsrcInstallPath - The location that where the component resource was installed

  The rsrcInstallPath variable will be in the file format for the remote agent on which the component is (or is being) installed. This variable is only defined for simple components. Because the value of the rsrcInstallPath variable may require other dynamic component variables to be computed, it may not be used within a component variable default value or variable settings override value. For the same reasons, the variable may not be used within the

  value of the <component> installPath attribute, or the <resourceRef>/<installSpec> element attributes. These restrictions prevent the possibility of circular references.

  ---

  Note –

  Variable names and definitions are case-sensitive.

  ---