Home / Middleware / Oracle Virtual Assembly Builder

5 Using Oracle Virtual Assembly Builder

This chapter describes how to use Oracle Virtual Assembly Builder, and includes the following sections:

• Section 5.1, "Oracle Virtual Assembly Builder Interfaces"

• Section 5.2, "Typical Workflow"

• Section 5.3, "Operations Related to Creating an Assembly"

• Section 5.4, "Operations Related to Deployment"

5.1 Oracle Virtual Assembly Builder Interfaces

Oracle Virtual Assembly Builder provides the following user interfaces depending on which parts of the product you have installed:

• When you have installed Oracle Virtual Assembly Builder Studio the following interfaces are supported:

  • Oracle Virtual Assembly Builder Studio graphical user interface

  • abctl, a command-line tool.

  • Oracle Virtual Assembly Builder Studio and abctl interact with Oracle Virtual Assembly Builder Deployer as a Web client. In a suitably configured Oracle Virtual Assembly Builder Studio environment, you can perform deployment through the configured connection to Oracle Virtual Assembly Builder Deployer using either the graphical user interface or abctl.

• When you have installed Oracle Virtual Assembly Builder Deployer the following interfaces are supported:

  • abctl, a command-line tool.

  • A Web service API to interface with Oracle Virtual Assembly Builder Deployer Web service, described in Oracle Virtual Assembly Developer's Guide.

  When only Oracle Virtual Assembly Builder Deployer is installed, you can access only a subset of the commands through the command-line interface (all of the Web service operations are available, however). When Oracle Virtual Assembly Builder Studio is installed, or Oracle Virtual Assembly Builder Studio and Oracle Virtual Assembly Builder Deployer are installed, you can access all the commands. See Appendix A, "Command Line Reference".

Note:

You cannot launch two sessions of either the Oracle Virtual Assembly Builder Studio or abctl interfaces at the same time.

5.1.1 Accessing Oracle Virtual Assembly Builder Studio

Launch Oracle Virtual Assembly Builder Studio by executing the command:

$AB_INSTANCE/bin/abstudio.sh

Where, $AB_INSTANCE is an instance of Oracle Virtual Assembly Builder Studio, in the format ab_instance<instance number>, installed in an Oracle Home.

Figure 5-1 shows Oracle Virtual Assembly Builder Studio.

There are multiple ways to perform operations in Oracle Virtual Assembly Builder Studio. You can use context menus by right clicking on a node, or you can use the main menu options. The Assembly main menu provides assembly related operations, the Appliance menu provides appliance related operations, and the Deploy menu provides Deployer related operations.

Figure 5-1 Oracle Virtual Assembly Builder Studio

Description of "Figure 5-1 Oracle Virtual Assembly Builder Studio"

5.1.2 Accessing the abctl Command-Line Tool

Launch the abctl command-line tool by executing the command:

$AB_INSTANCE/bin/abctl

5.1.3 Accessing Logs

The log file is stored at $AB_INSTANCE/logs/assemblybuilder.log.

Access the log file manually, or view its messages through Oracle Virtual Assembly Builder Studio in the Messages window.

5.1.4 Shutting Down Oracle Virtual Assembly Builder Studio

When you close Oracle Virtual Assembly Builder Studio, if a long running process which interacts with the local catalog is in progress, a warning dialog indicates that operations are in progress. You can decide whether to continue or abort the shutdown. You are recommended to allow the operations to complete before shutdown, to avoid a problem on restart.

5.1.5 Differences Between the Interfaces

The Oracle Virtual Assembly Builder Studio and abctl interfaces complement each other but do not include identical functionality. Here are the main differences:

• When running in Deployer-only mode only the abctl interface is supported.

• Only Oracle Virtual Assembly Builder Studio provides editing capability. That is, the following operations are not supported in abctl:

  • managing file set definitions: updating file set definitions

  • creating/editing a deployment plan

• In Oracle Virtual Assembly Builder Studio, you can introspect multiple reference systems and put the results into a new or existing assembly. In abctl, you must introspect reference systems one-by-one and subsequently add them to an assembly.

• Only abctl provides the ability to create a 'target' connection to an Oracle VM 3.0 environment. Oracle Virtual Assembly Builder Studio does not have a connection wizard.

These differences are further detailed in Section 5.3, "Operations Related to Creating an Assembly".

5.1.6 Naming Rules

Any user-provided names must follow these rules:

• The name must begin with an alphabetic character.

• The name may only contain alphanumeric characters, or the underscore (_) or hyphen (-) characters.

• The name must be 4 to 40 characters long.

5.1.6.1 Naming Conflicts

You may experience a name conflict between appliances or assemblies in a catalog if you import an appliance or assembly into a catalog where you already have an appliance or assembly with the same name. Mixed-case names are allowed, although the Oracle Virtual Assembly Builder catalog is case-insensitive. For example, "myAssembly" and "myassembly" are considered to be the same.

If you want to overwrite the existing appliance or assembly you can use the force option.

5.1.7 Symbolic Links

Symlinks are not supported by Oracle Virtual Assembly Builder, and can lead to errors during introspection, capturing file sets, and deployment. Avoid symlinks in your Linux reference systems.

5.2 Typical Workflow

Users will typically use Oracle Virtual Assembly Builder in these ways:

• Create assemblies and appliances:

  • introspect a reference system to capture the necessary metadata and configuration information for all components that make up the appliances within an assembly.

• Edit assemblies and appliances to configure the relationships among the appliances and any external resources.

  • create networks within an assembly

  • create network interfaces within an appliance

  • bind appliance inputs to network interfaces and bind network interfaces to networks

  • create external resources from an appliance output

• Creating an archive for the assemblies:

  • Create bootable virtual machine disk images with customized Oracle Enterprise Linux operating system distributions and configurable metadata allowing for deploy-time customization of the software component

• Define connections to the backend virtualization system:

  • Define the connection to Oracle VM backend endpoints and add deployment targets in the backend.

• Deploy: deploy the assembly into your environment.

  • create and edit a deployment plan

  • upload assembly archive to Deployer repository

  • register an assembly archive to a target

  • deploy assembly instances

  • perform other lifecycle operations on assembly instances

5.3 Operations Related to Creating an Assembly

This section details how you will use Oracle Virtual Assembly Builder Studio or abctl command line utility to perform operations related to creating an assembly.

• Section 5.3.1.3, "Managing and Discovering Plug-ins"

• Section 5.3.1.4, "Preparing Custom Scripts"

• Section 5.3.1.5, "Preparing Properties"

• Section 5.3.2, "Creating an Assembly"

• Section 5.3.1, "Introspecting Appliances"

• Section 5.3.3, "Creating Templates for an Appliance or an Assembly"

• Section 5.3.10, "Creating an Assembly Archive"

• Section 5.3.4, "Editing an Assembly Using Oracle Virtual Assembly Builder Studio"

• Section 5.3.5, "Editing an Assembly Using abctl"

• Section 5.3.6, "Clearing Assembly Passwords"

• Section 5.3.7, "Copy an Appliance or Atomic Assembly"

• Section 5.3.8, "Export Operations"

• Section 5.3.9, "Rename an External Resource"

5.3.1 Introspecting Appliances

You can introspect one or more appliances into the top-level catalog and optionally include the appliances into an assembly. During introspection, the metadata for appliances is created in the $AB_INSTANCE/catalog/metadata directory. A unique ID (called the capture ID or cid) is generated for each appliance, and is stored in its metadata. In addition, a file set definition is created in the shared area of the catalog.

When you add a shared appliance to an assembly, the metadata is copied and subsequent modifications you make to the shared appliance's metadata (the one shown in the Introspected Components panel of the Assembly navigator) are not reflected in any assembly that has a copy of that same appliance. Similarly, any change you make to the metadata of a copy of a shared appliance do not affect the source instance.

While the metadata is not shared, the file sets and templates associated with the various copies of the appliance are shared between all copies.

Note:

You should not change any configuration or content of the reference system between introspection and capturing file sets, as that may create undesired results. For instance, introspecting a reference system on one date and capturing file sets in the "same" reference system at some arbitrary future date is not supported.

The available appliances supported for introspection are the set of supported Oracle product plug-ins, or a generic product that you capture products generically by taking as input a set of product directories to capture and a set of scripts to run on the appliance instance. You can also capture information to create appliance properties, inputs, and outputs.

The following appliances are supported for introspection:

• Generic Product

• Oracle Coherence*Web (Alias of WLS)

• Oracle Forms Services (Alias of WLS)

• Oracle HTTP Server

• Oracle Real Application Clusters Database

• Oracle Reports (Alias of WLS)

• Oracle Single-Instance Database

• Oracle RAC Database

• Oracle SOA Platform Plugin (Alias of WLS)

• Oracle Traffic Director

• Oracle Tuxedo 11g

• Oracle WebLogic Server

For introspection to succeed, some introspection plug-ins have specific requirements for the reference system's running state. Table 5-1 lists the preconditions for the products supported by Oracle Virtual Assembly Builder.

Table 5-1 Introspection Plug-in Requirements

Introspected Product	Running State Pre-Condition
Oracle WebLogic Server	Administration Server must be up and in the running state (not in the admin state). Managed Server(s) may be up or down.
Oracle Coherence*Web	Administration Server must be up and in the running state (not in the admin state). Managed Server(s) may be up or down.
Oracle Forms*Web	Administration Server must be up and in the running state (not in the admin state). Managed Server(s) may be up or down.
Oracle SOA for WebLogic Server	Administration Server must be up and in the running state (not in the admin state). Managed Server(s) may be up or down.
Oracle HTTP Server (OHS)	No requirement; Oracle HTTP Server may be up or down.
Oracle Single-Instance Database	In the introspection phase, the database can be up or down.
Oracle RAC Database	In the introspection phase, the database can be up or down.
Oracle Reports	Administration Server must be up and in the running state (not in the admin state). Managed Server(s) may be up or down.
Oracle Traffic Director	In the introspection phase, the Oracle Traffic Director application can be up or down.
Oracle Tuxedo	In the introspection phase, the Tuxedo application can be up or down.

5.3.1.1 Introspect Using Oracle Virtual Assembly Builder Studio

The Introspect Appliances wizard (Figure 5-2) is a standalone interface to allow you to introspect appliances into the top-level catalog and select whether to place them into an assembly. To access it, select File > New > Appliance Introspection.

Figure 5-2 Introspect Appliances Wizard

Description of "Figure 5-2 Introspect Appliances Wizard"

Enter the following information:

• Include in Assembly: Select whether to place the appliances into an assembly after a successful introspection. Choose a Parent Assembly from the drop-down list or select Do Not Include in an Assembly.

  If you choose to introspect an appliance into an assembly, the appliance becomes owned by the assembly and cannot be included in any other assembly. These appliances appear in the Introspected Components panel in the Assembly navigator.

  If you do not introspect into an assembly, you can add the resulting appliance to any number of assemblies. These appliances appear in the Introspected Components panel in the Assembly navigator.

  If the assembly does not exist, you can click Create Assembly to open the Create Assembly dialog and create a new assembly; you can then select the new assembly as the target assembly for the introspection.

• On the Appliance tab, configure:

  • Name: name your appliance. The name can be 4 to 40 characters, may not start with a digit, and no spaces or special characters are allowed (underscores are allowed). Assembly and appliance names are not allowed to be localized.

  • Overwrite: If introspecting at the top level, check this box to overwrite any top-level assembly or appliance object, provided that it is not registered.

    If you are introspecting into an existing assembly, checking this box overwrites only assemblies and appliances inside that assembly.

  • Type: select the type of appliance from the list.

  • Capture File Sets: check the box to capture file sets during introspection. You can capture file sets during either introspection or when creating a template. See Section 5.3.3.4, "Capturing File Sets".

  • Description: enter an optional description.

• On the Connection tab tab, configure:

  • Name: enter the name of the host that you want to introspect.

  • Host Name: enter the hostname of the host that you want to introspect. You can use Local Host to introspect locally.

  • Port: enter the port number for connecting to this host. The default port number is 22.

  • Username: enter the username for the SSH user to log into the remote host. This user must have permissions to access the introspected configuration.

  • Authentication: select Password and enter a password or select Private Key to reference the SSH key to use rather than providing a password. If selecting Private Key, select the browse button and navigate to the location of a private SSH key file on the local machine. The use of a private key file provides added security because no password handling is required by Oracle Virtual Assembly Builder.

  • Run As User: enter a name of a user on the remote machine to sudo as before executing operations. For example, if you log in with 'User Name' bob and 'Run As User' jill, the introspection process will run as jill, not bob. In that case, bob must do a sudo operation to jill.

  • Working Directory: enter the path to a directory on the remote host in which Oracle Virtual Assembly Builder may stage files required for introspection. The files may be reused.

  • Cleanup Working Directory: check to remove the artifacts copied over to the Working Directory once the introspection is complete.

  • Test Connection: click the Test Connection button to test if you can successfully connect to the host.

    Note:

    You cannot perform remote introspection of a database if you cannot log into the database machine with the database installation owner's account. If remote introspection is required, you must enable the account for remote access.

• On the Parameters tab, configure the required values for appliance parameters. Depending on the type of appliance chosen, different sets of properties are displayed. Set the properties for that appliance by selecting the cell for the property and entering a value for the property. Required properties are identified with an asterisk. See Appendix B, "Oracle Virtual Assembly Builder Introspection Plug-ins", for information on introspection properties.

5.3.1.1.1 Summary of Appliances for Introspection

Click Finish to begin the introspection.

You can see the progress of the introspection in the Tasks navigator. Oracle Virtual Assembly Builder Studio displays a node for the appliance being introspected. If introspection fails, a red X mark is displayed in the navigator. You can open the task log for the failed task from the Tasks navigator using the View Task Log toolbar button. See also Appendix D, "Troubleshooting".

5.3.1.2 Introspect Using abctl

abctl provides both local and remote introspection capability. For remote introspection, the Oracle Virtual Assembly Builder host must have SSH access to the subject machine.

The -name flag is optional.

Here are two examples:

Example 5-1 Introspect Oracle HTTP Server Remotely

$ ./abctl introspectOHS -oracleInstance /path/to/oi –componentName ohs1 –name myOHS -remoteHost myReferenceSystemHost –remoteUser abdemo  

Example 5-2 Introspect Oracle WebLogic Server Locally

$ ./abctl introspectWLS -wlsHome /path/to/wls/wlserver -domainRoot /path/to/user_projects/domains/basic_domain -adminUser weblogic -name myWLS 

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.3.1.3 Managing and Discovering Plug-ins

Starting with Oracle Fusion Middleware 12c (12.1.2), each product's plugin for Oracle Virtual Assembly Builder is shipped with the respective product's release and laid out in that product's top level installation directory (ORACLE_HOME for Oracle products) at installation time. To allow a plug-in to be used by Oracle Virtual Assembly Builder, you must install the plug-in into the Oracle Virtual Assembly Builder environment. You can add a product plug-in to Oracle Virtual Assembly Builder at any time after installing Oracle Virtual Assembly Builder.

Oracle Virtual Assembly Builder provides a Plug-in Manager to allow you to manage introspection plug-ins, and download and install new Oracle Virtual Assembly Builder introspection plug-ins from a local or remote Oracle Home.

5.3.1.3.1 Managing and Discovering Plug-ins with Oracle Virtual Assembly Builder Studio

The Plug-in Manager dialog allows you to view and manage all the plug-ins in the Oracle Virtual Assembly Builder installation. You can launch a discovery of a new plug-in by clicking the + button on the toolbar, enable or disable plugins by clicking the checkbox for a selected plug-in, or remove a selected plug-in by clicking on the X button. Disabling a base plug-in disables all of its extensions. You can access this dialog by selecting Tools > Introspector Plug-in Manager.

Figure 5-3 Plug-in Manager

Description of "Figure 5-3 Plug-in Manager"

To install a plug-in or extensions from a product home:

1. Launch a discovery of a new plug-in by clicking the + button on the toolbar.

2. Click Next in the welcome page of the Discover Plugins wizard.

3. Specify the connection information for the Oracle Home containing the plug-in:

   • Remote Host or Local Host:

   • If you selected Remote Host, configure the following information:

     • Host Name: Enter the name of the host that you want to introspect.

     • Port: Enter the port number for SSH for this host. The default port number is 22.

     • Username: Enter the username for the SSH user to log into the remote host. This user must have permissions to access the plug-in.

     • Authentication: Select Password and enter a password or select Private Key to reference the SSH key to use rather than providing a password. If selecting Private Key, select the browse button and navigate to the location of a private SSH key file on the local machine. The use of a private key file provides added security because no password handling is required by Oracle Virtual Assembly Builder.

     • Remote Working Directory: Enter the path to a directory on the remote host in which Oracle Virtual Assembly Builder may stage files required for plug-in discovery. The files may be reused.

     • Remote Cleanup: Check to remove the artifacts copied over to the Remote Working Directory once the plug-in discovery is complete.

4. Click Test Connection to verfiy you can successfully connect to the host.

5. Click Next.

6. Enter the Oracle Home or product root directory containing the plug-in(s).

7. Select one or more of the plug-ins to install into your base Oracle Virtual Assembly Builder installation. You can track installation progress through the Task Manager tab.

   Note:

   Some plug-ins may have a dependency on other plug-ins. If the installation of a particular plug-in fails, view the failure in the Task Manager, and reattempt the installation of the failed plug-in once the dependency is resolved.

8. Click Finish.

   You can verify the installation of the plug-ins from the Plug-in Manager.

5.3.1.3.2 Managing and Discovering Plug-ins with abctl

Use the describePlugins command to list the set of installed introspector plug-ins and extensions including their status. Example 5-3 shows the describePlugins command:

Example 5-3 describePlugins Command

$ ./abctl help –command describePlugins
$ ./abctl describePlugins

Use the enablePlugin command to enable the specified introspector plug-in or extension. Example 5-4 shows the enablePlugin command:

Example 5-4 enablePlugin Command

$ ./abctl help –command enablePlugin
$ ./abctl enablePlugin -pn WLS -recurse 

Use the disablePlugin command to disable the specified introspector plug-in or extension. Example 5-5 shows the disablePlugin command:

Example 5-5 disablePlugin Command

$ ./abctl help –command disablePlugin
$ ./abctl disablePlugin -pn WLS

Use the installPlugins command to install one or more plug-ins and extensions from a product home. You may be prompted to enter the password for the remote SSH user when you execute the command. Example 5-6 shows the installPlugins command:

Example 5-6 installPlugins Command

$ ./abctl help –command installPlugins
$ ./abctl installPlugins -productRoot myPath

For more information see Appendix A, "Command Line Reference".

5.3.1.4 Preparing Custom Scripts

Oracle Virtual Assembly Builder supports a common scripting API to provide custom scripts for the following features:

• Custom reconfiguration scripts - you can use the custom reconfiguration scripts feature to add scripts to an appliance that gets created by an existing introspector. For example, "When I capture my WLS installation, I want to add scripts to do additional work beyond what is already done on the VM where WLS is to be deployed."

  At introspection time, the scripts and properties are captured and added to the appliance. The captured scripts are executed alongside the creating plugin and extension on the vServer during the various reconfiguration operations.

• Generic appliance (GenericProd) introspector plug-in scripts - when you do not want to (or cannot) use an existing introspector plugin to capture and deploy a particular product, you can use the GenericProd introspector plugin to simply create an appliance that captures a set of product directories and a set of scripts. The captured product directories are present on the VM at the same location and the scripts are executed to reconfigure the product and start/stop. For example: "No introspector plugin exists for the product I want to capture, but it should be easy to write a few scripts to change the product's configuration to work in different environments.

You can supply one or more scripts to be executed during each of the various reconfiguration operations. The following reconfiguration operations are supported:

• Configuration - Executed during the initial vServer boot. This is where a product will be reconfigured to be usable on the newly deployed vServer.

• Start - Executed after the Configuration operation has completed at initial vServer boot and during all subsequent boots.

• Stop - Executed during shutdown of the vServer. This is where the product should be shutdown gracefully.

• Ping - Executed on demand by external applications to query the status of the deployed product running on the vServer. Only supported by generic appliance.

5.3.1.4.1 Script Root Directory

The script root directory is a top level directory supplied by the user containing zero or more of the following sub-directories:

• A set of sub-directories containing scripts to be executed on the vServer.

• A directory named properties/ that contains one or more property files.

• A directory named endpoints/ that contains one or more endpoint files (only partly supported by custom reconfiguration scripts).

The script root directory need not contain all well-known sub-directories and well-known sub-directories that do exist may be empty.

The names of the script sub-directories vary depending on which scripting feature is being used. How this script root directory is supplied by the user also depends on which scripting feature is being used. See the respective documentation for details.

5.3.1.4.2 Script Sub-directories for Custom Reconfiguration Scripts

Like /etc/rc.d/, each subdirectory will contain a set of one or more scripts which get executed at the appropriate time. The custom script sub-directories have the following well-known names:

• vm-pre-app-config.d/ - executed only at first VM boot (initial deployment)

• vm-post-app-config.d/ - executed only at first VM boot (initial deployment)

• vm-pre-app-start.d/ - executed for all VM boots, follows vm-*-app-config.d/ at first VM boot

• vm-post-app-start.d/ - executed for all VM boots, follows vm-*-app-config.d/ at first VM boot

• vm-pre-app-stop.d/ - executed for all VM shutdowns.

• vm-post-app-stop.d/ - executed for all VM shutdowns.

You can optionally create the /ovab/scripts.d/ root directory and populate it with the set of well-known sub-directories and the scripts you want to execute. At the end of every introspection we check for the existence of this directory on the reference system and (if found) add these scripts to the appliance. Here is an example of a root custom script directory you can create:

/ovab/scripts.d/
    vm-pre-app-config.d/
        00configthis.sh
        01configthat.sh
    vm-post-app-config.d/
        00configotherthing.sh
    vm-pre-app-start.d/
        00startthisfirst.sh
        01startthatsecond.sh
    vm-post-app-start.d/
        00startotherthinglast.sh
    ...

The script sub-directories must only contain scripts that can be executed. The presence of a directory within a well-known sub-directory generates an error during introspection and an appliance is not created.

5.3.1.4.3 Script Sub-directories for Generic Appliance Scripts

Each sub-directory may contain a set of one or more scripts which get executed at the appropriate time. The script sub-directories must have the following well-known names:

• vm-app-config.d/ - executed only at first VM boot (initial deployment)

• vm-app-start.d/ - executed for all VM boots, follows vm-app-config.d/ at first VM boot

• vm-app-stop.d/ - executed for all VM shutdowns

• vm-app-ping.d/ - executed on demand from external applications

Here is an example of a root script directory that you can create:

/my/root/scriptdir/
    vm-app-config.d/
        00configthis.sh
        01configthat.sh
    vm-app-start.d/
        00startthisfirst.sh
        01startthatsecond.sh
    vm-app-stop.d/
        00stopthis.sh
    ...

The script sub-directories must only contain scripts that can be executed. The presence of a directory within a well-known sub-directory generates an error during introspection and an appliance is not created.

5.3.1.4.4 Script Execution

Scripts under each sub-directory are captured during introspection and stored with the appliance. During reconfiguration operations the appropriate set of scripts according to the requested operation are executed sequentially, in sorted order.

All scripts are executed as the root user to provide the flexibility of performing operations requiring root privileges or switching to another user as necessary.

All scripts must exit with a zero exit status upon success. Any script exiting with a non-zero exit status results in the failure of the operation. The operation blocks as each script executes and waits for the script to exit before continuing. The script must complete execution and exit in a timely manner.

The standard out (stdout) and standard error (stderr) output from each executed script is redirected and appended to a script-specific console log file on the VM within the $AB_INSTANCE/logs directory. The name of the console log is generated from a combination of the script name and the script sub-directory name as follows: <script-subdir-name>_<script-name>.log

5.3.1.4.5 Script Environment

The following environment variables are set in the execution environment of all scripts:

• $AB_PROPFILE_DIR: The directory containing the property files added to the appliance and modified according to the metadata in the reconfiguration environment.

• $AB_ENDPOINT_DIR: The directory containing the endpoint files generated from the metadata in the reconfiguration environment.

• $AB_CLI: The full path to the Oracle Virtual Assembly Builder command line utility available to scripts executed on the vServer.

The current working directory in the environment is undefined and should not be relied upon during script execution.

The presence of other environment variables depends on which scripting feature is being used. See the respective documentation for details.

5.3.1.4.6 Property Directory

The script root directory may contain a properties/ sub-directory. If a properties/ directory exists then all files in the directory will be captured and added to the appliance.

Files with a <filename>.userprops or <filename>.pwprops naming scheme are parsed as a property file. The <filename> part must not contain ':' as this character will serve as a delimiter in property name generation. Files within the properties directory that do not conform to the above naming schemes are blindly copied without parsing.

When the property files are obtained from the 'properties/' directory the property names are modified as they are added to the appliance as follows:

<prefix>:<filename>:<propertyname>

During deployment the properties are written back out to the property file(s) using their original names, including the values as edited within the appliance or overridden in the deployment plan. The properties files may be accessed by scripts during execution using the $AB_PROPFILE_DIR environment variable.

5.3.1.4.7 Property Files

A property file must consist of zero or more lines where each line must be a property declaration, a comment, or a blank line. Property declarations take the form of <name>=<value> and must be contained on a single line. Ending a line with '\' will not result in line continuation. Property names may contain only letters, digits, '_' (underscores), '.' (periods), and '-' (dashes).

Each property in a property file is added as a user property into the appliance. Like any other user property, you can edit these properties in the generated appliance and override them in deployment plans.

All properties in '.userprop' files are added as type "STRING". All properties in '.pwprop' files are added as type "PASSWORD" and supplied values must be the encrypted form. See Section 5.3.1.4.10, "Encryption Support" for instructions on how to obtain the encrypted form of a value.

All properties are marked as 'required' in the appliance metadata. Property declarations without any assigned value (nothing after '=') are set to null in the appliance metadata, requiring that the user assign a value to that property prior to deployment.

5.3.1.4.8 Endpoint Directory

The script root directory may contain an endpoints/ sub-directory. This sub-directory may contain files describing an ApplianceInput and ApplianceOutput to be added to the appliance as part of introspection. An ApplianceInput represents a product's configuration related to the the host and port on which the product listens and accepts connections. An ApplianceOutput represents a product's configuration related to the host and port on which the product initiates connections to other products (or to instances of itself on other machines).

Each endpoint is described in a separate file with the following naming strategy:

• For ApplianceInput: <input-name>.input

• For ApplianceOutput: <output-name>.output

Note:

Only GenericProd plugin can supply an endpoints directory during introspection for creations of endpoints. Both features have access to the endpoints directory created on the vServer for use during reconfiguration operations.

During reconfiguration, endpoint files are created for all ApplianceInput and ApplianceOutput of the appliance. In addition, files are created for all ApplianceInput of other appliances to which the appliance is connected.

5.3.1.4.9 Endpoint Files

t The custom reconfiguration scripts feature cannot create endpoint files. The feature can only create read endpoint files created by the underlying plugin that created the appliance. By contrast, generic product can both create endpoint files at introspection, and read endpoint files (during reconfiguration operations).

The *.input/*.output files are comprised of properties expressed as key/value pairs, one per line, with the form of <key>=<value>. The keys are not guaranteed to be valid shell variable names so endpoint files cannot be sourced to create shell variables.

The following properties can be contained in *.input files:

- port : required
- protocols : required, comma separated list with no whitespace
- host : derived internally, available at rehydration userprop.
- userprop.<property-name> : optional, always type='STRING'
- pwprop.<property-name> : optional, always type='STRING'
- sysprop.<property-name> : optional, always type='STRING'
- original-port : optional
- original-host : optional

Properties denoted as 'required' must be specified in the files supplied at introspection. The 'host' property should not be specified by the user and is instead derived automatically during rehydration. Rehydration scripts should use the value of the 'host' property to set the listening address when configuring an ApplianceInput and to set the connection address when configuring an ApplianceOutput.

The following properties can be contained in *.output files:

- protocol : required
- connected-input : derived internally, available at rehydration
- userprop.<property-name> : optional, always type='STRING'
- pwprop.<property-name> : optional, always type='PASSWORD'
- sysprop.<property-name> : optional, always type='STRING'
- original-port : optional
- original-host : optional
- conn-userprop.<property-name> : optional
- conn-pwprop.<property-name> : optional
- conn-sysprop.<property-name> : optional

Properties denoted as 'required' must be specified in the files supplied at introspection.

All 'userprop.*' properties are endpoint user properties.

All 'sysprop.*' properties are endpoint system properties.

All 'pwprop.*' properties are endpoint user properties of type PASSWORD and must be supplied in encrypted form and will be returned in encrypted form. See Section 5.3.1.4.10, "Encryption Support" for instructions on how to obtain the encrypted form of a value.

The properties with the 'conn-' prefix are connection properties and they are for specifying requirements on connected inputs. An input is only compatible with a given output if it supports the protocol of the output and has the user and system properties that the output names in its connection properties. This is enforced when creating connections in appliance metadata. Omitting this information may permit the output to be associated with an incompatible input.

The original-host and original-port properties are useful in determining which inputs were connected to which outputs in the case where the inputs/outputs of appliances captured separately were originally connected to each other and need to be reconnected in appliance metadata.

The 'connected-input' property should not be specified by the user and is instead derived automatically during rehydration. Rehydration scripts should use the value of the 'connected-input' property to derive the name of the *.input file by appending '.input' to the name. The filename indicated by the connected-input property will take the form of:

<assembly-path>.<input-name>

where each component of <assembly-path> is separated by a '.' (period).

This input file just like any other *.input file but it is for another appliance and therefore prefixed with the assembly-path to avoid input name collision. For example, take an appliance at path 'mySite/otherAppliance' which has input 'otherInput' which is connected to an output named 'output1' on a target GenericProd appliance. The connected output file, 'output1.output' would contain the following property:

connected-input=mySite.otherAppliance.otherInput

The *.input file representing 'otherInput' would be located at the following full path (alongside all other *.input/*.output files):

$AB_ENDPOINT_DIR/mySite.otherAppliance.otherInput.input

5.3.1.4.10 Encryption Support

To prevent the storage of cleartext passwords on disk all password properties must be supplied in encrypted form. During rehydration the password properties (which may have been modified during assembly editing or by deployment plan) are written back out to the property files also in encrypted form. OVAB provides an encryption utility for use during property file creation and a decryption utility for scripts to invoke during rehydration operations.

You can use the encryptProperties command of the abctl interface to encrypt password values during property file creation:

abctl encryptProperties -propertyNames String ... [-outputFile String]

Example execution with three properties, applied to pre-existing file with replacement of myprop3 property:

% abctl encryptProperties -propertyNames myprop1 myprop2 myprop3 -outputFile allmysecrets.pwprops
Enter value for property 'myprop1':
Confirm entered value for property 'myprop1':
Enter value for property 'myprop2':
Confirm entered value for property 'myprop2':
Enter value for property 'myprop3':
Confirm entered value for property 'myprop3':
 
Changes applied to pre-existing file 'allmysecrets.pwprops'.
Added property 'myprop1'.
Added property 'myprop2'.
Replaced property 'myprop3'.

During script execution the 'decryptProperty' command of the utility indicated by the $AB_CLI environment variable may be used to decrypt property values:

$AB_CLI decryptProperty -encryptedValue String

Example execution from a script:

# encrypted value already obtained from property file
 
# execute decryption utility and store value in variable
THE_PASSWORD=$($AB_CLI -encryptedValue $THE_PASSWORD_ENCRYPTED)
 
# now ready to use $THE_PASSWORD to reconfigure a product

Use the standard help facility, abctl help <command> in the source environment to learn about the encryptProperties command. Use the $AB_CLI help <command> on the vServer to to learn about the decryptProperty command.

5.3.1.4.11 Additional Property Support

Other components, especially in the case of custom reconfiguration scripts, may create properties in the appliance that need to be fetched during script execution. Since these values were not originally supplied from a property file they are not present in any of the property files during reconfiguration. You can fetch these properties directly from the appliance metadata. Your scripts can use the getProperty command of the $AB_CLI utility during rehydration operations:

$AB_CLI getProperty -propertyName String [-parentAssembly] [-systemProperty] [-instanceId String]

The Deployer delivers to the VM certain configuration parameters that influence the behavior of reconfiguration operations. These parameters are separate from the appliance metadata but may be useful in rare cases to scripts. The getConfigParam command of the $AB_CLI utility may be used by scripts during reconfiguration operations:

$AB_CLI getConfigParam -paramName String [-instanceId String]

5.3.1.5 Preparing Properties

This feature allows an introspection to pick up properties from one or more property file on the reference system during introspection, and for those properties to be added to the resulting appliance/assembly as user properties so they can be edited.

During deployment, the set of original properties including any modifications by the user are made available to scripts provided by the user to perform custom processing based on those properties.

5.3.1.5.1 Properties Directory

The properties directory is supported only for the custom reconfiguration scripts feature, and not for the generic appliance introspection scripts.

To get property files picked up automatically during dehydration, you can place the property files in the well-known directory:

/ovab/scripts.d/properties/

This directory must reside on the same machine as the underlying product that is being captured. Within that directory, property files must conform to the following naming scheme:

<filename>.userprops

The <filename> must not contain ':' as this character will serve as a delimiter in property name generation.

Files within the properties directory that do not conform to the above naming scheme will be blindly transferred with the Appliance without reading it to generate additional user properties. This allows the user to provide additional files that may contain internal properties or other information to aid in the processing of user properties during reconfiguration.

5.3.1.5.2 Property File

A property file must consist of zero or more lines where each line must be a property declaration, a comment, or a blank line. More formally, a property file must comply with the following syntax:

property-file   = *line
line            = prop-decl | comment | blank-line
prop-decl       = name "=" value NL
comment         = *WS "#" *CHAR NL
blank-line      = *WS NL
name            = <any character in "a".."z", "A".."Z", "0".."9", "_", "-", ".">
value           = *XATTRCHAR
XATTRCHAR       = <any CHAR, escaped as necessary for XML element attribute interpretation>
CHAR            = <any character, excluding CTL (and NL), but including WS>
CTL             = <any control character (octets 0 -31) and DEL (127)>
NL              = <platform dependent line termination sequence>
WS              = <white space character>

Any property file that does not comply with the above syntax rules will result in an error and an appliance will not be created.

Property declarations must be contained on a single line. Ending a line with "\" will not result in line continuation.

All properties will be marked as "required" in the appliance metadata. Property declarations without any assigned value (nothing after "=") will be set to null in the appliance metadata requiring that the user assign a value to that property prior to deployment.

Whitespace is not permitted anywhere to the left of "=" in a property declaration. Whitespace to the right of "=" is assumed to be part of the intended value and will be preserved.

Comments and blank lines are preserved at dehydration and will be reproduced when the file is regenerated at rehydration.

5.3.1.5.3 Property Names

Each *.userprops file in the properties directory will be read and an appliance user property will be generated for each property in each file. Property names will be modified by adding a prefix to designate that the property is a custom property and that the property belongs to a specific properties file as follows:

• For custom reconfiguration scripts:

  custom:<filename>:<propname>

• For generic product appliances:

  generic:<filename>:<propname>

The <filename> part comes from the properties filename with the ".userprops" suffix removed. The <propname> part is copied directly without modification from the property name found in the property file.

The user, during editing, will see the entire property name. At reconfiguraiton when the property files are recreated, the "custom:<filename>:" prefix will be removed and will not appear in the property files (that is, the property names originally found in the files will be preserved in the recreated files).

5.3.1.5.4 Property Values

As indicated in the Property File section above, property values must conform to the requirements of XML element attributes. Any necessary escaping of characters in property values is the responsibility of the user when creating property files.

5.3.1.5.5 At Deployment

During reconfiguration, the user properties in the appliance will be traversed and all properties with a "custom:<filename>:" prefix will be added to a properties file under the indicated filename (with ".userprops" suffix added).

The order of properties and the comments within the original properties file are preserved in the regenerated properties file.

All generated properties files will be placed into the same directory. The full path to that directory will be passed to all reconfiguration scripts as an environment variable with the following name:

$AB_PROPFILE_DIR

5.3.2 Creating an Assembly

You can create a new empty assembly by selecting File > New Assembly. You can can add existing appliances to the assembly using the assembly editor, or introspect appliances into an assembly as described in Section 5.3.1, "Introspecting Appliances".

Configure the following fields for the assembly:

• Name: enter a name for the new assembly in the Assembly Name field.

• Overwrite: if an appliance or assembly with the same name already exists, and it has not been registered, you may overwrite it by checking the Overwrite checkbox.

• Description: optionally, enter a text description.

• Default Vnet Name: enter a name for a default Vnet (virtual network) to be created for this assembly. You can connect one or more NICs or vNICs to the Vnet.

Click OK to create the assembly.

5.3.3 Creating Templates for an Appliance or an Assembly

Template creation generates virtual machine templates that are ready to be deployed into virtualized platforms. In Oracle Virtual Assembly Builder, Oracle VM is the only supported platform. Oracle Virtual Assembly Builder supports Oracle Enterprise Linux guest OS for all appliances.

To create a template, you must provide a system base image that contains the operating system. You may create your own system base image if the sample system base image does not meet your needs.

If a product that is introspected contains files encoded with a specific character encoding, ensure that the system base image you use to create templates for the resulting appliance(s) contains the needed character encodings.

Oracle Virtual Assembly Builder provides a sample system base image for Oracle Enterprise Linux templates. When creating Oracle Enterprise Linux templates, Oracle Virtual Assembly Builder transparently invokes Oracle VM's modifyjeos tool to create the virtual machine templates. The tool allows you to modify or customize the base image (for example, adding disk space to the base image, or specifying certain RPMs). Refer to "System Base Images" in Oracle Virtual Assembly Builder Installation Guide for details on how to create a custom system base image.

5.3.3.1 Base Image Validation

Introspector plug-ins can express prerequisites for base images to be enforced at template creation time. Plug-ins can specify the behavior on a failed check - either an error (which causes the template creation to fail), or a warning (which is presented to you but allows the template creation to proceed).

5.3.3.2 Storage of Templates

Templates are stored in the Oracle Virtual Assembly Builder instance's catalog directory. Template creation must be done on an Oracle Virtual Assembly Builder Host, where Oracle VM's modifyjeos is installed.

Note:

Base images are stored in either $AB_INSTANCE, or in $ORACLE_HOME. Here is the order of precedence for base image detection:

• location specified by -baseImage flag

• $AB_INSTANCE/templates/baseImage/OVM/OEL

• $ORACLE_HOME/templates/baseImage/OVM/OEL

5.3.3.3 Creating Templates Using Oracle Virtual Assembly Builder Studio

This operation allows you to create templates for an appliance. Select View > Appliances to view the available appliances. Right click an appliance and select New > OVM Appliance Template.

In the Configure Base Image Options page, choose the base image that serves as the default for the templates. Configure the following fields:

• Assembly Level Base Image Path: Specify a location for the base images by selecting the platform default, or by choosing a custom base image.

• Use the Platform Default: select if you want to use the default base image.

  • When configuring the OEL base image for Oracle VM the default location is: $AB_INSTANCE/templates/baseImage/OVM/OEL.

• Choose a Custom Base Image: select if configuring a custom base image. Click the browse icon, navigate, and select the base image.

• Include Root Password in Template: check to include the OS Root password in the template, and enter the password.

Click Next to continue.

5.3.3.4 Capturing File Sets

Capturing file sets takes the file set definitions generated from introspection, archives these file sets into one or more zip (or other raw) files and stores the resulting files in the shared area of the catalog.

For the capture to succeed, some plug-ins have specific requirements for the reference system's running state. Table 5-2 lists the preconditions for the products supported by Oracle Virtual Assembly Builder.

Table 5-2 Capture Plug-in Requirements

Introspected Product	Running State Pre-Condition
Oracle WebLogic Server	Administration Server must be up and in the running state (not in the admin state). Managed Server(s) may be up or down.
Oracle Coherence*Web	Administration Server must be up and in the running state (not in the admin state). Managed Server(s) may be up or down.
Oracle Forms*Web	Administration Server must be up and in the running state (not in the admin state). Managed Server(s) may be up or down.
Oracle SOA for WebLogic Server	Administration Server must be up and in the running state (not in the admin state). Managed Server(s) may be up or down.
Oracle HTTP Server (OHS)	No requirement; Oracle HTTP Server may be up or down.
Oracle Single-Instance Database	In the introspection phase, the database can be up or down.
Oracle RAC Database	In the introspection phase, the database can be up or down.
Oracle Reports	Administration Server must be up and in the running state (not in the admin state). Managed Server(s) may be up or down.
Oracle Traffic Director	In the introspection phase, the Oracle Traffic Director application can be up or down.
Oracle Tuxedo	In the introspection phase, the Tuxedo application can be up or down.

5.3.3.4.1 Capturing File Sets Using Oracle Virtual Assembly Builder Studio

Configure the file sets for the appliance in the Configure New Appliance Templates page. The file sets that appear are configured by the introspector plug-in (at this point they are read-only).

The introspector plug-in defines whether a file set is shared or local. It also defines whether or not:

• a file set can be edited (whether the user can change the properties of the file set)

• a shared file set can be switched to a local file set and vice-versa

These controls are independent of one another. The File Set dialog ensures the definitions of the introspector plugin are followed. For example, if a file set is not editable, but the shared state is editable (a shared File Set can be made local, etc.), all the fields except the shared/local radio buttons are read-only. However, the flags (Editable and Shared Editable respectively) are shown in the Property Inspector.

You can add file sets. For example, in Oracle HTTP Server there is a DocumentRoot path, and you may want to capture this file set.

File Set Details

Configure these parameters for a file set:

• Name: Enter a name for the file set.

• Root Directory: Enter a root directory.

• OS Owner and OS Group: For each file set, a you can specify an OS owner and group. The product makes no guarantees that the owner and/or group is defined in the base image. During deployment, the file set is expanded with the owner and group specified. The owner and groups defaults to "oracle."

• Exclusions: For each file set you can specify multiple locations under the root directory that should not be captured. The locations are relative to the root directory. The following patterns are allowed in the exclusions:

  • a literal path, for example foo/bar

  • any * in a trailing file/directory name, for example:

    • foo/bar/*

    • foo/bar/*.log

    • foo/bar/tmp.*

    The difference between foo/bar and foo/bar/* is that foo/bar removes bar, whereas foo/bar/* removes everything under foo/bar, but not foo/bar itself.

Note:

The base image must have the owners and groups defined.

Capture File Set

Creates a directory where you can capture the file set definition in this file set. The file set definition is the set of instructions used to build a file set. Both local and remote file sets can be captured if the file system type allows it. See "File System Type".

Shared File Sets

You can configure each file set as either shared or local. If shared, users may or may not decide to capture the file set. In some cases a file set may not be allowed to migrate from local to shared or vice versa. This is defined by the introspector plug-in that created the initial file set and Oracle Assembly Builder Studio follows that setting.

You can also specify mount options for a shared file set. This occurs only in the property inspector view during deployment plan editing.

File System Type

You can specify the free space size for a given file set. Each file set can have a defined free space. This value is set on a file set by file set basis. For local file sets, you can also elect to not capture the file set, and create an empty space on the VM.

Select the file system type. For local file sets, valid choices are:

• Linux

  • Can capture a file set

  • Can define free space

For Shared File Sets, valid choices are:

• NFS

  • Can capture a file set

  • Cannot define free space

• RAW

  • Cannot capture a file set

  • Can define free space

• Native

  • Can capture a file set

  • Can define free space

Define Free Space for a File Set

Define a free space for the given file set. Select Megabyte, Gigabyte, or Percent for the free space unit, and enter a value.

The free space unit can only be defined as Percent if the file set is captured. A Native file system type cannot use Percent because Native can never capture a file set.

Validate Base Image

In the Validate Base Image page, you validate that the base image for each appliance meets minimum requirements. The page displays the results of validation. A successful validation allow you to continue. An unsuccessful validation specifies the missing requirements.

Summary

The Summary page displays a summary of the template that you will create. Click Finish to start the template creation.

Note:

Creating templates can be time and resource (disk and network I/O) intensive. Depending on how many templates are being created this could take more than an hour to complete. Verify the actions outlined, and click Finish to start the process.

To accurately get the progress of a particular task, use the task log. To view a task log for a particular task, select the task from the Task viewer and click the View Task Log toolbar button on the Tasks navigator.

5.3.3.4.2 Capturing File Sets Using abctl

The introspect* commands in abctl currently capture file sets at the end of introspection by default. This can be overridden with a flag to allow separate capture of file sets via the captureFileSets command.

abctl provides both local and remote file set capture capability. For remote file set capture, the Oracle Virtual Assembly Builder host must have SSH access to the subject machine.

Here are two examples:

Example 5-7 Capture File Sets for Oracle HTTP Server Remotely

$ ./abctl captureFileSets –name myOHS -remoteHost myReferenceSystemHost –remoteUser abdemo

Example 5-8 Capture File Sets for Oracle WebLogic Server Locally

$ ./abctl captureFileSets -name myWLS -force

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command along with a sample output of the command.

The Summary window lists all the templates that will be created after you click Finish. It also shows a warning that creating templates can take some time.

5.3.3.5 Creating Templates Using abctl

Example 5-9 through Example 5-10 are createTemplate command examples:

Example 5-9 create Oracle VM Guest OS template for Oracle WebLogic Server

$ ./abctl createTemplate -name myWLS -platform OVM

Example 5-10 create Oracle VM Guest OS template for OHS

$ ./abctl createTemplate -name myOhs -platform OVM -baseImage /private/baseImage/OVM/OEL/System.img

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.3.4 Editing an Assembly Using Oracle Virtual Assembly Builder Studio

This section describes how to edit an assembly, using Oracle Virtual Assembly Builder Studio. After creating an assembly, you may need to edit the assembly before it can be deployed to create connections, and optionally, to make other changes.

Note that once you have created an assembly archive you cannot edit the assembly (that is, create connections, or modify properties of appliances contained in the assembly, and so on).

5.3.4.1 Connecting Appliances

Managing connection configuration includes the connecting of inputs to outputs, setting or changing the property values of inputs and outputs (such as JDBC connection strings), and creating external resource appliances for those outputs that connect to components not deployed as part of the assembly.

Defining a connection means generally to connect an output to an input and set/modify the properties of the input and output as necessary. The "connect output to input" step can be achieved by either connecting an output of an appliance to an input of another or connecting an output of an appliance to the input of an external resource appliance.

All input/output properties that require values must have values set and all outputs must be connected to either an input or an external resource before you can create an assembly archive. Inputs do not need to be connected. All other properties may also need to be set/modified according to the environment that will be in place at deployment time.

For example:

• Configure Web server port forwarding: select an output on myohs and connect it to a Managed Server input on the mywls assembly by drawing an arrow between the two.

• Specify JDBC connect strings for each JDBC connection: open the JDBC output of an Oracle WebLogic Server assembly by selecting it.

  Figure 5-4 Connecting Appliances

  
  Description of "Figure 5-4 Connecting Appliances"
  
  

  For JDBC connections, you either create external resources or introspect the database, then make the connection between the JDBC output of Oracle WebLogic Server to the external resource or the introspected database appliance.

  Each of the JDBC connections has a different description. Use that description to figure out which JDBC database schema to connect each to. For each of the JDBC entries, you can look at the original-url, and then copy the hostname and global-db-name, into mydb.

  For example: in jdbc:oracle:thin:@machine999.example.com:1521/orcl, the hostname is machine999.example.com, the port 1521, and the global-db-name orcl.

  Also specify the global-db-name and port as properties of the external database resource input, and the host as a property of the database appliance itself.

  The port is a property of the external database resource input. The hostname is the only property that belongs to the database external resource itself.

  Note:

  Appliance-specific connection information is described in Appendix B, "Oracle Virtual Assembly Builder Introspection Plug-ins"

5.3.4.2 Auto-wiring

You can enable or disable auto-wire suggestions on the editor toolbar. If disabled, then no suggestions are shown. If enabled then suggestions are shown in two different ways.

The Suggest Wiring Toolbar Button only shows the suggested wiring when you select an output. It shows all the valid connections to different valid inputs. A valid input is the one which follows the same protocol as the output. Oracle Virtual Assembly Builder provides only one suggestion for a given output. The suggestions appear as soon as the output and input both exist on the canvas, after a drag and drop operation for example.

To accept a suggestion, you can right-click on the output, input, or suggestion and select Accept Suggestion. Suggestions only appear for unbound outputs.

If you select an unbound output, then one dashed wire is drawn for each potential legal connection. Each potential legal connection is colored gray but if a suggestion exists, it will still be in the list as black. When you select a suggested wiring and right click on it, the Accept option is presented. If you click on the Accept button, a new connection is created (bound).

5.3.4.3 Property Inspector

You may not need to make changes to properties if the values from the reference system are appropriate. If required, make changes using the property inspector.

The property inspector (Figure 5-5) displays the property values. Properties are grouped in the property inspector during assembly editing and deployment plan editing. Set the properties as required.

Figure 5-5 Property Inspector

Description of "Figure 5-5 Property Inspector"

5.3.4.4 Structure Pane

The Structure Pane is populated whenever you select an element, such as an assembly, Deployer artifacts such as targets, assembly instances, and appliance instances (Figure 5-6). When you select an assembly, the Structure Pane (Figure 5-7) shows the structure of that assembly, including all appliances as well as those appliances' inputs, outputs and network interfaces. Selecting an item on the structure pane populates the property inspector with the properties scoped to that specific selection.

Figure 5-6 Selecting an Element

Description of "Figure 5-6 Selecting an Element"

Figure 5-7 Structure Pane

Description of "Figure 5-7 Structure Pane"

5.3.4.5 Task Viewer

A task viewer shows the a description and status of all asychronous operations, or tasks, you have launched from the same Oracle Virtual Assembly Builder Studio session. Each task is displayed in the task viewer, a dockable pane positioned at the lower middle of the main frame.

During their lifetime, tasks progress through a sequence of states which you can observe in the viewer. Task states are described in Table 5-3.

Table 5-3 Task States

State	Icon or progress bar	Description
Pending	Clock icon	Initial state. Not observable for tasks that run immediately when created.
Running	Active progress bar	Entered from the PENDING state.
Cancelling	Active progress bar with the word “Cancelling…” in background	Entered from the RUNNING or PENDING state. May not be observable if task responds very rapidly to cancellation.
Cancelled	Red circle with icon	Final state. Entered from the CANCELLING state. May not be entered if task does not respond to cancellation, that is, the task may succeed or fail after an attempted cancellation.
Failed	“X” on circular red background	Final state. Entered from the RUNNING or CANCELLING state.
Succeeded	Green check mark	Final state. Entered from the RUNNING or CANCELLING state.

Table 5-4 describes the information displayed for each task.

Table 5-4 Task Viewer

State	Description
Description	A logical description of the task in progress. For example "Create template for ohs64."
Status	The current state of the task. This column displays the icon or progress bar as described in Table 5-3. If the task has a deterministic number of steps, or a percentage of progress is available, the progress bar represents the completed steps or percentage.
Started	The local time at which the task entered the RUNNING state.
Elapsed	The total time elapsed since the task entered the RUNNING state.
Completed	The local time at which the task reached a final state (SUCCEEDED, FAILED, or CANCELLED).

5.3.4.5.1 Viewing a Log of the Tasks Actions

You can view a log of the task's actions and progress by selecting the task (row) and clicking the “text” icon in the toolbar. Viewing the messages opens up a text editor in the canvas area and presents the messages associated only with that task. You can also open the task's log by double clicking the task's row in the table.

5.3.4.5.2 Filtering Tasks

You can filter the list of displayed tasks based on their state. You can independently hide tasks in the , CANCELLED, SUCCEEDED and/or FAILED states using the latching toolbar buttons. If hidden, the task viewer does not show any tasks in that state.You cannot filter tasks in the PENDING, RUNNING, or CANCELLING states.

5.3.4.5.3 Deleting a Task

You can delete any task in a final state by selecting the task (row) and clicking the red “X” icon in the toolbar, or using the delete key.

5.3.4.5.4 Cancelling Tasks

You can attempt to cancel a task by selecting the task (row). If the task supports cancellation, you can then click the "stop" (red block) icon in the toolbar. If the task does not support cancellation, the stop icon is disabled.

The type of tasks you can cancel include:

• Create assembly archive

• Capture file set (both local and remote)

• Create OEL template

• Import (both from directory and from assembly archive)

5.3.4.6 File Set Definition Editor

You can add, edit, and delete file sets from the structure pane. To perform a file set definition action, right click on the file set, or the file set folder for a given appliance in the Structure pane.

You can click on a file set to view the properties in the property inspector. You can right click a appliance and select New > File Set to create a file set definition. You can also right click on an individual file set to select the Open or Delete options. If the file set is editable, you will be able to modify properties in the dialog. If not, the properties will be read only.

To create, edit or delete a file set definition:

• The top-most parent assembly for the appliance must not have an assembly archive.

• If the appliance is shared, (that is, its binaries are used across multiple assemblies) and no containing top-level assembly has an assembly archive.

If the appliance already contains a template or has already had its file sets captured, but is not part of any assembly with an assembly archive, you are warned that any changes will cause that appliance's (or appliances' if shared) templates and file sets to be deleted should you accept the changes. You can also view the state of the file set (whether or not it is packaged and whether it is a system file set or a user file set).

5.3.4.7 Editing Assemblies Containing Oracle HTTP Server/Oracle Web Cache and Oracle WebLogic Server

If you have an assembly that contains Oracle HTTP Server/Oracle Web Cache and Oracle WebLogic Server with Enterprise Manager deployed, as part of deployment of Oracle HTTP Server/Oracle Web Cache "opmnctl registerInstance" is called to register that appliance with an Enterprise Manager application hosted in Oracle WebLogic Server. To enable this operation to complete successfully, you must perform the following steps while editing the assembly:

1. Define connections between Oracle HTTP Server/Oracle Web Cache's EMRegistration output and Oracle WebLogic Server.

2. Use the property inspector to set the Oracle HTTP Server/Oracle Web Cache dependency on Oracle WebLogic Server. You can do this by selecting the Dependency drop-down menu in the General section.

   Without this configuration, Enterprise Manager registration will fail because the Administration Server has not been started.

3. Verify that the WebLogic Server Administration Server has not been configured to accept only SSL connections. The "opmnctl registerInstance" does not support SSL connections to WebLogic Server.

5.3.4.8 Application Routing between Oracle HTTP Server and Oracle WebLogic Server

If the Oracle HTTP Server configuration file mod_wl_ohs.conf defines application routing between Oracle HTTP Server and Oracle WebLogic Server, you need to connect Oracle HTTP Server to Oracle WebLogic Server in the editor.

5.3.4.9 Creating Vnets within an Assembly

When an assembly is created, a default Vnet is created for the assembly. You can change the name and description of the default Vnet when you create the assembly. Once the assembly is created, you may also create additional Vnets other than the one created by default.

To create a new Vnet right-click the assembly and choose New > Vnet... or select the assembly and right-click the Vnets folder in the Structure Pane and choose New Vnet... from the context menu (Figure 5-8). Enter the name and description of the new Vnet.

Figure 5-8 Create Vnet

Description of "Figure 5-8 Create Vnet"

5.3.4.10 Creating Network Interfaces within an Appliance

Each appliance must have at least one network interface and each network interface may have zero or more virtual network interfaces. When the appliance is deployed to a vServer each network interface defined on the appliance will correspond to a network interface on the vServer. To create interfaces:

• Create a physical network interface by right clicking on an appliance in the assembly editor and selecting New Network Interface, or by selecting the assembly in the Assembly navigator and right clicking on the appliance or the Network Interfaces folder under an appliance and selecting New Network Interface.

• Create virtual network interfaces by right-clicking on a physical network interface and choosing New Virtual Interface. You are prompted for the name and description of the new interface. Set the other properties using the Property Inspector. The result is displayed in the Structure Pane as the child of the physical network interface. Virtual network interfaces exist to model the concept of VLAN.

5.3.4.11 Binding Network Interfaces to Vnets

Assemblies and appliances have Vnets and network interfaces. Each network interface may be bound to one and only one Vnet. The deployment plan is used to associate Vnets and network interfaces with physical networks and IP addresses that exist in the deployment environment.

The binding can be changed to a different Vnet (if a different one exists) through the Property Inspector. Each logical network must be resolved at deploy time using the deployment plan (that is, each network will have properties in the deployment plan).

5.3.4.12 Binding Appliance Inputs to Network Interfaces

When configuring an appliance Input you need to specify the network interface and port on which the Input will receive (or listen for) data. You can either select a specific network interface, in which case the Input will only listen for inputs coming from that network interface or you can specify INADDR_ANY in which case the Input will listen for inputs coming from any network interface configured for the appliance. INADDR_ANY is the default.

To set the default interface on an appliance: right-click the interface in the Structure Pane and choose Set as Default from the context menu. The default may be either a virtual or a physical interface. Note that virtual interfaces do not appear in the Assembly Editor. They may only be selected in the Structure Pane.

5.3.4.13 Creating External Resources from an Appliance Output

Create an external resource by right-clicking on an unconnected appliance output in the assembly editor, and selecting New External Resource, or selecting a button on the toolbar in the canvas.

The Create External Resources dialog populates with all the unbound outputs, and allows you to create external resources for selected unbound outputs. You can select and choose which outputs to bind to external references. Once you click OK the external references appear on the canvas bound to the output. This operation is similar to the createExternalResources abctl command. The names for the references are auto-generated.

5.3.5 Editing an Assembly Using abctl

This section describes assembly editing operations you can perform using abctl.

Creating Empty Top-level Assemblies

Use the createAssembly command to create an empty top-level assembly. Example 5-11 shows the createAssembly command.

Example 5-11 createAssembly Command

$ ./abctl help –command createAssembly
$ ./abctl createAssembly -name myAssembly -defaultNetwork intranet

Adding Appliances (or WebLogic Server Assemblies) to Top-level Assemblies

Use the addToAssembly command to add appliances to a top-level assembly. Example 5-12 shows the addToAssembly command.

Example 5-12 addToAssembly Command

$ ./abctl help –command addToAssembly
$ ./abctl addToAssembly -name myAppliance -into myAssembly

Connecting Outputs to Inputs

Use the connectEndpoints command to creates a new connection between an output and an input. The protocols of the output and input must match, and the owners of the output and input must be part of the same assembly. Example 5-13 shows the connectEndpoints command.

Example 5-13 connectEndpoints Command

$ ./abctl help –command connectEndpoints
$ ./abctl connectEndpoints -from mySite/myOhs -fromOutput output1 -to mySite/myWls -toInput default

5.3.6 Clearing Assembly Passwords

You can clear all passwords for a top-level non-atomic assembly and its child appliances and assemblies, such that all passwords must be provided within the deployment plan. This operation removes all user and template passwords (does not pertain to system property passwords since they are not reflected in the deployment plan). Optional passwords that have no value at the time the command is executed are still not required to be provided in the deployment plan. Optional passwords that have a value at the time the command is executed are set to required and their value unset.

This command does not alter any deployment plans. You must specify passwords in the deployment plan prior to deployment. If you do not provide values in the deployment plan, the deployment plan validation fails.

5.3.6.1 Clearing Assembly Passwords with Oracle Virtual Assembly Builder Studio

The Clear Assembly Passwords dialog allows you to clear the passwords from the assembly and appliance metadata. To access the Clear Assembly Passwords dialog, select View > Assemblies > Right click an Assembly > Clear Assembly Passwords. Click OK.

You can also perform this operation can from the Create Assembly Archive wizard.

5.3.6.2 Clearing Assembly Passwords with abctl

The clearAssemblyPasswords command in the abctl command-line interface allows you to clear the passwords from the assembly and appliance metadata.

Example 5-14 shows how to clear assembly passwords:

Example 5-14 Clear Assembly Passwords

 ./abctl clearAssemblyPasswords -name myWlsAssembly

5.3.7 Copy an Appliance or Atomic Assembly

When an appliance or atomic assembly is added to a top-level assembly, a metadata copy is created in the assembly. The new copy shares file sets and VM templates with the original. This behavior saves space and is usually desirable. In some cases, however, you may want to have a copy of an appliance or atomic assembly that does not share files and VM templates.

You can create a copy of an appliance or an atomic assembly that does not share file sets or VM templates with the original object. This operation is not allowed for external resource appliances, appliances contained within atomic assemblies, or top-level non-atomic (user created) assemblies.

The copy is placed at the root of the catalog. Sharing of any captured file sets and/or created virtual machine templates is broken, which means new copies of those things are made as well.

5.3.7.1 Copying an Appliance or Atomic Assembly with Oracle Virtual Assembly Builder Studio

Select the appliance/atomic assembly and choose Save As. You can also create a copy of an appliance or assembly by exporting and then importing under a different name. The Save As dialog allows you to create a copy that does not share files sets and VM templates with the original object. In the Save As field, enter a unique name for the new appliance, and click OK.

5.3.7.2 Copying an Appliance or Atomic Assembly with abctl

The copy command in the abctl command-line interface allows you to create a copy that does not share files sets and VM templates with the original object.

Example 5-15 shows how to copy an appliance:

Example 5-15 Copy an Appliance

 ./abctl copy -name mySite/myWls -copyTo wls2

5.3.8 Export Operations

The following sections describes the available export scenarios:

• Export and import (of the artifacts created by the export) from the Oracle Virtual Assembly Builder Studio Catalog to another Oracle Virtual Assembly Builder Studio Catalog. See the following sections:

  • Section 5.3.8.1, "Export an Appliance or Assembly from a Catalog"

  • Section 5.3.8.2, "Import an Appliance or Assembly to a Catalog"

• Assembly Archive copy. Publishing the assembly archive outside of Oracle Virtual Assembly Builder for someone else to consume. For example, you create an assembly archive and publish it within an enterprise for others to download and deploy.

  • Section 5.3.8.3, "Exporting (Copying) an Assembly Archive"

• Importing an assembly archive from the Deployer repository into the Oracle Virtual Assembly Builder Studio catalog (import command, or Import from Studio).

  • Section 5.3.8.4, "Importing an Assembly Archive to a Catalog"

5.3.8.1 Export an Appliance or Assembly from a Catalog

This section describes how to export an appliance or assembly from a catalog, using Oracle Virtual Assembly Builder Studio, or abctl.

To copy an appliance or assembly from one catalog to another, you must use Oracle Virtual Assembly Builder's export and import functionality.

Note:

Manual copying of disk files from one catalog to another is not supported and will not work.

5.3.8.1.1 Exporting an Appliance or Assembly from a Catalog Using Oracle Virtual Assembly Builder Studio

Access the Export dialog box (Figure 5-9) to export an appliance or assembly from a catalog by selecting File > Export, or by right-clicking the assembly in the Assemblies navigator and select Export.

Enter the following information:

• Name: this field pre-populates with the name of the appliance or assembly that you selected for export.

• Directory: browse to and select or enter the name of the directory of the location of the export. This directory must be empty and will be created if it does not exist.

• Working Directory: optionally, specify the path to a working directory.

• Metadata Only: check this checkbox to export only metadata (and not the associated templates or file sets).

Click OK.

Figure 5-9 Exporting an Appliance or Assembly from a Catalog

Description of "Figure 5-9 Exporting an Appliance or Assembly from a Catalog"

5.3.8.1.2 Exporting an Appliance or Assembly from a Catalog Using abctl

Use the export command to export an assembly, or assembly metadata. Example 5-16 shows the export command for exporting metadata, and associated templates and file sets. Example 5-17 shows exporting metadata only.

Example 5-16 export Command

$ ./abctl help –command export
$ ./abctl export -name myOhs -toDir /tmp/myOhs.export/
(some progress messages)
Successfully exported to /tmp/myOhs.export/.

Example 5-17 export Command (Metadata Only)

$ ./abctl export -name myOhs -to /tmp/myOhs.export/ -metadataOnly
(some progress messages)
Successfully exported to /tmp/myOhs.export/.

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command along with a sample output of the command.

5.3.8.2 Import an Appliance or Assembly to a Catalog

This section describes how to import an appliance, assembly, or assembly archive using Oracle Virtual Assembly Builder Studio, or abctl.

To copy an appliance or assembly from one catalog to another, you must use Oracle Virtual Assembly Builder's export and import functionality.

5.3.8.2.1 Importing Using Oracle Virtual Assembly Builder Studio

Access the Import dialog box (Figure 5-10) to import an appliance or assembly to a Catalog by selecting File > Import. Enter the following information:

• Path: browse to and select or enter the name of the directory of the assembly or appliance which was exported. The path and associated assembly appear in the window.

• Overwrite: check this checkbox to specify that any existing metadata and associated file sets and templates are overridden. This is to correct a case of name collision. Overriding an existing appliance can only be done if the existing appliance can be removed.

Click OK.

Figure 5-10 Importing an Assembly Archive

Description of "Figure 5-10 Importing an Assembly Archive"

5.3.8.2.2 Importing an Appliance or Assembly Using abctl

Use the import command to import (into the target catalog) the content of one or more files containing a sparse copy of exported metadata and associated file set and templates.

A new entry is created in the target catalog. If there is a name collision (for example, the import command attempts to create 'mySite', and the catalog already has 'mySite'), the operation will fail.

Example 5-18 shows the import command from a directory where you previously ran the export command:

Example 5-18 import Command from a Directory

$ ./abctl help –command import
$ ./abctl import -from /tmp/myOhs.export/
Successfully imported myOhs to /example/ab_home/catalog.

Example 5-19 shows the import command from an assembly archive:

Example 5-19 import Command from an Assembly Archive

$ ./abctl help –command import
$ ./abctl import -from /tmp/myOhs.ova
Successfully imported myOhs to /example/ab_home/catalog.

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.3.8.3 Exporting (Copying) an Assembly Archive

Assembly archives in the Oracle Virtual Assembly Builder Studio catalog are stored in the $AB_INSTANCE/archives directory. You can copy or use FTP to transfer the assembly archives from this directory without the need for any export utility. Typically you will copy the assembly archives to the Deployments navigator managed by Deployer.

5.3.8.4 Importing an Assembly Archive to a Catalog

Importing an assembly archive allows you to import an assembly archive template file from a disk location into the local catalog to allow editing of the assembly appliances. Importing creates a metadata structure, with file set and template artifacts that are identical to the original catalog.

To import an assembly archive use the downloadAssemblyArchive command in abctl:

Example 5-20 downloadAssemblyArchive Command

$ ./abctl help –command downloadAssemblyArchive
$ ./abctl downloadAssemblyArchive -name MyAssembly -version 1 -fileName RenamedAssembly.ova

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.3.9 Rename an External Resource

When you create an external resource, the name of the resource is selected automatically. This name selection is performed in the infrastructure and supports reuse in that functionally identical existing external resources are reused where possible.

You can the rename any external resource. The operation is not supported for other types of catalog objects. Only external resources can be renamed.

5.3.9.1 Renaming an External Resource with Oracle Virtual Assembly Builder Studio

The Rename dialog allows you to rename an external resource. To access the dialog, select File > Rename from the main menu, or select Rename from the context menu of the external resources.

In the Rename field, enter a new name for the external resource, and click OK.

5.3.9.2 Renaming an External Resource with abctl

The renameExternalResource command in the abctl command-line interface allows you to renames a specified external resource.

Example 5-21 shows how to rename an external resource:

Example 5-21 Rename an External Resource

 ./abctl abctl renameExternalResource -assembly mySite -currentName jdbc0 -newName myDatabase

5.3.10 Creating an Assembly Archive

You can create an assembly archive for a given assembly. An assembly archive contains metadata about the assembly and assembly templates that are used to instantiate an instance of the assembly in a virtualized environment.

When the assembly archive is successfully created, the assembly is locked. At this point you cannot make changes to the assembly without explicitly deleting the assembly archive.

5.3.10.1 Creating Assembly Archives Using Oracle Virtual Assembly Builder Studio

To create an assembly archive for an assembly:

1. Select View > Assemblies to view the available assemblies.

2. Right click an assembly and select New > OVM Assembly Archive to create an assembly archive for the assembly.

3. In the Welcome page, click Next.

4. In the Create Assembly Archive page, do the following:

   1. Select the Compress Assembly Archive checkbox if you want to create and compress an assembly archive.

   2. Select the Sign Assembly Archive checkbox to sign the archive and provide the signing information.

   3. Click Next.

5. In the Clear Assembly Passwords page, select whether to clear all the passwords from the assembly and appliance metadata. Clearing passwords does not impact any existing appliance templates.

   WARNING:

   Once passwords have been cleared they cannot be recovered.

6. In the Recreate Existing Appliance Templates page, select those existing appliance templates that need to be recreated by checking Recreate. You cannot recreate a template if the template is already included in a different assembly archive.

7. Perform the required configuration on the remaining pages (Configure Base Image Options, Configure New Appliance Templates, Validate Base Images, and Summary) as described in Section 5.3.3, "Creating Templates for an Appliance or an Assembly".

5.3.10.2 Creating Assembly Archives Using abctl

You can use abctl to create an assembly archive for the named top-level assembly. This command can only be invoked on a top-level assembly. Additionally, you must have previously templated all the subappliances within the assembly using the createTemplate command.

Use the -platform option to specify the platform as Oracle VM.

Example 5-22 is a createAssemblyArchive command example:

Example 5-22 Create Assembly Archive

$ ./abctl createAssemblyArchive -name myWlsAssembly -platform OVM -nocompress

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4 Operations Related to Deployment

This section details how you will use Oracle Virtual Assembly Builder Studio or the abctl command line utility to perform operations related to deployment.

• Section 5.4.1, "Managing Deployer Connections"

• Section 5.4.2, "Configuring Targets"

• Section 5.4.3, "Creating a Deployment Plan"

• Section 5.4.5, "Checking Target Resources"

• Section 5.4.6, "Uploading an Assembly Archive to the Deployer Repository"

• Section 5.4.7, "Uploading Assembly Resources"

• Section 5.4.8, "Downloading an Assembly Archive from the Deployer Repository"

• Section 5.4.9, "Registering an Assembly Archive to a Target"

• Section 5.4.10, "Deploying an Assembly Instance"

• Section 5.4.11, "Performing One-Step Deployment"

• Section 5.4.12, "Stopping an Assembly Instance"

• Section 5.4.13, "Starting or Restarting an Assembly Instance"

• Section 5.4.14, "Scale Appliance"

• Section 5.4.15, "Undeploying an Assembly Instance"

• Section 5.4.16, "Unregistering an Assembly Archive from a Target"

• Section 5.4.17, "Deleting an Assembly Archive from the Deployer Repository"

• Section 5.4.18, "Interacting with EM Software Library"

5.4.1 Managing Deployer Connections

You can manage connections to the Deployer by selecting Tools > Manage Deployer Connections. The Deployer Connection Manager dialog appears (Figure 5-11), which allows you to create, edit, or delete connections for uploading, registering and deploying assembly archives to the Deployer.

Figure 5-11 Deployer Connection Manager

Description of "Figure 5-11 Deployer Connection Manager"

To create a connection to the Deployer:

1. Select the create icon.

2. Configure the following connection properties:

   • Name: enter a name for the Deployer connection.

   • URL: enter a URL for the Deployer connection.

   • Username: enter a username for accessing the Deployer.

   • Password: enter the password for accessing the Deployer.

3. Click Test Connection to verify that you can successfully connect.

   If you test a Deployer connection that uses HTTPS (TLS/SSL), additional steps may be required. If the Deployer trust store determines the connection to be trusted, then nothing is required. If the Deployer trust store does not trust the connection, you are prompted with the chain of certificates returned by the Deployer and asked if you want to add them to the Deployer trust store. To do so, you must provide the Deployer trust store password that you specified during installation.

4. Click OK.

To edit a connection to the Deployer:

1. Select the connection in the Connections pane.

2. Select the edit icon.

3. Updates the connection properties as required.

4. Click OK.

To delete a connection to the Deployer:

1. Select the connection in the Connections pane.

2. Select the delete icon.

3. Confirm the deletion.

5.4.2 Configuring Targets

The following configuration tasks are required for Oracle VM Manager and Oracle Virtual Assembly Builder Deployer to configure deployment targets:

• configure Oracle VM Manager connection parameters

• configure Oracle Virtual Assembly Builder Deployer properties

• configure the connection from the Deployer to Oracle VM Manager

• define the connection to the Oracle VM backend endpoints

• add deployment targets in the backend

5.4.2.1 Configure Oracle VM Manager

By default, when Oracle VM Manager is installed it is setup with a secure connection (that is, HTTPS). SSL communication to Oracle VM Manager needs to be configured to use Java Secure Socket Extension (JSSE) for Oracle Virtual Assembly Builder to be able to connect to it.

To configure JSSE for Oracle VM Manager:

1. Log into the Oracle WLS administration console of Oracle VM Manager.

2. Go to Servers > AdminServer > SSL > Advanced Properties.

3. Make sure Use JSSE SSL is checked.

Note:

If a change was made for JSSE, you must restart Oracle VM Manager for it to take effect.

You can use a non-SSL connection (HTTP) to Oracle VM Manager if it is enabled.

5.4.2.2 Identify Oracle VM Manager Connection Parameters

Identify the following connection properties for Oracle VM Manager:

• URL

• Username/Password

• Pool

5.4.2.3 Stop Oracle Virtual Assembly Builder Deployer

Before proceeding to the following steps ensure that the Oracle Virtual Assembly Builder Deployer is not running. Use the ps –ef | grep command for Java processes if needed. If you just completed creating the Deployer domain the Deployer will not be running. The server needs to be explicitly started.

5.4.2.4 Configure Deployer Properties

To configure properties:

1. Ensure the Oracle Virtual Assembly Builder Deployer is not running.

2. Edit the <deployer domain root>/config/fmwconfig/servers/AdminServer/mbeans/ovabconfig.properties file and set the ovab.webserver.url property

   appropriately. By default it is set to "http\:localhost\:7001". The ":" is escaped by a "\". Determine the IP address of the host machine and edit the ovab.webserver.url appropriately. For example:

   ovab.webserver.url=http\://192.168.1.1\:7001
   

Note:

This IP address must be reachable. If the IP is not reachable the Deployer operations associated with deployments will fail. This is the callback URL that the Oracle VM Manager uses to communicate with the Deployer.

5.4.2.5 Configure Deployer for SSL connection to Oracle VM Manager

To create an SSL connection to Oracle VM Manager, if required:

1. Install the Oracle VM Manager certificate in the Deployer:

   1. Issue the following command:

      /usr/bin/openssl s_client -connect <ovmm_host>:<port>
      

      For example:

      [ovab@localhost ~]$ /usr/bin/openssl s_client -connect
      ovmmhost.example.com:7002
      CONNECTED(00000003)
      depth=0 /C=US/O=Oracle/OU=OVMM/CN=weblogic
      verify error:num=18:self signed certificate
      verify return:1
      depth=0 /C=US/O=Oracle/OU=OVMM/CN=weblogic
      verify return:1
      ---
      Certificate chain
        0 s:/C=US/O=Oracle/OU=OVMM/CN=weblogic
          i:/C=US/O=Oracle/OU=OVMM/CN=weblogic
      ---
      Server certificate
      -----BEGIN CERTIFICATE-----
      tZh6pp/foLKF6tczer9CtH58gXdRKIjRsN3kYh1NUhYwdMQhwrJeWgvDzs/AFpMy
      UzEPMA0GA1UEChMGT3JhY2xlMQ0wCwYDVQQLEwRPVk1NMREwDwYDVQQDEwh3ZWJs
      tZh6pp/foLKF6tczer9CtH58gXdRKIjRsN3kYh1NUhYwdMQhwrJeWgvDzs/AFpMy
      AlVTMQ8wDQYDVQQKEwZPcmFjbGUxDTALBgNVBAsTBE9WTU0xETAPBgNVBAMTCHdl
      YmxvZ2ljMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDVoMviwZXEyGTA0/gz
      tZh6pp/foLKF6tczer9CtH58gXdRKIjRsN3kYh1NUhYwdMQhwrJeWgvDzs/AFpMy
      pawpiL2jG/FoVA4qZDgxmFSfq70Qo0x8Csm9ZRJObb1229UDlzz9i4/wOZywLT65
      tZh6pp/foLKF6tczer9CtH58gXdRKIjRsN3kYh1NUhYwdMQhwrJeWgvDzs/AFpMy
      5tZh6pp/foLKF6tczer9CtH58gXdRKIjRsN3kYh1NUhYwdMQhwrJeWgvDzs/AFpMy
      bAUGIELgtYnR/iG1RVEp4yQxSYqS9qdwoPwW/yhXspft9UwH0vNWUedzriRe5pA9
      216UH/+/RYtZ9wdFDDdOebT1u2bHWJExsVi8
      -----END CERTIFICATE-----
      subject=/C=US/O=Oracle/OU=OVMM/CN=weblogic
      issuer=/C=US/O=Oracle/OU=OVMM/CN=weblogic
      ---
      No client certificate CA names sent
      ---
      SSL handshake has read 1086 bytes and written 279 bytes
      ---
      New, TLSv1/SSLv3, Cipher is EDH-RSA-DES-CBC3-SHA
      Server public key is 1024 bit
      Secure Renegotiation IS supported
      Compression: NONE
      Expansion: NONE
      SSL-Session:
        Protocol : TLSv1
        Cipher : EDH-RSA-DES-CBC3-SHA
        Session-ID:
      517AF76A8665187015EC313D4FA2BC72B06B58A11268F3D4443F86517AF76A8
        Session-ID-ctx:
        Master-Key:
      517AF76A8BAC77A5C9571DA050343239C821CBCC3273CE781C64B8EF5E0137FBA93C67253D
      0D0A0E915CF517AF76A8
        Key-Arg : None
        Krb5 Principal: None
        Start Time: 1367013332
        Timeout : 300 (sec)
        Verify return code: 18 (self signed certificate)
      ---
      read:errno=0
      [ovab@localhost ~]$
      

   2. Copy the cert portion of the above output (from "BEGIN" to "END", inclusively) to /tmp/ovmm.cert:

      -----BEGIN CERTIFICATE-----
      tZh6pp/foLKF6tczer9CtH58gXdRKIjRsN3kYh1NUhYwdMQhwrJeWgvDzs/AFpMy
      UzEPMA0GA1UEChMGT3JhY2xlMQ0wCwYDVQQLEwRPVk1NMREwDwYDVQQDEwh3ZWJs
      tZh6pp/foLKF6tczer9CtH58gXdRKIjRsN3kYh1NUhYwdMQhwrJeWgvDzs/AFpMy
      AlVTMQ8wDQYDVQQKEwZPcmFjbGUxDTALBgNVBAsTBE9WTU0xETAPBgNVBAMTCHdl
      YmxvZ2ljMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDVoMviwZXEyGTA0/gz
      tZh6pp/foLKF6tczer9CtH58gXdRKIjRsN3kYh1NUhYwdMQhwrJeWgvDzs/AFpMy
      pawpiL2jG/FoVA4qZDgxmFSfq70Qo0x8Csm9ZRJObb1229UDlzz9i4/wOZywLT65
      tZh6pp/foLKF6tczer9CtH58gXdRKIjRsN3kYh1NUhYwdMQhwrJeWgvDzs/AFpMy
      5tZh6pp/foLKF6tczer9CtH58gXdRKIjRsN3kYh1NUhYwdMQhwrJeWgvDzs/AFpMy
      bAUGIELgtYnR/iG1RVEp4yQxSYqS9qdwoPwW/yhXspft9UwH0vNWUedzriRe5pA9
      216UH/+/RYtZ9wdFDDdOebT1u2bHWJExsVi8
      -----END CERTIFICATE-----
      

   3. Issue the following command:

      Note:

      This example shows the steps for when the demo truststore is in use by the Deployer. If using a custom truststore, substitute the appropriate truststore path and pass phrase.

      keytool -import -v -trustcacerts -alias ovmm_cert -file /tmp/ovmm.cert -keystore <deployer's weblogic home>/server/lib/DemoTrust.jks
      

      Note:

      You are prompted for a password. It is: DemoTrustKeyStorePassPhrase.

      You are prompted to trust the certificate. Enter yes.

      Here is a sample execution:

      [ovab@localhost ~]$ keytool -import -v -trustcacerts -alias ovmm_cert -
      file /tmp/ovmm.cert -keystore
      /home/ovab/Oracle/Middleware/Oracle_Home/wlserver/server/lib/DemoTrust.jks
      Enter keystore password:
      Owner: CN=weblogic, OU=OVMM, O=Oracle, C=US
      Issuer: CN=weblogic, OU=OVMM, O=Oracle, C=US
      Serial number: 50866375
      Valid from: Tue Oct 23 05:29:25 EDT 2012 until: Fri Oct 21 05:29:25 EDT
      2022
      Certificate fingerprints:
        MD5: BE:75:9D:CF:5F:21:6E:40:6E:3D:1E:A0:37:BE:22:C2
        SHA1: 3C:69:CA:BA:58:DF:4D:AB:CF:2F:53:84:D9:B8:9D:40:CA:A3:F8:B5
        SHA256:
      EA:0A:49:A0:C3:15:31:C5:5D:4A:3F:2D:AD:3A:18:C4:CC:55:C2:11:67:93:A3:C2:F5
      :68:1F:BD:2F:21:63:BC
        Signature algorithm name: SHA1withRSA
        Version: 3
      Trust this certificate? [no]: yes
      Certificate was added to keystore
      [Storing
      /home/ovab/Oracle/Middleware/Oracle_Home/wlserver/server/lib/DemoTrust.jks
      ]
      [ovab@localhost ~]$
      

5.4.2.6 Start Oracle Virtual Assembly Builder Deployer

Start the Oracle WebLogic Server hosting the Deployer.

Note:

Wait for the server to reach the "RUNNING" mode.

5.4.2.7 Connection URL

Oracle requires that you configure your target connections for Oracle VM 3.2.1 with HTTP/HTTPS protocol.

To configure with HTTP, specify a URL of the form "http://their-ovm-host:7001".

5.4.2.8 Connection Credentials

To configure connection to Oracle VM Manager:

1. The HTTP/HTTPS port is used to connect to Oracle VM Manager. If the Oracle VM Manager protocol HTTPS is used (which will be the usual, since OVMM disables HTTP by default), you must import the Oracle VM Manager certificate into the Deployer's trust store prior to creating a target.

   See Section 5.4.2.5, "Configure Deployer for SSL connection to Oracle VM Manager" for information on importing the certificate into the trust store.

2. Create the target using the createTarget command in abctl.

   This operation, which can only be performed by the CloudAdmin, defines the connection information, and, depending on the backend type, user credentials for the backend. Specify ovm.vmmversion=3.2 and Oracle VM credentials here.

5.4.2.9 Examples

Example 5-23 shows how to create a target for Oracle VM:

Example 5-23 Create Target for Oracle VM

 ./abctl createTarget -name slcTarget_http -type ovm -properties ovm.poolName=ab_ovm_30_stand_alone_pool ovm.vmOperationTimeout=3600 ovm.vmmversion=3.2 ovm.user=admin ovm.pwd ovm.url=https://example.com:7002 -connectionName localDeployer

Example 5-24 shows how to add users to a target for Oracle VM:

Example 5-24 Add Users to a Target for Oracle VM

 ./abctl addTargetUser -user Username -target Targetname

5.4.3 Creating a Deployment Plan

A deployment plan allows you to override property values defined in the metadata of an assembly so you can customize each deployment of the assembly. The plan is applied when the assembly is deployed. Only top-level assemblies can have deployment plans.

5.4.3.1 Create a Deployment Plan Using Oracle Virtual Assembly Builder Studio

Create a deployment plan:

1. In the Deployment Plans navigator, right-click an assembly and select New Deployment Plan.

   The Create Deployment Plan wizard appears (Figure 5-12).

   Figure 5-12 Create Deployment Plan

   
   Description of "Figure 5-12 Create Deployment Plan"
   
   

2. Enter the name for the deployment plan.

3. Select the associated assembly from the Assembly drop-down menu.

4. Click OK. The Deployment Plan editor opens.

5.4.4 Editing a Deployment Plan

The Deployment Plan Editor displays a read-only view of the assembly. This view is useful as an overview and for selecting items so that their property values may be overridden.

5.4.4.1 Required Views

Deployment plan editing makes use of both the Structure Pane and the Property Inspector. You should ensure both views are visible.

1. Open the Structure Pane by selecting View > Structure.

2. Open the Property Inspector by selecting View > Property Inspector.

5.4.4.2 Edit a New Deployment Plan

When you create a new deployment plan, the Deployment Plan editor opens automatically.

5.4.4.3 Edit an Existing Deployment Plan

Edit an existing deployment plan:

1. In the Deployment Plans navigator, right-click the plan and select Open, or double-click the plan icon in the Deployment Plans navigator.

   You can also edit a deployment plan by selecting the deployment plan in the Deployment Plan navigator and selecting the appliances/network interfaces in the structure pane. The properties of any element selected in the structure pane are reflected in the property inspector.

5.4.4.4 Selecting items in the Deployment Plan Editor

To override the properties of an appliance, input, output or other item, you must first select the item.

To select an item in the Deployment Plan editor, click on it.

5.4.4.5 Selecting items in the Structure Pane

When populated, the Structure Pane shows additional details of the plan.

Populate the Structure Pane:

1. In the Deployment Plans navigator, select the plan.

   The Structure Pane populates with the assembly structure. To select an item in the populated Structure Pane, click on it.

   Selecting any item in the Deployment Plan editor also populates the Structure Pane.

5.4.4.6 Overriding Property Values

The properties of the selected item are displayed in the Property Inspector.

To override a value:

1. In the property inspector, type a new value in the field.

   A blue bullet is displayed next to overridden values.

5.4.4.7 Remove an Override Value

To remove an override:

1. In the Property Inspector, click the downward-pointing arrow (chevron) to the right of the property value.

2. From the pop-up menu, select Reset to...

   The value shown in the Reset to... menu item is always the original value specified in the assembly metadata. The override is removed.

5.4.4.8 Ability to Set Appliance 'target' Count to Zero (Zero-Count Appliances)

During deployment plan editing, you can edit the target scale to zero in the deployment plan to initially deploy an assembly with zero appliance instances.

In subsequent scaling operations you can add appliance instances to those appliances that are part of the assembly configuration but were initially "deployed" with a zero instance count.

5.4.4.9 Synthetic Properties

Synthetic properties are properties needed to successfully deploy an assembly, that Oracle Virtual Assembly Builder adds to appliances, networks and network interfaces. These properties include, scaling, network, resource requirements and several more.

You may override the scalability properties of an appliance. Doing so may change the number of potential appliance instances that can exist when the assembly is deployed. Each of these potential appliance instances may require its own network settings including hostname, IP address, MAC address, and netmask properties. The Property Inspector automatically displays the appropriate number of instance-specific network properties. When the scalability values are changed, the Property Inspector automatically adjusts the number of network properties to match the number of appliances instances that may potentially exist.

5.4.4.9.1 Appliance Properties

To display the network properties of an appliance:

1. In the Structure pane or Deployment Plan editor, click to select the appliance.

2. In the Property Inspector, click to open the Network category.

The default-gateway, dns-domains, and dns-servers property values are required unless all network interfaces of the appliance are configured to use DHCP. These values are shared by all instances of the appliance.

The hostname.0 property is required. If the appliance is scalable, the Property Inspector will display an appropriate number of properties (hostname.0, hostname.1, etc.) All values are required.

5.4.4.9.2 Network Interface Properties

To display the Deployment Plan properties of a network interface, click on the network interface in the Deployment Plan editor or expand the Network Interfaces folder in the Structure pane and click the network interface within the folder.

Setting the usedhcp property of the Interface to true asserts that these network properties will be automatically configured in the deployment target environment. When usedhcp is true, the Property Inspector displays previously-established values of the other network interface properties, but does not permit the values of these properties to be modified.

If usedhcp is false, the ip_address.0, mac_address.0, and netmask properties are required. If the appliance is scalable, the Property Inspector will display an appropriate number of address properties (ip_address.0, ip_address.1, ..., mac_address.0, mac_address.1, ...) and all values are required.

5.4.4.9.3 Vnet Properties

Vnets are not displayed in the Deployment Plan editor so cannot be selected there. To display the Deployment Plan properties of a Vnet, expand the Vnets folder in the Structure pane and select the Vnet.

The is_private property specifies that the network should be automatically configured as a high-performance network for internal use within the deployed Assembly. This value must be false if the deployment target environment does not provide the necessary platform support for high-performance private networks. Set this value to false when deploying directly to Oracle Virtual Machine version 3.0.

The network_name property specifies the name of the network defined in the deployment target environment. This property is required.

Some deployment target environments may not require that network names be unique. When network names are not unique, the optional network_id property can be used to uniquely specify the network defined in the deployment target environment. The value of this property is ignored when the is_private property is true.

5.4.4.10 Validating a Deployment Plan

To validate the deployment plan:

1. In the Deployment Plans navigator, right-click the plan and select Validate.

   The validation results are displayed in a dialog box.

5.4.4.11 Saving a Deployment Plan

When the deployment plan has been modified, its name is displayed in italic font in both the Deployment Plan navigator and the tab of the Deployment Plan editor.

To save the deployment plan:

1. Select File > Save.

If the File > Save menu item is not enabled, the deployment plan may not be selected. In the Deployment Plan navigator, select the plan, then select File > Save.

You can create, edit and save multiple deployment plans for a single assembly. At deployment time, you select one plan for the deployment. In this way, a single assembly may serve as the basis of multiple deployments, each with their own specific network and other property settings.

5.4.5 Checking Target Resources

You can check whether there are enough resources on the target network to deploy your assembly with a particular deployment plan. You must have already created a deployment plan.

There are four places in Oracle Virtual Assembly Builder Studio where you can validate that there are enough resources for the assembly and deployment plan combination:

• Local assembly: you can right click an assembly with an assembly archive and select Check Available Resources. Once selected, the user is presented a modified version of the deployment dialog. Users will need to select a target and deployment plan as well as resolve any vnet bindings before clicking on the “check resources” button. A success dialog will be shown if sufficient resources exist. Otherwise a failed dialog will be shown specifying which resources are insufficient for a deployment.

• Uploaded assembly: you can right click on an uploaded assembly archive version and select Check Available Resources. All other behavior is identical to the local assembly.

• Registered assembly: you can select a specific registered instance of an assembly archive and select Check Available Resources. You do not need to select a target.

• Deployment plan: you can select a specific deployment plan of an assembly and select Check Available Resources. You do not need to select a deployment plan, but must select a target.

In the Check Target Resources dialog, configure the following fields:

• Target: select the deployment target.

• Deployment Plan: select the deployment plan for the deployment.

• Vnet Mappings: map Vnets from your assembly to target networks. Any change to mappings will be saved in the selected deployment plan prior to deployment. Select the target network to map to the Vnet. The current mappings are designated by an asterisk.

5.4.6 Uploading an Assembly Archive to the Deployer Repository

You can upload an assembly to the Deployer repository using Oracle Virtual Assembly Builder Studio or abctl.

5.4.6.1 Uploading an Assembly using Oracle Virtual Assembly Builder Studio

To upload the assembly archive, right click on the assembly and selecting Upload Assembly Archive > Deployer.

5.4.6.2 Uploading an Assembly using abctl

To upload an assembly archive, use the uploadAssemblyArchive command.

Example 5-25 uploadAssemblyArchive Command

$ ./abctl help –command uploadAssemblyArchive
$ ./abctl uploadAssemblyArchive -fileName Path -name String [-description String] -connectionName String

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.7 Uploading Assembly Resources

Assembly resources are a collection of files used during registration and/or deployment of an assembly. You upload assembly resources in a zip format file and store them alongside a specific assembly archive version. Generally, the initial zip should contain all necessary resources, however, there is an append option to the upload operation that allows adding more resources. The delete operation removes all resources for an assembly version by default. The file option allows for deleting a subset. The two options mentioned – append and file – allow for arbitrary updates.

5.4.7.1 Volume Management

The assembly resources file contain disk images which are used to create a file system template on a zfs storage device at assembly registration time and these are cloned into filesystems that are mounted on the VM at deployment time.

The resource zip contains a disks folder that has a set of disk images. These images are referenced by the OVF metadata for the assembly. The following is an example of the OVF Metadata. The first entry (volume|MyVolume|content-filename) is a reference to a disk image in the assembly resource zip and is not configurable. The other properties are details on the volume that the Deployer uses for setup and to communicate details to the vServer at deploy time.

<ovf:ProductSection ovf:class="com.oracle.ovab.volumes">
  <ovf:Property 
    ovf:key="volume|MyVolume|content-filename" 
    ovf:type="string" ovf:userConfigurable="false" 
    ovf:value="myIsoFileName"/>
  <ovf:Property 
    ovf:key="volume|MyVolume|mount-options" 
    ovf:type="string" 
    ovf:userConfigurable="true" ovf:value=""/>
  <ovf:Property 
    ovf:key="volume|MyVolume|mount-target" 
    ovf:type="string" 
    ovf:userConfigurable="true" ovf:value=""/>
  <ovf:Property 
    ovf:key="volume|MyVolume|nfs-type" 
    ovf:type="string" 
    ovf:userConfigurable="true" ovf:value="nfs"/>
  <ovf:Property 
    ovf:key="volume|MyVolume|quota-size" 
    ovf:type="sint32" 
    ovf:userConfigurable="true" ovf:value="10"/>
  <ovf:Property 
    ovf:key="volume|MyVolume|quota-unit" 
    ovf:type="string" 
    ovf:userConfigurable="true" ovf:value="GB"/>
...

Based on these definitions, the Deployer uses the disk images from the assembly resource to create a filesystem in a ZFS storage device at assembly registration time. Later, at deployment time, this filesystem is cloned for specific use by individual vServers in the assembly and passes mount point information to the vServers through the vmapi.

Connection information for the ZFS storage device is configured using the existing target configuration interfaces of the Deployer. There is a new target type for this named “zfs”. This target type has the following settings:

• zfs.host

• zfs.port

• zfs.user

• zfs.pwd

• zfs.pool

• zfs.project

The operation for registering an assembly archive has an argument to declare the storage target to use. Also, the virtualization target definitions have a property, storageTargets, which declares the valid storage targets for use with the virtualization target. This exists because some storage targets may not be visible to the vServers created in a given virtualization target. Hence, the visibility is declared by the CloudAdmin who defines all the target information.

5.4.7.2 Application Lifecycle Scripts

The assembly resources file may contain shell scripts that are executed from the Deployer at various lifecycle points of an assembly. The resources file may contain a scripts.d directory with a set of subdirectories containing user scripts to be run at specific lifecycle points of the vServers started by the deployer. These scripts are executed from the Deployer process and are intended for performing actions in the deployment environment and not generally used to interact with the VMs themselves.

• pre-deploy.d - runs before deployment begins

• post-deploy.d - runs after deployment completes

• deployer-pre-vm-start.d - runs before the start of each vServer

• deployer-post-vm-start.d - runs after the start of each vServer

• deployer-pre-app-config.d - runs after the VM is up, and the network configured, but before the application on the VM is configured

• deployer-post-app-config.d - runs after the application on the VM is configured

• pre-undeploy.d - runs before undeployment begins

• post-undeploy.d - runs after undeployment is complete

• deployer-pre-vm-stop.d - runs before the stop of each vServer

• deployer-post-vm-stop.d - runs after the stop of each vServer

The scripts are passed a single argument which is a file path. This file path points to a properties file (name/value pairs) having the same set of properties that the Deployer

would pass to the VM over the VMAPI for that point in the lifecycle. The scripts are tied to lifecycle and not to any particular appliance or vserver. Scripts use the properties file passed in to infer any necessary context. If multiple scripts are included in a particular sub-directory, they are executed in alphabetical order.

If any script returns a non-zero result, it is considered failed and no more scripts would be run. The Deployer considers the transition failed at that point. One use case for the scripts is to configure environmental things external to the assembly itself, for example, modifying load balancer entries to allow a route to vservers created during deployment. Another possible use case is to send notifications of lifecycle events. Depending on the environment, it may or may not be possible to interact with the vServers themselves as there is no requirement that the Oracle Virtual Assembly Builder Deployer and the vServers be visible to one another on the same network.

For security reasons, if the assembly resource file contains scripts it can only be uploaded by a CloudAdmin.

5.4.7.3 Uploading Resources Using abctl

To upload assembly resources, use the uploadAssemblyResources command in abctl. Example 5-26 shows the uploadAssemblyResources command.

Example 5-26 uploadAssemblyArchive Command

$ ./abctl help –command uploadAssemblyArchive
$ ./abctl abctl uploadAssemblyResources -assemblyName myAssembly -version 1 -fileName resources.zip -connectionName myConnection

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.8 Downloading an Assembly Archive from the Deployer Repository

You can download the assembly archive corresponding to an assembly version from the Deployer repository into the Oracle Virtual Assembly Builder Studio catalog. This may be necessary if you do not have a local copy of the assembly and you want to modify it or create a deployment plan.

5.4.8.1 Download Using Oracle Virtual Assembly Builder

To download, right-click on an assembly archive in the Deployments view, and select Download Assembly Archive.

5.4.8.2 Download Using abctl

Use the downloadAssemblyArchive command to unregister templates for an assembly. Example 5-27 shows the downloadAssemblyArchive command:

Example 5-27 downloadAssemblyArchive Command

$ ./abctl help –command downloadAssemblyArchive
$ ./abctl abctl downloadAssemblyArchive -name MyAssembly -version 1 RenamedAssembly.ova

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.9 Registering an Assembly Archive to a Target

Once you upload an assembly archive to Oracle Virtual Assembly Builder Deployer you can register the assembly archive to a particular target.

5.4.9.1 Register Using Oracle Virtual Assembly Builder

Perform this in one of two ways:

• Open the Deployments navigator by selecting View > Deployments. Under Available Assemblies, right-click on a specific assembly archive version and select Register.

• Drag and drop a specific assembly archive version to the intended target. In the Deployments navigator, select the assembly archive under Available Assemblies, and drop it onto the target in Deployment Targets.

Both methods start the registration. The target node is updated with a new child representing the assembly archive version. The target node displays a throbber icon which will switch to the standard assembly archive icon once the registration is complete. You receive message feedback in the Message Log window as the registration progresses. If the registration fails, the node disappears and a pop-up menu appears explaining the failure.

To unregister, right-click on a registered node and select Unregister. The node will be removed once the unregistration is complete.

5.4.9.2 Register Using abctl

Use the registerAssemblyArchive command to unregister templates for an assembly. Example 5-28 shows the unregisterAssemblyArchive command:

Example 5-28 unregisterAssemblyArchive Command

$ ./abctl help –command registerAssemblyArchive
$ ./abctl registerAssemblyArchive -connectionName MyDeployerConnection -name TheAssembly -version 1

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.10 Deploying an Assembly Instance

This section describes how to deploy an assembly instance, using Oracle Virtual Assembly Builder Studio, or abctl.

When you deploy a registered assembly, an assembly instance and appliance instances are created and started. In Oracle Virtual Assembly Builder Studio, creation of the assembly instance, and deployment of the assembly instance are grouped into the "deploy" operation. In the abctl interface, you perform two separate commands.

Applications within the appliance instances are also started. Deploying an assembly instance can be a long running operation that can take several minutes. The time taken to deploy an assembly instance will vary depending upon the number of VMs that need to be created and started.

5.4.10.1 Deploy Using Oracle Virtual Assembly Builder Studio

Once an assembly archive is registered to a specific target, you can deploy that assembly archive one or more times.

1. Open the Deployments navigator by selecting View > Deployments.

   In the Deployments navigator, under the Deployment Targets pane, you can expand the targets and see a list of assembly archives that you can deploy.

2. Right-click an assembly version (assembly name and version) and select Deploy.

   You can also initiate an assembly instance by dragging a deployment plan from the Deployment Plan navigator and dropping it on a registered assembly archive.

3. Enter the following information in the Deploy Assembly Archive window.

   • Deployment Plan: select a deployment plan. The dialog populates the drop-down list with deployment plans matching the name of the assembly being deployed. If no plans exist, you must create a plan before you can deploy.

   • Vnet Mappings: verify (and possibly correct) the Vnet mappings in the deployment plan. At the time the deployment plan is created Oracle Virtual Assembly Builder cannot determine where you intend to deploy the assembly so it cannot validate the name of the target Vnet.

     You see one row for each Vnet defined in your assembly. The logical name of the Vnet (as defined in the assembly) is shown as the label and the corresponding drop-down contains the Vnets defined by the deployment target. The value from the deployment plan is included in the drop-down list, even though it may be invalid, for the purposes of displaying to you the value from the deployment plan. The value, or mapping, from the deployment plan has an asterisk (*) suffix.

     If the current mapping is invalid, the value displays a red error border and the "Deploy" button becomes disabled. You cannot deploy an assembly if the deployment plan contains invalid mappings. Any changes made to the Vnet mapping are saved to the deployment plan before the assembly instance initiates.

4. Click Deploy to update the deployment plan with the new mappings and initiate the assembly instance.

   Once you confirm the deployment options, the assembly deployment is initiated. A new child node is created under the registered node to indicate the progress. The name of the new child node is the Deployment ID. A throbber icon is shown until the assembly instance reaches a final state.

   When the network is initialized, you can expand an appliance to see the IP addresses of each virtual machine started for that appliance.

   When an appliance instance (and the assembly instance) is actively being processed you can see the throbber icon. As the assembly is deploying, you may see the icon for the appliance instances and possibly the assembly instance change from the throbber icon to a grey icon. The grey icon means the appliance instance has reached, and is currently sitting at, one the intermediate deployment states and it may stay in that state for several minutes while other appliance instances are being actively processed. This is especially noticeable when there are dependencies specified between appliances.

   When the appliance instance begins processing again, the icon returns to the throbber icon.

   If you select the assembly instance or appliance instance while the assembly is being deployed, you can see the current state in the property inspector.

   You can see the progress of the deployment in the Tasks navigator. If deployment fails, a red X mark is displayed in the navigator. You can open the task log for the failed task from the Tasks navigator using the View Task Log toolbar button.

5.4.10.2 Deploy Using abctl

Create an assembly instance by using the createAssemblyInstance command, as shown in Example 5-29. The createAssemblyInstance command will return the assemblyInstanceId needed for the deployAssemblyInstance command.

Example 5-29 createAssemblyInstance Command

$ ./abctl help –command createAssemblyInstance
$ ./abctl createAssemblyInstance -deploymentPlan c:/zeroAppliancesSite_plan.xml -name SMALLOVA -version 1 -c cloudAdmin
Plan upload File Size: 700
Assembly Instance Id: gdc4_29x5_SMALLOVA_1
Assembly instance has been created.

Once you have created the assembly instance, you can deploy an assembly instance by using the deployAssemblyInstance command as shown in Example 5-30.

Example 5-30 deployAssemblyInstance Command (without Waiting for Completion)

$ ./abctl help –command deployAssemblyInstance
$ ./abctl deployAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdminRequest ID: 1d1599a0-434b-426a-ab29-7c6230b5fa33Request to deploy assembly instance has been submitted to deployer.

The deployAssemblyInstance command is an asynchronous operation. It will initiate a deploy request and return a request ID. The status of the request can be queried using the describeRequests operation.If you want to wait until the completion of the operation, you may do so, optionally, by specifying additional parameters as follows:-waitForComplete -pollTime 30

Example 5-31 deployAssemblyInstance Command (Waiting for Completion)

$ ./abctl help –command deployAssemblyInstance
$ ./abctl deployAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdmin -waitForComplete -pollTime 30Request ID: 1d1599a0-434b-426a-ab29-7c6230b5fa33Request to deploy assembly instance has been submitted to deployer.

You can list the current deployments with the describeAssemblyInstances command, as shown in Example 5-32:

Example 5-32 describeAssemblyInstances Command

$ ./abctl help –command describeAssemblyInstances
$ ./abctl describeAssemblyInstances -c cloudAdmin---------------------------------------------------------------------------------- Name     | Version | State      | Assembly Instance Id | Target  | Appliances---------------------------------------------------------------------------------- SMALLOVA | 3       | Undeployed | c1Lm-GyML_SMALLOVA_3 | LOCBOX1 | c1Lm-GyML_SMALLOVA_3:zeroAppliancesSite/myWls/Server_3Assembly Instances have been described.$

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.11 Performing One-Step Deployment

One-step deployment consolidates several steps involved in creating and deploying an assembly archive into a single logical operation. Each of the steps is a potentially long running process and the consolidation eliminates the need for monitoring each individual step, waiting for it to complete and then starting the next. Instead, you can start the process to run over-night or over a weekend.

5.4.11.1 Prerequisites

The following conditions must be met before starting the process.

• All changes to the assembly must have been saved.

• All outputs must be connected.

• All file sets must have been captured.

• A deployer connection must exist and have at least one deployment target defined.

• If the assembly has an existing assembly archive, the platform type of the assembly archive must match the target platform:

  • OVM archives must be deployed to an OVM target.

• If the assembly does not yet have an assembly archive, a default base image must exist for the target platform, which is determined by the deployment target.

  • OVM targets require an OVM base image.

• At least one deployment plan must exist for the assembly and it must match the target platform.

  • OVM targets require an OVM deployment plan.

  • Template passwords must be set in the deployment plan.

If one of the prerequisites is not met, an error dialog describes why the assembly could not be deployed.

5.4.11.2 Deployment Considerations

The following conditions must be met addressed during deployment.

• You must specify the platform type. One-step deployment only shows deployment plans specific to the deployer connection type.

• By default, the deployment operation for an OVM target is an OVM archive.

One-step deployment consolidates the following steps:

1. Create Appliance Templates: Each appliance included in the assembly must have an appliance template for the target platform. If an appliance template already exists, it is used. Templates are only created for those appliances that do not already have a template for the target platform. If all appliances have existing templates, this step is skipped

2. Create Assembly Archive: The assembly must have an assembly archive for the target platform. If one does not already exist, one is created. If an archive needs to be created, it is compressed.

   If an assembly archive already exists for the target platform, this step is skipped.

3. Upload Assembly Archive: Once an assembly archive has been created, the archive is uploaded using the Deployer connection that was active (selected in the Deployments navigator) at the time the deployment was initiated. The description assigned to the uploaded assembly version is “one step deployment” and the version number is assigned automatically by the Deployer.

4. Register Assembly: Once the upload completes successfully, the newly uploaded assembly version is registered with the deployment target selected in the Deploy Assembly dialog.

5. Deploy Assembly: Once the registration completes successfully, the registered assembly is deployed using the deployment plan selected in the Deploy Assembly dialog.

5.4.11.3 Submitting an Assembly for Deployment

Once you have met the prerequisites, submit an assembly for one-step deployment, by selecting Deploy from the assembly context menu. Specify the platform type.

5.4.11.4 Task Tracking

After submitting an assembly for deployment, an entry for each step will appear in the Task Viewer. The first step, which may vary depending on the state of the assembly, begins execution immediately. The remaining steps are in a pending state until the preceding task completes successfully.

If any task fails, any pending tasks are cancelled and the process terminates.

5.4.12 Stopping an Assembly Instance

This section describes how to stop an assembly instance, using Oracle Virtual Assembly Builder Studio, or abctl.

When an assembly instance is stopped, the VMs and the applications that are running within the VMs are stopped. VMs that are in a stopped state retain their context. Stopped VMs can be restarted much more quickly than the original deployment because the VMs do not need to be created.

5.4.12.1 Stop an Assembly Instance with Oracle Virtual Assembly Builder Studio

In the Deployment Targets pane of the Deployments navigator you can start, stop, deploy, or undeploy an assembly instance. To stop an assembly instance, select the assembly instance that needs to be stopped and click Stop.

5.4.12.2 Stop an Assembly Instance with abctl

Use the stopAssemblyInstance command to stop an assembly instance. The assembly instance is referred to by its assemblyInstanceId. You can retrieve a list of assembly instances by using the describeAssemblyInstances command. Example 5-33 and Example 5-34 show the stopAssemblyInstance command:

Example 5-33 stopAssemblyInstance Command (without Waiting for Completion)

$ ./abctl help –command stopAssemblyInstance
$ ./abctl stopAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdminRequest ID: 8486522b-8a5e-4348-bdf1-a7d55fccf848Request for stop has been submitted to deployer.

Example 5-34 stopAssemblyInstance Command (Waiting for Completion)

$ ./abctl help –command stopAssemblyInstance
$ ./abctl stopAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdmin -waitForComplete -pollTime 30Request ID: 8486522b-8a5e-4348-bdf1-a7d55fccf848Request for stop has been submitted to deployer.

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.13 Starting or Restarting an Assembly Instance

This section describes how to start or restart an assembly instance, using Oracle Virtual Assembly Builder Studio, or abctl. An assembly instance that has been stopped can be restarted. Restarting an assembly instance starts up all the VMs that were stopped and also starts up the applications within the VMs. The assembly instance gets restored to the state it was in before it was stopped. This operation completes more quickly than a deployment operation.

5.4.13.1 Restarting an Assembly Instance with Oracle Virtual Assembly Builder Studio

In the Deployment Targets pane of the Deployments navigator you can start, stop, deploy, or undeploy an assembly instance. To start an assembly instance, select the assembly instance and click Start.

5.4.13.2 Starting or Restarting an Assembly Instance with abctl

The startAssemblyInstance command is used to start a deployment. The assembly instance is referred to by its assemblyInstanceId. You can retrieve the list of deployments by using the describeAssemblyInstances command. Example 5-35 and Example 5-36 show the startAssemblyInstance command:

Example 5-35 Start an Assembly Instance (without Waiting for Completion)

$ ./abctl help –command startAssemblyInstance
$ ./abctl startAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdminRequest ID: 1936dff2-f8a7-4407-83f8-08521bb48fefRequest for start has been submitted to deployer.

Example 5-36 Start an Assembly Instance (Waiting for Completion)

$ ./abctl help –command startAssemblyInstance
$ ./abctl startAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdmin -waitForComplete -pollTime 30Request ID: 1936dff2-f8a7-4407-83f8-08521bb48fefRequest for start has been submitted to deployer.

The restartAssemblyInstance command is used to restart an assembly instance., and is equivalent to performing a stopAssemblyInstance followed by a startAssemblyInstance. The assembly instance is referred to by its assemblyInstanceId. You can retrieve the list of assembly instances by using the describeAssemblyInstances command. Example 5-37 and Example 5-38 show the restartAssemblyInstance command:

Example 5-37 Restarting an Assembly Instance (without Waiting for Completion)

$ ./abctl help –command restartAssemblyInstance
$ ./abctl restartAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdminRequest ID: 126a97ef-89db-4b05-88d5-17b70e5cc3d2Request to restart assembly instance has been submitted to deployer.

Example 5-38 Restarting an Assembly Instance (Waiting for Completion)

$ ./abctl help –command restartAssemblyInstance
$ ./abctl restartAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdmin -waitForComplete -pollTime 30Request ID: 126a97ef-89db-4b05-88d5-17b70e5cc3d2Request to restart assembly instance has been submitted to deployer.

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.14 Scale Appliance

This section describes how to scale the selected appliance instance after an initial deployment of an assembly, using Oracle Virtual Assembly Builder Studio, or abctl.

After you deploy an assembly, the target number of VM instances for each appliance is started. The initial target for each appliance instance is specified in the deployment plan. You can dynamically specify a new target after an assembly has been deployed. Oracle Virtual Assembly Builder dynamically starts or stops VM instances to reach the new target (thus scaling up or scaling down). A scale down operation will only stop the properly deployed instances.

5.4.14.1 Scale Appliance with Oracle Virtual Assembly Builder Studio

To scale the number of instances of an appliance:

1. Select an assembly instance in the Deployments navigator and expand the assembly structure in the Structure Pane.

2. Right-click on a scalable appliance and select Scale appliance.

3. Set the target number of VM instances for the appliance from the Target Scale drop down. The current Scale level is identified by a * next to the right value. For example: 1* or 2*.

4. Click OK.

5.4.14.2 Retrieve the scalingGroupId for Use in the Scale Command

Use the describeScalingGroups command to retrieve the scalingGroupId to pass in to the scale command. (Example 5-39):

Example 5-39 describeScalingGroup Command

$ ./abctl help -command describeScalingGroups
$ ./abctl describeScalingGroups

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.14.3 Scale Appliance(s) in an Assembly Instance with abctl

Use the scale command to scale the appliance (Example 5-40 and Example 5-41):

Example 5-40 scale Command (without Waiting for Completion)

$ ./abctl help -command scale
$ ./abctl scale -scalingGroupId 1gWT-t0Np_SMALLOVA_1:zeroAppliancesSite/myWls/Server_3 -target 1 -c cloudAdminRequest ID: c1d2c742-d2fe-4698-bf61-99d619be4fcaRequest for scaling operation has been submitted to deployer.

Example 5-41 scale Command (Waiting for Completion)

$ ./abctl help -command scale
$ ./abctl scale -scalingGroupId 1gWT-t0Np_SMALLOVA_1:zeroAppliancesSite/myWls/Server_3 -target 1 -c cloudAdmin -waitForComplete -pollTime 30Request ID: c1d2c742-d2fe-4698-bf61-99d619be4fcaRequest for scaling operation has been submitted to deployer.

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.15 Undeploying an Assembly Instance

This section describes how to undeploy an assembly instance, using Oracle Virtual Assembly Builder Studio, or abctl.

Undeploying an assembly instance stops all the running VMs. It also cleans up any failed VMs that may exist.

5.4.15.1 Undeploying a Deployment with Oracle Virtual Assembly Builder Studio

In the Deployments navigator, you can undeploy an assembly instance by right-clicking on a deployed assembly instance and selecting Undeploy. If successful, the node is removed. If the operation fails, a red icon appears. Progress messages are shown in the Message Log window.

5.4.15.2 Undeploying an Assembly Instance with abctl

You can use the undeployAssemblyInstance command to undeploy an assembly instance. The assembly instance is referred to by its assemblyInstanceId. You can retrieve a list of assembly instances by using the describeAssemblyInstances command. Example 5-42 shows the undeployAssemblyInstance command:

Example 5-42 undeployAssemblyInstance Command (without Waiting for Completion)

$ ./abctl help –command undeployAssemblyInstance
$ ./abctl undeployAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdminRequest ID: 6b0f1b14-466e-4b23-bcc3-8b8506fd40acRequest to undeploy assembly instance has been submitted to deployer.

Example 5-43 undeployAssemblyInstance Command (Waiting for Completion)

$ ./abctl help –command undeployAssemblyInstance
$ ./abctl undeployAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdmin -waitForComplete -pollTime 30Request ID: 6b0f1b14-466e-4b23-bcc3-8b8506fd40acRequest to undeploy assembly instance has been submitted to deployer.

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.16 Unregistering an Assembly Archive from a Target

This section describes how to unregister an assembly archive from Oracle Virtual Assembly Builder Deployer using abctl. This operation unregisters the assembly archive, but does not delete the uploaded archive.

5.4.16.1 Unregistering Assembly Archives with Oracle Virtual Assembly Builder Studio

Unregister an assembly archive version (from a deployment target) by right-clicking on a registered version and selecting Unregister.

5.4.16.2 Unregistering Assembly Archives with abctl

Use the unregisterAssemblyArchive command to unregister templates for an assembly. Example 5-44 and Example 5-45 show the unregisterAssemblyArchive command:

Example 5-44 unregisterAssemblyArchive Command (without Waiting for Completion)

$ ./abctl help –command unregisterAssemblyArchive
$ ./abctl unregisterAssemblyArchive -name SMALLOVA -version 1 -target LOCBOX1 -c cloudAdminRequest ID: f9f9d0b7-e334-4020-a038-2b728e9a0a37Request to unregister assembly has been submitted to deployer.

Example 5-45 unregisterAssemblyArchive Command (Waiting for Completion)

$ ./abctl help –command unregisterAssemblyArchive
$ ./abctl unregisterAssemblyArchive -name SMALLOVA -version 1 -target LOCBOX1 -c cloudAdmin -waitForComplete -pollTime 30Request ID: f9f9d0b7-e334-4020-a038-2b728e9a0a37Request to unregister assembly has been submitted to deployer.

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.16.3 redeployAssemblyInstance

Use the redeployAssemblyInstance command to redeploy an assembly instance. Example 5-46 and Example 5-46 show the redeployAssemblyInstance command:

Example 5-46 redeployAssemblyInstance Command (without Waiting for Completion)

$ ./abctl help –command redeployAssemblyInstance
$ ./abctl redeployAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdminRequest ID: eff86a4c-d064-4794-b1ae-0624a972ab06Request to redeploy assembly instance has been submitted to deployer.

Example 5-47 redeployAssemblyInstance Command (Waiting for Completion)

$ ./abctl help –command redeployAssemblyInstance
$ ./abctl redeployAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdmin -waitForComplete -pollTime 30Request ID: eff86a4c-d064-4794-b1ae-0624a972ab06Request to redeploy assembly instance has been submitted to deployer.

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.16.4 deleteAssemblyInstance

Use the deleteAssemblyInstance command to delete an assembly instance once the assembly instance is in an undeployed state. Example 5-48 shows the deleteAssemblyInstance command:

Example 5-48 deleteAssemblyInstance Command

$ ./abctl help –command deleteAssemblyInstance
$ ./abctl deleteAssemblyInstance -assemblyInstanceId gdc4_29x5_SMALLOVA_1 -c cloudAdminAssembly instance gdc4_29x5_SMALLOVA_1 has been deleted.

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.17 Deleting an Assembly Archive from the Deployer Repository

This section describes how to delete an assembly archive from the Deployer repository, using Oracle Virtual Assembly Builder Studio, or abctl.

5.4.17.1 Deleting an Assembly Archive using Oracle Virtual Assembly Builder Studio

Delete an assembly archive from the Deployer repository by right clicking on the uploaded archive and selecting Delete Assembly Archive.

5.4.17.2 Deleting an Assembly Archive using abctl

The OVAB Admin can use the deleteAssemblyArchive command in abctl to delete the assembly archive from the Deployer repository. This operation may only be performed if there are no registrations for the assembly archive.

Example 5-49 deleteAssemblyArchive Command (without Waiting for Completion)

$ ./abctl help –command deleteAssemblyArchive
$ ./abctl deleteAssemblyArchive -name TheAssembly -version 1 -connectionName myDeployerConnection

Example 5-50 deleteAssemblyArchive Command (Waiting for Completion)

$ ./abctl help –command deleteAssemblyArchive
$ ./abctl deleteAssemblyArchive -name TheAssembly -version 1 -connectionName myDeployerConnection -waitForComplete -pollTime 30

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.18 Interacting with EM Software Library

Use these operations if you plan to use Enterprise Manager Grid Control Cloud Management Pack to perform deployment operations on assembly archives. In this scenario, you use Oracle Virtual Assembly Builder to create your assembly archive and upload it to EM Software Library. You use Enterprise Manager Grid Control Cloud Management Pack to deploy the assembly instance.

5.4.18.1 Managing Connection to EM Software Library with Oracle Virtual Assembly Builder Studio

You can manage connections to the EM Software Library by selecting Tools > Manage EM Software Library Connection. The EM Software Libary Connection Manager dialog appears (Figure 5-13), which allows you to add, edit, or delete connections for uploading assembly archives to EM Software Library. You can create only one connection to EM Software Library.

Figure 5-13 EM Software Library Connection Manager

Description of "Figure 5-13 EM Software Library Connection Manager"

To create the connection to EM Software Library:

1. Select the create icon.

2. Configure the following connection properties:

   • EM Host: enter a host for the connection.

   • Port: enter a port for the connection.

   • EM Username: enter the username for accessing Enterprise Manager.

   • SSH Port: Enter the SSH port for the connection.

   • SSH User: Enter the SSH user for the connection.

   • SSH Authentication: Select Password and enter a password or select Private Key to reference the SSH key to use rather than providing a password. If selecting Private Key, select the browse button and navigate to the location of a private SSH key file on the local machine. The use of a private key file provides added security because no password handling is required by Oracle Virtual Assembly Builder.

   • Working directory: Enter the working directory where assembly archives are uploaded to Oracle Software Library.

   • Named host credential: Enter the named host credential that specifies authentication information for Oracle Software Library.

3. Click Test Connection to verify that you can successfully connect.

4. Click OK.

To edit the connection to EM Software Library:

1. Select the connection in the Connections pane.

2. Select the edit icon.

3. Updates the connection properties as required.

4. Click OK.

To delete the connection to EM Software Library:

1. Select the connection in the Connections pane.

2. Select the delete icon.

3. Confirm the deletion.

5.4.18.2 Creating a Connection to Oracle Software Library Using abctl

You can configure a connection to the Oracle Software Library using the createEMConnection command in abctl. The connection to Oracle Software Library is persisted in a connections file.

You must specify the fully qualified hostname of the remote Enterprise Manager machine, for example myhost.example.com instead of myhost.

Example 5-51 createEMConnection

$ ./abctl createEmConnection -connectionURL emMachine:7791 -connectionUser admin -namedHostCredential hostCredential -remoteUser mySshUser -remoteWorkingDir /scratch/myovas [-sshPort 23] [-privateKeyFile ~/.ssh/id_rsa]

You are prompted for a connectionPassword.

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.18.3 Uploading an Assembly

You can upload an assembly archive from Oracle Virtual Assembly Builder Studio Catalog to Oracle Software Library using Oracle Virtual Assembly builder Studio or abctl.

To upload an assembly archive in Oracle Virtual Assembly Builder Studio, right click the assembly and select Upload Assembly Archive > EM Software Library.

To upload an assembly archive in abctl, use the uploadEMAssemblyArchive command in abctl. The assembly archive must have been created with the assembly.

Example 5-52 Upload an Assembly to Oracle Software Library

$ ./abctl uploadEMAssemblyArchive -name archiveName -description "my assembly archive"
 Assembly archive upload started
  Assembly archive upload at 10%
  Assembly archive upload at 20%
  Assembly archive upload at 30%
  Assembly archive upload at 40%
  Assembly archive upload at 50%
  Assembly archive upload at 60%
  Assembly archive upload at 70%
  Assembly archive upload at 80%
  Assembly archive upload at 90%
  Assembly archive upload at 100%
  Assembly archive upload complete
  Assembly archive version 0.1 uploaded
  Successfully uploaded the assembly archive mySite to EM Software Library.  Check the status of the assembly archive with describeEMAssemblyArchives before using.

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.18.4 Describe Assembly Archives in Oracle Software Library

You can list the assembly archives and their versions present in Oracle Software Library using the describeEMAssemblyArchives command in abctl:

Example 5-53 Describing the Assembly Archives in EM Software Library

$ ./abctl describeEMAssemblyArchives [-name nameOfAssemblyArchive]

------------------------------------------------
Name   | Version | Description | Status
------------------------------------------------
mySite | 0.3     | mysite3     | READY
       | 0.2     | mysite3     | READY
       | 0.1     | mysite3     | READY
------------------------------------------------

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.18.5 Deleting an Assembly Archive from Oracle Software Library

You can delete the specified version of an assembly archive from Oracle Software Library using the deleteEMAssemblyArchive command in abctl.

Note:

Do not attempt to delete an assembly archive until its status is READY from the describeEMAssemblyArchives command. See Example 5-53, "Describing the Assembly Archives in EM Software Library" for example output.

Example 5-54 Delete an Assembly Archive from Oracle Software Library

abctl deleteEMAssemblyArchive -name archiveName -version 1.2

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.

5.4.18.6 Downloading an Assembly to Oracle Virtual Assembly Builder Catalog

You can download an assembly from the EM Software Library to the Oracle Virtual Assembly Builder Studio Catalog using Oracle Virtual Assembly Builder Studio or abctl.

To download an assembly using Oracle Virtual Assembly Builder Studio, right click the assembly in the EM Software Library view and select Download Assembly Archive.

Note:

Do not attempt to download an assembly archive until its status is READY from the describeEMAssemblyArchives command. See Example 5-53, "Describing the Assembly Archives in EM Software Library" for example output.

The assembly archive is reverse engineered to have the Oracle Virtual Assembly Builder metadata, file sets and templates created and persisted in the Oracle Virtual Assembly Builder Studio catalog.

To download an assembly from Oracle Software Library to the Oracle Virtual Assembly Builder Studio Catalog, use the download command in abctl.

Example 5-55 Download an Assembly

abctl downloadEMAssemblyArchive -name archiveName -version 1.0 -force -downloadAs newName

For more information see Appendix A, "Command Line Reference", which contains the details of the parameters that can be passed into the command.