10 Oracle Virtual Assembly Builder

This chapter describes issues associated with Oracle Virtual Assembly Builder. It includes the following topics:

10.1 Installation and Configuration Issues and Workarounds

This section describes issues related to installation of Oracle Virtual Assembly Builder. It includes these items:

10.1.1 Deployer Instance Directory Only Suitable for Use in Deployer-only Installation

When you perform a combined (Studio and Deployer) installation of Oracle Virtual Assembly, and subsequently configure the Deployer in an Oracle WebLogic Server domain, the installation creates an ab_instance directory under the Oracle WebLogic Server domain root ("Deployer instance directory"). This ab_instance will not be functional for the purposes of using abctl.

Instead, in the case of a combined installation you should only use the "Studio Instance directory" that is created by the Oracle Virtual Assembly Builder installer (typically located directly under MIDDLEWARE_HOME).

A Deployer instance directory is only suitable for use in a Deployer-only installation.

10.1.2 Disk Warning Causes Installation Failure

When installing Oracle Virtual Assembly Builder on an Oracle Exalogic machine with a large disk space, a known issue with the Oracle Universal Installer prevents the installation from completing. You can see an error that includes "errorString:Space required for Oracle home is 350 MB.[[ Space Available: 0 MB ]."

The workaround is to launch the installer as follows:

./runInstaller -novalidation -ignoreDiskWarning

10.1.3 Errors about Missing Libraries in the VM

If certain libraries are missing from the VM, an exception may be recorded in the logs on the VM. The exception is the result of a file copy, and is harmless. The file is still successfully copied. The exception appears similar to the following:

[2012-04-25T03:04:04.949-04:00] [as] [TRACE] [] 
[oracle.as.assemblybuilder.common] [tid: 11] [SRC_CLASS: 
oracle.as.assemblybuilder.common.jni.Native] [SRC_METHOD: <init>] Unable to load native library. 

10.1.4 Incorrect sshd_config File in Base Image

The base images used in creating the VMs has an incorrect sshd_config file. The line

#AllowTcpForwarding yes 

is commented out and should read:

AllowTcpForwarding yes 

To allow remote introspection, you must update the /etc/ssh/sshd_config file on the VMs and restart SSH (/etc/rc.d/init.d/sshd stop/start).

10.2 General Issues and Workarounds

This section describes general issues and workarounds for Oracle Virtual Assembly Builder Studio operations, such as introspection, capturing file sets, and deployment. It includes these items:

10.2.1 Oracle Virtual Assembly Builder Introspection Issues

This section describes issues observed during introspection. It includes these items: Remote Introspection Must Be Run as Specific Users

The remoteUser specified for remote WLS introspection must be either the owner of the WLS process that is running on the reference system, or must be a user that has permission to read files that the owner of the WLS process creates. Unable to Create Secure Connections for Multiple OVMs in a Single Session

You can create secure connections to multiple OVMs using Oracle Virtual Assembly Builder Studio. However, you cannot create secure connections to multiple OVMs during a single Studio session. In order to create multiple secure connections, you must create a secure connection, then exit Oracle Virtual Assembly Builder Studio. Restart Studio and create the next secure OVM connection. You must repeat this process for each desired secure OVM connection. Do Not Try to Import and Register a Template at the Same Time

Do not attempt to import and register a template at the same time. Doing so will cause the registration to fail and may cause unforeseen side-effects. Time Zones Must Match Between Base Image and Reference Systems

It is possible to have a time zone in your base image that is significantly different from the time zone of a reference system being introspected. If the introspected reference system is an Oracle WebLogic Server installation that has demo SSL certificates that were recently created you can experience a deployment failure caused by invalid SSL certificates. This is due to the valid time listed in the certificate being in the future relative to the time in the base image. Make sure the time zone in your base image matches the time zone of your reference systems to avoid this type of failure.

10.2.2 Oracle Virtual Assembly Builder File Set Capture Issues

This section describes issues observed during file set capture operations. It includes these items: Troubleshooting Template Registration Errors

If you receive an error while registering a template (such as ImportError, or any error including oracle.ovs.biz.exception.OVSException) in the Oracle Virtual Assembly Builder log file, be sure to check the Oracle VM logs for the root cause, as it may not be expressed in the Oracle Virtual Assembly Builder logs. Capturing File Sets with a Different userid than userid of Individual Who Installed Oracle Virtual Assembly Builder

When capturing file sets on a local reference system that was installed using a different OS userid than the one used for the Oracle Virtual Assembly Builder installation, capturing file sets will fail with file permission errors. There are two workarounds for this issue. Use either:

  • Run Oracle Virtual Assembly Builder as root. When you do this, all generated artifacts in catalog (such as metadata, file sets, and others) are owned by the root user and all subsequent operations must also be executed as root user.

  • Run local file set capture through remote ssh. Treat the local reference system as remote and perform remote file set capture, using an ssh user that has read permission of the reference system installation. Template Status Not Updated

An intermittent problem has been reported in which the status of a template is not immediately updated after the status has changed. If you encounter this issue, stop and restart Oracle Assembly Builder Studio. Oracle Virtual Assembly Builder Instance Directory Should Not Reside in FMWHOME

During introspection, you may receive a full disk error even though you have the required disk space available. You encounter this issue if you have specified an Oracle Virtual Assembly Builder instance that is located within a Fusion Middleware instance home. To correct the problem, move your Oracle Virtual Assembly Builder instance directory outside of the Fusion Middleware instance home. Non-Root User Cannot Capture File Sets Owned by Root

During introspection, if there are files owned by root in a directory such as ORACLE_HOME, a non-root user is prevented from capturing the file sets in the ORACLE_HOME as part of the introspection.

The solution is to remove these files, or have their ownership changed to the user that is capturing the file sets.

10.2.3 Oracle Virtual Assembly Builder Deployment Issues

This section describes issues observed during deployment. It includes these items: Scale Operations and Failed Deployments

Scale operations are affected by failed deployments.

Scale down operations only remove properly (successfully) deployed instances. In the case of failed deployments, those instances are not removed during scale down. Failed instances are left for you to troubleshoot. If you want to remove instances that failed to deploy, you must undeploy them, fix the plan, and then redeploy.

Scale up operations are prohibited if a failed instance exists in the assembly. As above, you must undeploy, fix the problem, and then redeploy. Importing Using the ImportAs Option Removes All Deployment Plan Overrides

When importing an assembly or assembly archive (OVA file) using the 'importAs' option, the deployment plans are imported, but any overrides that were in the original deployment plan are not imported. It will appear as if you have a new deployment plan with no overridden properties. Unresolved IP Addresses Result in Error

Deployment attempts will fail if IP addresses specified in the deployment plan are unresolved on the Oracle Virtual Assembly machine (the machine on which Deployer is running). To avoid this issue, ensure that IP addresses are resolvable. Complete Editing Operations on Assemblies Before Creating a Deployment Plan

If you have created deployment plans for an assembly, and then made certain modifications to the assembly (notably, adding or removing network interfaces from one of the assembly's appliances), then deployment plan values may become misassigned. (For example, the IP address and netmask for a deleted network interface may be assigned to a different network interface).

To avoid this, it is recommended that you create and populate deployment plans only after you have completed all desired editing operations on the assembly. The safest approach is to create an assembly archive first, then create deployment plans. This is because creating the assembly archive prevents further edit operations that may invalidate the deployment plan. NFS Mounting Not Supported in Reference Systems

Oracle Virtual Assembly Builder does not support NFS mounting in the reference system, since these NFS mounts will not be created by Assembly Builder in the deployment environment. In some cases, deployment will fail if the reference system has an NFS mount.

A number of third-party tools require mounting file systems as part of their configuration. This can require specific workarounds. For example, when using the Websphere MessageQueue external JMS server, you may encounter the following issues:

  • The configuration for the JMS Server requires access to a class provided by Websphere. In some environments, those classes (also known as jars) are added to the PRE_CLASSPATH environment variable prior to starting Oracle WebLogic Server. Ensure that the configuration for your environment does not require modification for Oracle WebLogic Server to be able to see these jar files automatically on startup.

  • The Oracle WebLogic Server configuration for the JMS server requires a JNDI connection URL as follows, 'file://<path to mq config>'. This file resides on the external Websphere server, and must be mounted locally so it can be used. Firewall Implications for Template Registration

To allow template registration, the Oracle VM host must be able to download the template through HTTP from the Assembly Builder host. If you are using a firewall (for example, iptables on Linux) then you must properly configure that firewall to allow the communication. By default Oracle Virtual Assembly Builder specifies its HTTP port to be "0" which causes the system to issue one (so there is no default port).

You can specify the port by setting the "ovmPort" property in deployer.properties.

A simpler solution is to turn off the firewall. For iptables, use the following command: /etc/init.d/iptables stop

To configure your firewall, refer to the documentation for your firewall. Recovering from Unexpected Errors During Deployment

Whenever an unexpected error occurs during deployment, you typically want to examine what went wrong and perform necessary cleanup before recovering from the error. For these reasons, Oracle Virtual Assembly Builder provides neither an automatic recovery mechanism, nor a tool to recover from a failure.

To perform recovery of the Deployer:

  1. Examine the resource pools in the corresponding Oracle Virtual Machine managers configured in the resource-pools.xml file relevant to the crashed AB_INSTANCE and perform cleanup. This includes cleaning up (stopping and destroying) all instances initiated by Oracle Virtual Assembly Builder.

  2. Delete the .hastore file.

This returns the Deployer to a clean state. Deployment Failure Due to 'Too Many Open Files' Error

Some components may require a large number of open files to deploy successfully. Even if a base image with the required limits is provided, the limit will be reset to 4096 by the Oracle Virtual Assembly Builder service that runs on the VM.

The workaround is to edit $ORACLE_HOME/resources/bottler/ab/etc/ab_service.sh to set the desired limit instead of 4096, and then to create (or recreate) the assembly archive.

10.2.4 Other Oracle Virtual Assembly Builder Issues

This section describes other issues observed while performing operations in Oracle Virtual Assembly Builder. It includes these items: Add DNS Button Does Not Work When Using OVAB Studio in Japanese Language

When following the procedure to create resource pools using the graphical interface of Oracle Virtual Assembly Builder Studio set to the Japanese locale, the Add DNS button does not function. To work around this problem, set the locale to English:

  1. Exit Oracle Virtual Assembly Builder

  2. Execute the commands:

    export LC_ALL= c 
  3. Create resource pool connection in the English locale. Large Delete Operations Can Make Oracle Virtual Assembly Builder Studio Appear to Lock Up

When large top-level items are deleted through Oracle Virtual Assembly Builder Studio, the interface may appear to have locked-up, when in fact it is running normally. This is normal behavior, allow the application to finish its task. Virtual Machine Swap Space

Ensure your virtual machines have at least 500MB of available swap space (on each machine). Top-level Delete Messages in English Only

Messages displayed during top-level delete of items are displayed in English only. Export Operation Requires Temporary Local Storage

In an export operation, the AB_INSTANCE/tmp directory is used for storage of intermediary artifacts. This means that an export may fail if there is not enough space in the disk where AB_INSTANCE is located, even though the destination directory may be located in another disk. Non-supported Character When Naming Vnets

It is possible to create networks in Oracle VM 3.0 that have the period ('.') character in the name. But Oracle Virtual Assembly Builder does not support this character in the name so you will not be able to name your Vnet in Oracle Virtual Assembly Builder after the actual network name in your Oracle VM 3.0 environment.

The createAssembly command in the Oracle Virtual Assembly Builder abctl command-line interface fails to disallow a Vnet name containing the '.' character. The Oracle Virtual Assembly Builder Studio graphical user interface correctly disallows it. Obsolete Assembly Archives After Download and Import

In a Oracle Virtual Assembly Builder Studio or combined (Studio and Deployer) installation, downloading an assembly archive from the Deployer or from the EM Software Library automatically imports the archive into the local catalog. If you optionally specify a new name for the assembly when downloading, then the archive file will be saved on disk using the new name, and imported into the catalog using the new name. However, the contents inside the archive will still refer to the original assembly name, and hence this downloaded archive should be considered obsolete.

Therefore, after a successful download and import, the downloaded archive should not be used. It can be deleted manually from AB_INSTANCE/archives, or it can be overwritten by using the createAssemblyArchive command with the -force option, or the create template wizard in the Oracle Virtual Assembly Builder Studio graphical user interface (which implicitly uses the -force option). Zero-count Appliances Cannot Be Scaled in Oracle Virtual Assembly Builder Studio

If you deploy an assembly that contains a 'zero-count' appliance - that is, an appliance with its scaling minimum and initial target both set to 0 - you will not be able to scale that appliance up using the Oracle Virtual Assembly Builder Studio graphical user interface. Use the Oracle Virtual Assembly Builder command-line interface scale command instead. If the describeScalingGroups command does not show the group you want to scale, use the appliance id, which can be found in the 'Appliances' column of the describeAssemblyInstances output.

10.3 Component Specific Issues

This section describes specific issues for components that Oracle Virtual Assembly Builder can introspect. The list of issues for each component presents the most severe or frequently encountered issues first, followed by lower priority issues.

This section describes the following topics:

10.3.1 Oracle Virtual Machine

This section describes issues for Oracle VM. It includes these items: Intermittent Errors When Using Oracle VM

Intermittent errors have been reported when using Oracle VM. If you receive an error that includes oracle.ovs.biz, check the Oracle VM logs to ensure you understand the root cause of the problem. In some cases, simply reattempting the task will solve the problem, but consulting the logs is the best approach. Limit Virtual Machine Names to 100 Characters or Less

Oracle Virtual Machine limits virtual machine names to 100 characters or less. If your names are too long, you will receive the error: oracle.ovs.biz.exception.invalidNameException: OVM-4008

Oracle Virtual Assembly Builder Deployer determines virtual machine names based on the following format:


In order to have virtual machine name length in the defined 100 character limit, the assembly name (and all subassembly names) and appliance names combined must be short enough that, when combined, are less than 100 characters. Limit Virtual Machine Passwords to 50 Characters or Less

Oracle Virtual Machine limits virtual machine passwords to 50 characters or less; your virtual machine password must be less than 50 characters long. If your password is too long, you will receive the error: Oracle.ovs.biz.exception.OVSException: OVM-5101 The template{0} cannot be found Limitation on Number of Virtual Disks

Oracle VM supports handling an appliance with up to 26 virtual disks. If you attempt to perform operations to create a larger number of virtual disks, you will experience a failure and an error message indicating that a 'disk image declared in the OVF does not exist in the OVA.' VNC Access Only Available through Oracle VM Manager

Although you must supply a VNC password when creating templates, and can override this password in a deployment plan, neither of these values will actually take effect. You must access virtual machine VNC consoles through the Oracle VM Manager console, using the appropriate credentials as defined by Oracle VM Manager.

10.3.2 Oracle WebLogic Server Issues

This section describes issues for Oracle WebLogic Server. It includes these items: Forward Slashes in Server Service Names Cause Oracle WebLogic Server Deployment Failures

You can create a WebLogic Server service (such as a JMS server definition or a data source definition) with a name that contains a forward slash ( '/' ). Services with forward slashes in their names will cause WebLogic Server deployments to fail. To work around this, ensure that your WebLogic Server services do not have the '/' character in their names. Applications with JDBC Remap May Need to be Manually Restarted

An error has been reported in which an application using JDBC data source mapping configured at the application scope fails to start. The failure occurs only for deployments on Oracle WebLogic Server AdminServer, and only immediately after the AdminServer itself is deployed.

To correct this problem, manually start the AdminServer. Applications Accessing Web Services Not Updated at Deployment

An application that accesses a Web service that is also hosted on the Oracle WebLogic Server reference system will not be updated to point to the new web service location upon deployment. You must update the application to access the web service WSDL on the new Oracle VM host, and then redeploy the application through Oracle WebLogic Server administration tools, such as Admin Console or wlst, to the Oracle VM Oracle WebLogic Server environment. Limitation with Oracle WLS Domains Upgraded from 10.3.1

Oracle Virtual Assembly Builder uses a pack/unpack utility when moving Oracle WebLogic Server domains. An issue with the utility causes the unpack operation to fail when using the utility to move a domain that was originally a 10.3.1 domain, but which was upgraded to 10.3.2 during installation of 10.3.2. Admin URL Required to be Specified When Managed Server is No Longer Running

This issue applies to an uncommon scenario in which Oracle Virtual Assembly Builder has deployed and started the required instances in the assembly, including the Oracle WebLogic Server Managed Servers, and later the Managed Server (but not the guest OS) has either crashed or been explicitly shutdown through an external tool.

If you want to perform manual starts from the context of the guest OS, you must manually modify the StartManagedServer.sh script to provide the correct Admin Server URL (Admin Server hostname). This is required because the default admin URL has the wrong value (the machine name of the Admin Server is not known at the time of template creation).

You can still start or stop the server through the node manager in Admin Console. WLS Plug-in Does Not Support Changing Ownership of File Sets

The Oracle WebLogic Server plug-in does not support changing the ownership of file sets. The default 'oracle' user must be used or unexpected results, including possible deployment failure, could result. Relocating Node Manager Home Not Supported

You observe an error where servers in an Oracle WebLogic Server cluster cannot start through Node Manager. This error can occur if you have relocated your Node Manager home, which is not supported. Specifically, the node manager configuration at introspection time only occurs when the nodemanager.properties file resides in the <weblogic_home>/common/nodemanager directory. User-specific Changes to Setdomainenv.sh are Not Preserved

If you set any user-specific parameters (such as JAVA_OPTS, PRE_CLASSPATH, or POST_CLASSPATH) in setDomainEnv.sh these settings are lost during the reconfiguration of the domain to Oracle VM.

10.3.3 Oracle Web Cache Issues

This section describes issues for Oracle Web Cache. It includes these items: Protocol Mismatch Error

If Oracle WebCache has been registered with Enterprise Manager and is introspected, the resulting Enterprise Manager registration output cannot be connected to the Oracle WebLogic Server Admin server input due to a protocol mismatch.

The workaround is to manually edit the appliance.xml file for Oracle Web Cache. Under $AB_INSTANCE/catalog/metadata find the appliance.xml file for the Oracle Web Cache component. Edit it and search for the 'EMRegistration' output. Change the protocol from 'HTTP' to 'http'. You should now be able to connect the output to the Oracle WebLogic Server Admin server input. Oracle Web Cache Administration Port Not a Privileged Port

Oracle Virtual Assembly Builder does not support the deployment of an Oracle Web Cache appliance with a privileged port (a port number less than 1024) as its administration port. Oracle Web Cache Scaling Issues

Oracle Virtual Assembly Builder does not automatically update the webcache.xml file for each instance after you perform scaling. Even when the scaling operation completes without errors, you must still update the webcache.xml file for each instance so that the instance recognizes all the members in the cluster. Update Virtual Host Map Properties When Making Port Changes

In Oracle Web Cache, there is not necessarily a correlation between the ports in the virtual host map (VHM) elements and those in the listen elements of the Oracle Web Cache configuration. Whenever you make a port change, you must update your VHM ports by manually updating the properties associated with the VHMs.

10.3.4 Oracle Database Issues

This section describes issues for Oracle Database. It includes these items: Deployment Error Due to Database Vault

If the database vault has been configured in your reference system's database home, you may experience failures during some Oracle Virtual Assembly Builder operations.

In order to avoid any problems, complete these steps:

  1. Before introspection, execute the following command on your system to temporarily disable Database Vault in the database home:

    $ make -f $ORACLE_HOME/rdbms/lib/ins_rdbms.mk dv_off ioracle
  2. Re-start the database on your reference system and then shut it down.

  3. After capturing the file sets, execute the following command on your reference system to re-enable Database Vault in the database home:

    $ make -f $ORACLE_HOME/rdbms/lib/ins_rdbms.mk dv_on ioracle
  4. Re-start the database on your reference system.

  5. After deployment, execute the following command on the new virtual machine to enable Database Vault in the database home:

    $ make -f $ORACLE_HOME/rdbms/lib/ins_rdbms.mk dv_on ioracle
  6. Re-start the database on the new virtual machine. Use default name LISTENER on Reference Systems

During Oracle Virtual Assembly Builder operations, the listener on newly-created virtual machines starts using the default name LISTENER. If you used a different name for the listener on your reference system, you will receive an error. To avoid this error, ensure that you use the default name (LISTENER).

If you must use a different listener name, start your listener manually with the correct name:

$ORACLE_HOME/bin/lsnrctl start <listener name>


To view the correct listener name, see: $ORACLE_HOME/network/admin/listener.ora. Limited Database Configuration Support

The database introspector expects the listeners (the listener.ora configuration) to be configured as follows:

(ADDRESS = (PROTOCOL = TCP)(HOST = example.cm)(PORT = 5521))


The protocol, host, and port are all required, and must appear in the order above. Upgraded 10g Oracle Homes Cannot be Introspected

You cannot introspect a single-instance database Oracle Home if that Oracle Home has been upgraded from Release 10g.

10.3.5 Oracle Forms and Oracle Reports Issues

This section describes issues for Oracle Forms and Oracle Reports. It includes these items: Change nm* Files Ownership

After deploying an assembly, in Oracle HTTP Server, Oracle Forms and/or Oracle Reports deployed virtual machines, change the ownership of the following files to the "root" user:

  • $ORACLE_HOME/bin/nmo

  • $ORACLE_HOME/bin/nmb

  • $ORACLE_HOME/bin/nmhs

Alternatively, you can run $ORACLE_HOME/bin/root.sh as the root user which sets the right ownership on these files.

Not having the ownership set to "root" for these files impacts the Oracle EM Agent's ability to collect performance metrics.

10.4 Documentation Errata

There are no documentation errata at this time.