6 Using the Plug-in for Oracle Virtual Assembly Builder

This chapter describes the WebLogic Server introspection plug-in for Oracle Virtual Assembly Builder, which examines a single WebLogic domain. The domain specified and the Oracle home are captured.

Note:

This chapter describes the WebLogic Server plug-in that is included with the WebLogic Server installation program. Older versions of this plug-in are included with the Oracle Virtual Assembly Builder installation program. For information about using an older plug-in, see Release Notes for Oracle Virtual Assembly Builder.

This chapter includes the following sections:

Overview

The following topics provide a brief overview of Oracle Virtual Assembly Builder and the WebLogic Server introspection plug-in:

About Oracle Virtual Assembly Builder

Oracle Virtual Assembly Builder is a tool for virtualizing installed Oracle components, modifying those components, and then deploying them into your own environment. Using Oracle Virtual Assembly Builder, you capture the configuration of existing software components in artifacts called software appliances. Appliances can then be grouped, and their relationships defined into artifacts called software assemblies which provide a blueprint describing a complete multi-tier application topology.

Oracle Virtual Assembly Builder allows the logical connections between appliances within an assembly to be reconfigured by a process known as assembly editing. When a desired assembly configuration has been achieved, you use Oracle Virtual Assembly Builder to prepare the assembly for deployment and then deploy it into your environment.

For more information, see Using Oracle Virtual Assembly Builder.

About the WebLogic Server Introspection Plug-in

Introspection is an operation performed on a software component or a group of related components to create an appliance or assembly. During introspection, Oracle Virtual Assembly Builder creates an XML description of the component and captures a component-specific set of configuration files. This information forms a snapshot of the component's configuration at the time of introspection.

The introspection architecture is plug-in based. A plug-in is available for each supported component type, including a plug-in for WebLogic Server. Typically the result of introspecting a component is an appliance. However, when you use Oracle Virtual Assembly Builder to introspect a WebLogic Server domain, the introspection plug-in generates an assembly. The generated assembly contains:

An appliance representing the Administration Server.
One appliance for each standalone Managed Server.
One appliance for each cluster. (This appliance encompasses all Managed Server instances contained in that cluster.)

The WebLogic Server introspection plug-in fully supports WebLogic domains that are configured with dynamic clusters and dynamic servers.

Setting Up the WebLogic Server Introspection Plug-in

The following steps summarize the process of making the WebLogic Server introspection plug-in available for us with Oracle Virtual Assembly Builder:

Install the Oracle Fusion Middleware Infrastructure software (wls_jrf_generic.jar), as described in Planning an Installation of Oracle Fusion Middleware.

For installation type, select Fusion Middleware Infrastructure.
Install Oracle Virtual Assembly Builder, as described in Installing Oracle Virtual Assembly Builder.
Install the WebLogic Server plug-in for Oracle Virtual Assembly Builder using the following command:
```
$AB_INSTANCE/bin/abctl installPlugins -productRoot $ORACLE_HOME/wlserver
```
In the preceding command, $AB_INSTANCE is the environment variable set to the Studio instance home directory.

Introspection Plug-in Parameters

Table 6-1 lists the introspection parameters for the WebLogic Server plug-in for Oracle Virtual Assembly Builder. The specific set of parameters that are available for use depend on whether you are using the abctl command or Oracle Virtual Assembly Builder Studio. The column labeled Command-Line Support indicates whether the corresponding parameter may be specified using the abctl command. The column labeled Required indicates whether the parameter must be specified for the plug-in.

Table 6-1 WebLogic Server Plug-in Introspection Parameters

Parameter	Description	Command-Line Support	Required
domainRoot	The fully qualified path to the domain you want to introspect. This should be the directory that contains the `config` directory.	Yes	Yes
wlsHome	The fully qualified path to the WebLogic home directory. For example, `/u01/Oracle/Middleware/Oracle_Home/wlserver`.	Yes	Yes
adminUser	The administrative user for the WebLogic domain.	Yes	Yes
adminPassword	The password for the administrative user corresponding to the `adminUser` parameter.	No	Yes
nodeManagerUser	The Node Manager user name. If you specify this parameter during introspection time, the specified user name is used when the domain is rehydrated. If you specify this option in the abctl command, you are automatically prompted for the `nodeManagerPassword`, which is used during dehydration. If you do not specify this parameter, the value of the `adminUser` parameter is used by default as the Node Manager user.	Yes	No
nodeManagerPassword	The password for the user specified with the `nodeManagerUser` parameter.	No	Yes¹
nodeManagerDir	The non-default directory that contains the Node Manager configuration. If this parameter is not specified, the following value is used by default: $WL_HOME/common/nodemanager	Yes	No
identityKeystorePassPhrase	The password for the identity keystore that is used if the domain is configured to have a custom identity keystore.	No	No
privateKeyPassPhrase	The password for the private key contained in the custom identity keystore.	No	No

Reference System Prerequisites

The Administration Server for the domain must be running and introspection must target the Administration Server host machine.

Plug-in Usage Requirements

Table 6-2 lists and describes the requirements for using the introspection plug-in. Some requirements listed in this table pertain to the WebLogic Server plug-in, while others pertain overall to Oracle Virtual Assembly Builder. For more information, see Installing Oracle Virtual Assembly Builder.

Table 6-2 Requirements for Using the Introspection Plug-in

Requirement	Description
Editable domain	You must ensure that any WebLogic domain being introspected is configured to be editable. This allows edits to be performed successfully during deployment. For more information, see Understanding Domain Configuration for Oracle WebLogic Server.
Oracle Internet Directory	Oracle recommends the use of Oracle Internet Directory as the LDAP identity store on the reference system, not a file-based LDAP server. File-based LDAP cannot work properly in a deployed system due to synchronization issues.
Remote user	The remote user specified for remote introspection of WebLogic Server must be able to access files created by the user who owns the WebLogic Server process. When possible Oracle recommends that the remote user specified be the same as the user who owns the WebLogic Server process.
Applications accessing Web services	For each application that accesses a Web service hosted on the WebLogic Server reference system, you must: Update the application to access the Web service WSDL on the new Oracle VM host. Redeploy the application to the Oracle VM WebLogic Server environment, using any of the administration tools listed in "Summary of System Administration Tools and APIs" in Understanding Oracle WebLogic Server.
Avoid creating templates on individual servers	You must not create a template on an individual server in WebLogic Server. Such templates cannot be deployed because they lack certain deployment artifacts (the domain template jar in content, and data at the assembly level).
Administration Server URL	If you want to perform manual starts from the context of the Guest-OS, you must manually modify the `StartManagedServer` script to provide the correct Administration Server URL (Administration Server host name). This is required to provide the default Administration Server URL the correct value (the machine name of the Administration Server is not known at the time of template creation).

Resulting Artifact Type

An atomic assembly that contains an appliance for the Administration Server and appliances for any clusters found and any standalone (that is, non-clustered) Managed Servers found. One appliance is created for a cluster regardless of the number of Managed Servers in that cluster. The WebLogic Server plug-in assumes that every Managed Server in a cluster is configured identically. The names and the number of Managed Servers in the cluster are saved as 'scale out' information in the appliance metadata.

Note:

An atomic assembly cannot be edited to add or remove appliances. To wire other appliances to an atomic WebLogic Server assembly a non-atomic assembly must be created and the WebLogic Server assembly must be added to the non-atomic assembly.

Wiring

Inputs are created on the WebLogic Server assembly for all the channels the servers in the domain are listening on. Typically Oracle HTTP Server outputs would be connected to the WebLogic Server inputs.

Outputs are created on the WebLogic Server assembly for the following types of configuration that are found:

JDBC
LDAP
JMS messaging bridges
Foreign JMS

These outputs must all be connected to either an external resource or to an appliance before deployment. The description on the output and the protocol supported by the output provide hints about the type of appliance to connect the output to.

Wiring Properties

All input endpoints have the following wiring properties:

Two editable properties: port and description.
One non-editable property: a list of protocols. The protocols indicate the type of outputs that can be connected to the input.

All output endpoints have the following wiring properties:

One editable property: description.
The following non-editable properties:
- protocol — Indicates the type of input that can be connected to the output.
- singleton — Indicates the type of appliance that the output can be connected to. If singleton is true, the output can be connected only to an input on an appliance that has a scalability absolute max value of 1.

Table 6-3 describes common WebLogic Server appliance input user properties:

Table 6-3 Common WebLogic Server Appliance Input User Properties

Name	Type	Req'd	Default	Description
keepLocalHost	Boolean	false	none	If this input was originally bound to localhost explicitly, this property will exist and be set to true. Connections should not be made to this input if this property exists and its value is not overridden to false.
readymetric-naming-password	String	false	none	The password to use for the connection made to the server when doing the ready metric check.
readymetric-naming-protocol	String	false	none	Optional protocol you can specify for naming connections used for the ready metric check (for example, `iiop`).
readymetric-naming-user	String	false	none	The user to use for the connection made to the server when doing the ready metric check (for example, `weblogic`).
readymetric-server-protocol	String	false	none	The protocol to use for the connection made to the server when doing the ready metric check (for example, `iiop`).

Table 6-4 describes common WebLogic Server appliance input properties. These are not user-modifiable properties.

Table 6-4 Common WebLogic Server Appliance Input Properties

Name	Type	Req'd	Default	Description
originalBindAddresses	String	false	none	The original address of the system that was introspected.
originalDefaultHostname	String	false	none	The original host name of the system that was introspected. (For example, `example.com`).

Table 6-5 describes the Administration Server appliance input system properties:

Table 6-5 Administration Server Appliance Input Properties

Name	Type	Req'd	Default	Description
admin-password	String	true	none	The admin user's password. This is a user-modified property, specified in the deployment plan, that allows a deployer to introspect a well-known domain and deploy it multiple times, each deployed instance having a custom password.
admin-username	String	true	none	The admin user name for connecting to the Administration Server (for example, `weblogic`).

Table 6-6 through Table 6-9 describe Administration Server appliance output user properties for JDBC, foreign JMS, JMS messaging bridge, and LDAP.

Table 6-6 describes Administration Server appliance output user and system properties for JDBC. The password and username properties are user properties, and original-url is a system property.

Table 6-6 Administration Server Appliance Output Properties: JDBC

Name	Type	Req'd	Default	Description
password	String	false	<empty>	The password for the user needed for the data source connection.
username	String	false	none	The user needed for the data source connection. The value will be the original user for the data source connection.
original-url	String	false	none	The original JDBC URL from the introspected WebLogic domain. For example, `jdbc:oracle:thin:@adc2100927.example.com:1521:orcl`.

Table 6-7 describes Administration Server appliance output user properties for foreign JMS:

Table 6-7 Administration Server Appliance Output Properties: Foreign JMS

Name	Type	Req'd	Default	Description
original-connection-url	String	false	none	The original URL for the foreign JMS server.

Table 6-8 describes Administration Server appliance output system properties for JMS messaging bridge:

Table 6-8 Administration Server Appliance Output Properties: JMS Messaging Bridge

Name	Type	Req'd	Default	Description
original-url	String	false	none	The original URL for the JMS messaging bridge server.
original-username	String	false	none	The original username for the JMS messaging bridge server.
original-password	String	false	none	The original password for the JMS messaging bridge server, encrypted.

Table 6-9 describes Administration Server appliance output system properties for LDAP:

Table 6-9 Administration Server Appliance Output Properties: LDAP

Name	Type	Req'd	Default	Description
original-name	String	false	none	The original name for the LDAP security provider.
original-host	String	false	none	The original host for the LDAP security provider.
original-port	String	false	none	The original port for the LDAP security provider.
original-user	String	false	none	The original user for the LDAP security provider.

WebLogic Server Appliance Properties

This section discusses the following properties for assemblies with a WebLogic Server appliance. Those properties include assembly-level properties, properties on the inputs and outputs of each application, and properties of the appliances themselves. This section contains the following subsections:

Assembly-Level System Properties

Table 6-10 describes assembly-level system properties:

Table 6-10 Assembly-level System Properties

Name	Type	Req'd	Default	Description
admin-password	String	true	none	The admin user password for the domain.
admin-username	String	true	none	The admin user for the domain (for example, `weblogic`).
admsvr-jmx-input	String	true	none	Indicates what input on the Administration Server appliance should be used when making JMX connections (for example, `Default`).
admsvr-jmx-protocol	String	true	none	The protocol to use when making a JMX connection to the Administration Server (for example, `iiop`).
domain-name	String	false	none	The domain name of the domain that was introspected (for example, `test_domain`).
usesOracleHomes	boolean	true	none	Indicates that this is not a core WebLogic Server installation and as such has an Oracle home associated with it. This will be true for SOA and WebCenter domains. Allowable values are true and false.

Properties Common to Administration Server and Managed Server Appliances

The following information describes properties common to Administration Server and Managed Server appliances.

Table 6-11 describes common WebLogic Server appliance user properties:

Table 6-11 Common WebLogic Server Appliance User Properties

Name	Type	Req'd	Default	Description
NodeManagerPort	Integer	true	5556	The port the Node Manager should listen on (for example, 5556). This will only be present if the Node Manager was found to be configured on the reference system.
readymetric-attribute-compare-type	String	false	EQUALS	The comparison to make between the readymetric-attribute's value and the value specified for the property `readymetric-attribute-value`. Valid values are EQUALS, LESSER_THAN, GREATER_THAN, LESSER_THAN_OR_EQUAL, and GREATER_THAN_OR_EQUAL.
readymetric-attribute-name	String	false	State	The MBean attribute to check.
readymetric-attribute-type	String	false	STRING	The type of the MBean attribute. Valid values (but specific to the attribute being examined) are STRING, INTEGER, SHORT, LONG, DOUBLE, FLOAT, and BOOLEAN.
readymetric-attribute-value	String	false	RUNNING	The value the property `readymetric-attribute-name` must have for the check to be considered successful.
readymetric-instance-name-0	String	false	com.bea:Name=AdminServer,Type=ServerRuntime	The instance name to use for the JMX ready metric check.
readymetric-max-wait-period	String	false	600	The maximum time in seconds to wait for a successful ready metric check.
readymetric-naming-input	String	false	none	The input to use for the ready metric check (for example, "Default").
readymetric-polling-period	String	false	none	The time between connection attempts, in seconds, for the ready metric check.
readymetric-server-input	String	false	none	The input to use for the ready metric check (for example, "Default").
readymetric-trust-store-0	String	false	none	The location of the trust store to use if the ready metric check is using an SSL enabled port.
readymetric-type	String	false	JMX	The type of ready metric to use for the appliance.
readymetric-verify	String	false	true	If this property is set to true the ready metric check will be performed. Otherwise it will be skipped.
useTemplate	String	false	OEL	Specifies the template type to use by default when creating a template for the appliance.

Administration Server Appliance Properties

Table 6-12 describes Administration Server appliance system properties:

Table 6-12 Administration Server Appliance System Properties

Name	Type	Req'd	Default	Description
admin-input-name	String	false	none	The input to use for connecting to the Administration Server admin-input-protocol (for example, "Default").
admin-input-protocol	String	false	none	The protocol to use for connecting to the Administration Server (for example, "http").

Table 6-13 describes Administration Server appliance user properties:

Table 6-13 Administration Server Appliance User Properties

Name	Type	Req'd	Default	Description
<cluster name>-cluster-address	String	false	<empty>	The cluster address for the cluster named by the first part of the property name.
<cluster name>-frontend-host	String	false	<empty>	The front-end host for the cluster named by the first part of the property name.
<cluster name>-frontend-http-port	String	false	<empty>	The non-secure front-end port for the cluster named by the first part of the property name.
<cluster name>-frontend-https-port	String	false	<empty>	The secure front-end port for the cluster named by the first part of the property name.

Oracle Coherence*Web Introspection Extension

The Oracle Coherence*Web introspection extension extends the functionality of the WebLogic Server Introspector. It examines the configuration of Coherence cache clusters and servers configured as part of a WebLogic domain. For more information, see the Oracle Coherence documentation.

Supported Template Types

The supported template type is Oracle Enterprise Linux (OEL).

Required only if the Node Manager user name is specified.