Using IBM Image Construction and Composition Tool

Best practices to start building virtual appliances on IBM PowerVM cloud providers

This article aims to provide common best practices when working with the IBM® Image Construction and Composition Tool® (ICCT) to design and build virtual appliances on IBM PowerVM® cloud providers.

Jose M. Romo Corona (, Technical Consultant, IBM

moisesrcJose Moises Romo Corona is a Technical Consultant in the Solutions Enablement organization in IBM Systems and Technology Group. He has around six years of experience with IBM. He graduated in Computer Science and Electronics from Universidad del Valle de Atemajac. His areas of expertise include Web 2.0 Development, Linux, and system administration for IBM Power Systems™ . You can reach him at

02 April 2013

Also available in Chinese


The IBM Image Construction and Composition Tool (ICCT), also known as ICON, is part of the IBM Virtual Appliance Factory tools. ICCT implements a consistent methodology to design and build Open Virtualization Appliance (OVA) files across multiple cloud provider architectures, such as IBM PowerVM, kernel-based virtual machine (KVM), and VMware. An OVA file is a portable self-contained binary package that includes metadata and several software artifacts such as operating system, middleware, software packages, and applications at the top. In the case of an IBM PowerVM cloud provider, these software artifacts are part of a raw disk file and are configured by the Virtual Solution Activation Engine (VSAE) at deployment time. Virtual hardware resources are defined within the Open Virtual Machine Format (OVF) file included in the OVA.

This article is intended to share some of the common best practices when working with Image Construction and Composition Tool 1.2 to create virtual appliances on IBM PowerVM Express cloud providers running on IBM Systems Director or IBM Flex System Manager™ (FSM) and secure copy services-based image repositories. This type of image repository is discovered on a Virtual I/O Server (VIOS) operating system and supports virtual appliances containing IBM AIX®, IBM i, and Linux® on IBM Power Systems™ raw images. Raw images can be deployed in IBM Systems Director VMControl™.

The activation engine

The IBM Virtual Solutions Activation Engine orchestrates the configuration of software components within a virtual appliance at deployment time. This technology compliments the Distributed Management Task Force (DMTF) OVF standard. ICCT helps you to create the software bundles and all metadata required by the activation engine in a transparent fashion.

The activation engine is installed among other software components in the virtual appliance, and its base directory is:





Virtual appliance development process in ICCT

Basically, ICCT works with two type of assets: Software bundles and images. A software bundle defines the way in which a software binary or an application is installed and how it is configured and reset by the VSAE. A software bundle consists of three different operations: Install, configuration, and reset. Each operation runs at different time depending on the image task being performed.

On the other hand, a virtual appliance or virtual machine image is a software stack designed to run on a specific hypervisor. An image being used in ICCT to create new virtual appliances is called a base image. A base image is the binary baseline entity that you need to extend in order to add additional software solutions. ICCT helps you to repackage the base image along with additional software to create a new virtual appliance.

The main image tasks in the ICCT virtual appliance development cycle are: Import, extend, synchronize, capture and export. The deploy task is performed outside ICCT by using the VMControl deploy wizard in FSM or IBM Systems Director. The IBM SmartCloud® Entry also supports the deployment of virtual appliances making it easier for the user.

Figure 1 depicts all the steps involved in the virtual appliance development process, up to the deployment. This is a brief description of each step:

  1. Prepare base image: The preferred software stack is installed and configured on a target virtual server, which can be used to perform an import of a base image in ICCT. A base image can also be imported directly from an existing OVA file.
  2. Import base image: ICCT can import an existing image from the image repository or import from a running virtual server. ICCT gets the image metadata during the import, whereas, the binary image stays in the cloud provider image repository.
  3. Create software bundles: There are three basic operations being used in a software bundle:
    • Installation: This is performed once during image synchronization (runs during step 5). All installation files are uploaded onto a deployed running virtual system. Upon upload completion, the install command runs.
    • Configuration: This is performed by the activation engine during deployment (runs during step 9). This operation occurs every time the virtual appliance is deployed. The activation engine orchestrates the activation by validating any service dependency and passing the argument values that are entered by the user to the corresponding configuration or activation script.
    • Reset: This occurs just before the image capture process starts (runs during step 6). This operation is meant to return the deployed virtual system to an initial state. For instance, if you extend an IBM WebSphere® Application Server base image, which creates a profile during the deployment, a profile will be created during the extended image synchronization. The reset script should stop the application server and then delete the created profile before the capture. Otherwise, it will be part of the new virtual appliance.
  4. Extend base image: ICCT makes a copy of the base image metadata allowing you to add your software bundles to start creating a new virtual appliance.
  5. Synchronize: During synchronization, the base image is deployed onto a cloud provider host. This creates a new virtual system on which the capture process will be performed. ICCT accesses the deployed virtual system using Secure Shell (SSH). Installation files are uploaded using Secure Copy Protocol (SCP) onto the deployed running virtual system under the /tmp directory. Upon upload completion, ICCT runs the install command defined in the software bundle.
  6. Capture: This results in a new virtual appliance which is stored into your cloud provider image repository. There are several subprocesses involved in this task:
    1. Discover the virtual system's operating system in FSM or IBM Systems Director.
    2. Request access to the virtual system's operating system using the credentials provided during synchronization.
    3. Collect inventory on the virtual system's operating system.
    4. The activation engine performs all required reset operations.
    5. The virtual system is stopped.
    6. After the virtual system is stopped, the capture process starts. Here, a new virtual appliance gets created in the image repository.
    7. After the virtual appliance is created, ICCT adds all required product section elements into the OVF envelope file. The activation engine uses this product information to allow the interaction between the user and software bundle configuration scripts at deployment time.
  7. Export: ICCT extracts the raw disk from the cloud provider image repository. This is packaged along with the OVF envelope file and other metadata into a compressed file, which is saved into a target system.
  8. Import OVA: The file is decompressed and imported from an Hypertext Transfer Protocol (HTTP) server.
  9. Deploy: This task is performed outside ICCT as many times as required by using VMControl on either FSM or IBM Systems Director. The VMControl deploy wizard allows you to provide all configuration parameters required to deploy your virtual appliance onto a new virtual server. The IBM SmartCloud Entry also supports the deployment of virtual appliances.
Figure 1. Virtual appliance development process in ICCT
Virtual appliance development process in ICCT

Image tasks and software bundle operations

The key element of a software bundle is the executable script that performs each operation. The understanding of the relationship between image tasks and software bundle operations is important before starting to write such scripts.

The relationship between software bundle operations and image tasks is shown in table 1.

Table 1. Image tasks and bundle operations relationship
Image taskSoftware bundle operation
Import -
Extend -
Synchronize Installation
Capture Reset
Export -
Deploy Configuration

Best practices for software bundles

You should consider the following best practices when designing your software bundles:

  1. You can use any programming language supported in the base image operating system to write your scripts, this includes shell scripting (recommended).
  2. If you use a text editor in Microsoft® Windows® to write a shell script file, ensure to convert its Disk Operating System (DOS) format to the UNIX® format. DOS newline characters prevent the script to run. You can install CygUtils for Windows and convert the format using the dos2unix command.
  3. Ensure that command arguments are parsed correctly on every script in the same way these are defined in the software bundle operation.
  4. Always use unique names without blank spaces for each configuration operation.
  5. There are two options when creating software bundles to install and configure applications:
    1. Install during image synchronization and configure during deployment.
    2. Install and configure during deployment. Some applications may be difficult to reconfigure after they have been installed and the best approach is to perform both steps when the virtual appliance is deployed. Also, some applications may require an activation license key during the installation which is entered and accepted by the user. Further, some licenses may have dependencies on the system serial number or partition ID. Take into account that this approach makes the deployment process longer.
  6. Use the print work directory command, pwd, to have access to your installation files after they are uploaded to the running virtual system.




  1. Large install files (in the range of gigabytes) can be available into an internal Network File System (NFS) server or File Transfer Protocol (FTP) server. You can add the necessary logic on your install scripts to transfer the install files into the active virtual system, during image synchronization.
  2. If there is a script included in a configuration operation which needs access to files under the configuration or reset script directory, the path should be defined as follows:


MY_ACTIVATION_DIR=`dirname $0`
MY_RESET_DIR=`dirname $0`


MY_ACTIVATION_DIR=$(dirname $0)
MY_RESET_DIR=$(dirname $0)
  1. If there are files required by a configuration script, you can also upload them to a well-known directory during the image sync-install operation, and use this directory in the configuration scripts.
  2. If a software bundle contains a configuration operation which is used to create a new base image, then it must include a reset operation to return the deployed virtual system to an initial state before the capture operation starts.
  3. If you need to define service dependencies, use sequence numbers to name each configuration operation. For example, if you are deploying an enterprise application running on a WebSphere Application Server instance, which has a dependency of a database configuration on IBM DB2®, then you can define operation names as follows:
    1. 01Activate.DB2 : This configures the DB2 product. This has network configuration dependencies, for example, activate.vmc.system-networking and
    2. 02Activate.EnterpriseApplicationDatabase : This creates and configures the application database. It is dependent on 01Activate.DB2.
    3. 03Activate.WAS : This creates the WebSphere Application Server profile and starts the application server. It is dependent on 02Activate.EnterpriseApplicationDatabase.
    4. 04Activate.EnterpriseApplicationOnWAS : This installs and configures the enterprise application in WebSphere Application Server. It is dependent on 03Activate.WAS.

Notice that these configuration operations could be in one software bundle or in different separate software bundles.

  1. Only one script can run by each command operation. If more scripts need to run, these should be marked as executable and must be called from the main script.

Notes about IBM i scripting

Take into account the following, regarding software bundle scripts for IBM i:

  • Install files are uploaded into the QOpenSys file system during image synchronization. Use the CPYFRMSTMF command in case you need to copy any data from your install operation files into a file member or save file located at the integrated file system.
  • If you need to test a Portable Application Solutions Environment (PASE) shell script manually, use the call qp2term command to run your script.
  • Set environment variable, QIBM_SYSTEM_ALWMLTTHD, to not allow multithreading during install operations.
  • Avoid the use of flag i for system calls.
  • If there is a CL program that is required to run during deployment, and it calls a CL command that is not supported to run on a multithreaded job, then you need to call this CL program using the submit job command, SBMJOB.

Notes about user authority when writing installation and configuration scripts

ICCT allows you to specify the user who is required to run every software bundle operation. However, consider the following notes when additional user authority is needed:

  • On AIX/Linux, the install, reset, and configuration operations run as root by default. If a command must run under a different user ID, you can use su. If you specify a user other than root, such user should exist in the base image.
  • On IBM i, install and reset operation scripts can be run under QSECOFR user because its authority is required to perform most install and uninstall tasks. However, configuration operations are startup services that run once during the deployment, under the QPGMR user. If security officer authority is required at configuration time (virtual appliance deployment), you can generate a profile handle in a CL program to change the current job to be owned by the QSECOFR profile. This CL program can be created during the sync-install operation and must be owned by QSECOFR and adopt *OWNER authority. You can find an example in the IBM i 7.1 information center website.

Best practices for image tasks

Before you begin working with image tasks, it is important to consider that images are not stored in ICCT. After an image is imported, ICCT only keeps metadata of the image located in your cloud provider image repository. This implies that:

  • Virtual appliance metadata is not updated automatically in ICCT. For instance, ICCT will not update a virtual appliance OVF if this was updated in the image repository. You need to reimport the image so that the changes can take effect.
  • A virtual appliance is not removed or deleted from the cloud provider image repository if you delete it in ICCT.

The image tasks that are described in the following sections are implemented on base images to create new virtual appliances. Base images are created in the cloud provider image repository. You can use ICCT to either import base images located in the image repositories or capture a running virtual server to inject the activation engine software and create a new base image. You can find detailed information about creating base images in the IBM Redbooks®, Creating Smart Virtual Appliances with the IBM Image Construction and Composition Tool.

ICCT image tasks covered in following sections are: Import, extend, synchronize, capture, and export. The procedure to deploy is not covered here due to the fact that this is done outside ICCT.


There are two options available in ICCT to import images. You can import a base image directly from a cloud provider or import an image from a running virtual server.

  • Import from a running virtual server or virtual machine: You can perform this operation after the discovery and access of the operating system resource that runs on your virtual server. You also need to run an inventory job on the operating system resource using the All Inventory profile. Although ICCT will perform the required tasks to capture the virtual server, you can verify whether a virtual server can be captured in FSM/IBM Systems Director. The Capture option is available when you right-click the virtual server resource and click System Configuration, as shown in Figure 2.
Figure 2. Capture option in IBM Systems Director/FSM
Capture option in IBM Systems Director/FSM

For more information about the import option, refer to the ICCT information center website

  • Import from cloud provider: Ensure that you have the correct base image user name and password required for synchronization


Take into account the following recommendations before extending a base image:

  1. Ensure that SSH is installed by default in the base image.
  2. Ensure that you have the correct user credentials to access the deployed virtual system and perform the install operation.
  3. Ensure that the base image is shipped with a reset operation which takes the deployed virtual system back to an initial state before the capture operation is performed.
  4. Ensure that the base image meets the minimum system requirements for the software and middleware components that will be installed during the synchronization.
  5. Ensure that the file system free space is available in /tmp to transfer all the files required by every install operation.
  6. Ensure that the limit size of a file and data area in the ICCT system and the base image exceeds each bundle file size. You can set the file and data size as unlimited by issuing the ulimit command as follows:
$ulimit -f -1
$ulimit -d -1

The ulimit command is available in AIX, Linux, and IBM i PASE.

  1. If you need to add service dependencies in your bundles, ensure to have the names of the operating system services and activation engine services (configuration operations), which are available in the base image. You can deploy your base image directly in VMControl to validate startup services by looking at the following directories, depending on your operating system:







Only the service name should be used within the software bundle service dependencies, for example,, sshd, and network.

Extending the base image

When a base image is extended in ICCT, you are prompted to provide a name, unique universal ID, and version. Although the description is optional, you can use it to provide useful information about the operating system, installed service packs, or any additional information that you consider important. This information is shown in VMControl, and helps the user to identify the software solution that is provided by the virtual appliance.

After extending the base image, the next step is to add software bundles.

Adding software bundles

Take in to account the following recommendations when adding software bundles to an extended image:

  1. You need to provide all required installation parameters for each software bundle.
  2. All bundle dependencies for installation are met, which means all bundles are added in the correct order. You can move a bundle up or down in ICCT to meet dependencies.
  3. Software bundles requiring previous configuration from the activation engine or operating system services should have all service dependencies defined.
  4. If you update a software bundle that is already added in to an out-of-sync image (extended image), remove the bundle and add it again so that the changes can take effect.
  5. After you finish editing the new image, click Done Editing and then Save.


During this operation, ICCT instructs the cloud provider to deploy the base image onto a target host. This operation creates a new virtual system where the base image is deployed. ICCT uses the cloud provider network information to fill in all network parameters required by the base image. The first free IP address in your cloud provider is taken to configure the first Ethernet adapter defined in the VirtualHardwareSection section of your base image OVF file.

Validate the following steps before synchronizing a new image:

  1. A virtual server using the same network configuration of the one being created by ICCT does not exist in the cloud provider.
  2. Free space is available in the cloud provider storage pool to allocate the base image disk. The disk capacity is defined in the OVF element DiskSection. For example:
<ovf:Info>Disk Section</ovf:Info>
<ovf:Disk ovf:capacity="9797894144"
ovf:capacityAllocationUnits="byte" ovf:diskId="disk1"

Refer to the Shaping virtual appliance OVF using REST APIs section in case you need to retrieve the OVF file to accommodate more disk capacity.

  1. Ensure that the first Ethernet adapter name Connection defined in the OVF element VirtualHardwareSection matches the correct virtual network ID of your cloud provider host. This information is used to map the base image virtual Ethernet adapter with a virtual network on the target host. The virtual appliance deploy wizard in VMControl can be used to validate the mapping, as shown in Figure 3.
Figure 3. Network mapping between base image and Power Systems host
Network mapping between base image and Power Systems host

Click to see larger image

Figure 3. Network mapping between base image and Power Systems host

Network mapping between base image and Power Systems host

The first network defined in the base image OVF should match the name of your host bridged virtual network. Refer to the Shaping virtual appliance OVF using REST APIs section in case you need to update the OVF file.

Synchronized image

After the new image is synchronized, you need to validate the following:

  1. Open the Virtual System section of your synchronized image to display the active system (virtual server) details. Log into the system and validate the services in the following directory:







When issuing the ls -al command in PASE (IBM i) or in the AIX/Linux command line, all services should be listed in the correct order according to your service dependencies.

  1. On AIX/Linux, delete the /etc/ovf-transport/ovf-env.xml file if it exists. Otherwise, the virtual server takes the properties defined here as an input for network configuration every time the system is restarted if the activation engine was not properly reset.
  2. Validate whether all software bundle configuration and reset operations are included correctly in the master activation logic file. This file is located under the activation logic directory mentioned below:


  1. On AIX/Linux, if the deployment process is taking more than an hour, then you need to include the following code in one of your activation scripts.
cp /tmp/activation-engine-*/ovf-env.xml /opt/ibm/ae/AP

This is because during a deploy operation, the values entered by the user on the OVF Product Section fields are placed in a DMTF standard OVF environment document named, ovf-env.xml. This XML file is placed in a virtual CD image and loaded into a virtual CD drive on the virtual server under /tmp. During the deployed virtual server's first boot, the activation engine locates the OVF environment document on the CD and processes the user input. VMControl then removes the virtual optical device an hour after the deployment.

  1. Verify whether the following directories are empty:

Ensure that there is no file named, noap in the AP directory. The presence of this file prevents the activation engine from attempting to locate an OVF environment file.

  1. Optionally, you can request access directly to the active virtual system in FSM or IBM Systems Director. This can help you to catch a failed capture due to a timeout error when ICCT attempts to unlock the system during the capture operation.
  2. Do not delete the virtual server resource directly in FSM/IBM Systems Director. An Object ID (OID) is assigned to this resource, which is kept by ICCT as a reference to perform the capture.


During the capture operation, ICCT instructs the cloud provider to capture the active virtual system. This process results in a new virtual appliance. ICCT builds the OVF envelope file by adding a product section for each configuration operation defined in the software bundles. A product section is defined within the ProductSection element in the OVF envelope file. Configuration argument values received by an activation or configuration script are translated into product section properties. These properties are exposed to the user in the product settings page at the VMControl virtual appliance deploy wizard, as shown in Figure 4.

Figure 4. OVF product sections and product settings mapping
OVF product sections and product settings mapping

You need to perform the following steps to monitor the capture process:

  1. Issue the following command in the ICCT system to track the log entries:
tail -f /drouter/ramdisk2/mnt/raid-volume/raid0/logs/error/trace.log
  1. Validate that the activation engine performed all the required reset operations. The log should include the reset command mentioned below: --reset

Upon reset completion, the virtual server is turned off automatically.

  1. A Stopped state is shown in Systems Director/FSM on the virtual server in order to proceed with the capture and be able to continue building the OVF file. The system state can be updated manually by running an inventory job, targeting the VIOS or the Power Systems host, using an All inventory profile. Do not attempt removal and rediscovery of the virtual server, as this assigns a new OID, and ICCT would not be able to perform the capture again if something fails.
  2. Verify whether the OVF envelope file is built. The ICCT log file should include the new virtual appliance OVF content.
  3. Log in to the FSM/IBM Systems Director and go to System Configuration > VMCotrol > Virtual Appliances and verify whether the new virtual appliance is displayed.

Finally, you may want to deploy the newly created virtual appliance in VMControl and validate the activation.


Before exporting an OVA file using the PowerVM appliance format in ICCT, you need to verify the following points.

  1. Image repository credentials are set correctly in ICCT.
  2. One time of the image size is available in the VIOS /home/<user ID> directory (for example, /home/padmin), which is holding the extracted copy of the disk image.
  3. The target system must have two times the image size in free space (copy of raw disk image and OVA must exist simultaneously).
  4. The raw disk image is transferred directly to the target system. The target system must be able to connect to the storage system and the VIOS. Normally, the ICCT system itself is used to export the OVA files.

Previous sections covered some of the best practices for each of the image tasks in ICCT. After the export is completed, you can test the import in VMControl to make sure whether any of the OVA file is corrupted and your OVA is ready to be distributed. The recommended import method is to provision your virtual appliance files using HTTP. You can decompress the file by issuing the jar (Java archive) command:

jar -xvf <virtual_appliance_name>

Java™ 5 or later is required.

Split and validate large OVA files

The OVA compressed files created by the ICCT export operation, may be too large for most of the virtual appliances, especially for IBM i. The split command can be used on Linux, IBM I, or AIX to split the OVA compressed file into smaller pieces. Perform the following steps in order to split the OVA compressed file in AIX.

  1. Move to the directory where the OVA zip file is located.
  2. Issue the following command:
split -b <size>m input_file file_prefix

A size equal to 1024 MB can be used as follows:

split -b 1024m aix_base_scs_image.ova_
  1. Verify whether the files are generated as follows:

Where aN → ac, ad, ae … aN

  1. Rename the files as follows:
mv aix_base_scs_image.ova_aa
mv aix_base_scs_image.ova_ab
mv aix_base_scs_image.ova_aN

After the smaller files are ready, you can merge again by issuing the following command:

cat aix_base_scs_image.ova_* >

It is recommended to validate the files' integrity using MD5 hashes if you need to transfer these files to a different location. Perform the following steps to install the md5sum command in AIX and check MD5 hashes.

  1. Download the coreutils RPM from AIX Toolbox. Install it using the following command:
rpm -iv coreutils-5.2.1-2.aix5.1.ppc.rpm
  1. Get MD5 hashes for each file and redirect the output to a file.
/usr/bin/md5sum >> MD5SUMS
/usr/bin/md5sum >> MD5SUMS
/usr/bin/md5sum >> MD5SUMS
  1. If the OVA files are transferred to a different location along with the MD5SUMS file, then you can validate all MD5 hashes as follows:
/usr/bin/md5sum -c MD5SUMS OK OK OK

Shaping virtual appliance OVF using REST APIs

The IBM Systems Director Representational State Transfer (REST) application programming interfaces (APIs), which are also available in the FSM, can be used to update the OVF envelope file for a given virtual appliance to accommodate its logical resources and meet your requirements or environment configuration. There are different browser plug-ins that can help you to submit any HTTP request method supported by the REST APIs.

Mozilla Firefox plug-ins

Poster: This tool can be used to submit all HTTP requests supported by the REST APIs. Download the Poster Firefox plug-in from the Firefox Add-ons website. A similar plug-in named REST Console is available for Chrome.

JSONView: This plug-in displays formatted JavaScript Object Notation (JSON) content within your Firefox browser. Download the JSONView plug-in from the Firefox Add-ons website. This plug-in is also available for Chrome.

Getting the virtual image OVF envelope file

Perform the following steps to retrieve a virtual appliance OVF file using REST APIs.

  1. Enter the following URL in your browser or Poster plug-in and submit a GET request. This retrieves all available virtual appliances.
https://<FSM or ISD host>:8422
  1. Locate the required virtual appliance object ID, as shown in Figure 5.
Figure 5. Virtual appliance object ID
Virtual appliance object ID
  1. Open a Poster window in Firefox, and enter the following URL:
https://<FSM or ISD host>:8422
/ibm/director/rest/VMControl/virtualAppliances/{VA OID}.ovf
  1. Provide SMAdministrator user credentials in the User Auth field.
  2. Enter application/ovf+xml in the Content Type field.
  3. Click GET under Actions. A response window with the virtual appliance OVF content is opened.
  4. Copy the OVF content into your preferred XML editor.

How to resize a base image disk capacity

This task can help you to resize the disk capacity of a virtual appliance. Perform the following steps to change the disk capacity:

  1. Repeat steps 1 to 7 of the Get the virtual image OVF envelope file section
  2. You can only increase the size and never decrease the capacity. Furthermore, if you change the size, then IBM FlashCopy® is not used when the image is deployed but "dd" is used instead. Change the ovf:capacity value. The default allocation unit is byte.
<ovf:Disk ovf:capacity="73903636480"
ovf:capacityAllocationUnits="byte" ovf:diskId="disk1"
  1. Copy the modified OVF content and paste it in to Poster Content filed.
  2. Remove the .ovf extension from the URL.
  3. Click PUT. A response status 200 is received if the update was successful. This action updates the virtual appliance OVF.
  4. After the OVF file is updated, import the image in ICCT or reimport it if the image already exists.
  5. Extend and add your software bundles and synchronize.

In AIX, you need to issue the following command in order to have the size change applied to the volume group. This command can be included into installation or configuration scripts.

chvg -g rootvg

How to map virtual appliance networks with virtual networks on host

This task is useful when importing virtual appliances that were created outside your cloud provider, and the virtual network IDs in your host are different from your environment, or if you need to add more Ethernet adapters to your current virtual appliance. If the first Ethernet adapter connection name defined in the virtual appliance OVF does not match any of the virtual networks IDs on the host, then VMControl maps it to the first virtual network available on the host. This can lead to lack of connectivity between the deployed virtual system and ICCT.

Perform the following steps to map a host virtual network to a virtual appliance Ethernet adapter.

  1. Repeat steps 1 to 7 of the Get the virtual image OVF envelope filesection.
  2. Verify whether the NetworkSection element includes a network name equal to the target host virtual network ID. The Network Mapping page in the VMControl Deploy Virtual Appliance wizard shows both, the virtual appliance network name and the host virtual network ID, as shown in Figure 6.
Figure 6. Network Mapping page in VMControl deploy wizard
Network Mapping page in VMControl deploy wizard
  1. Submit a GET request using the following URL. This retrieves all the hosts managed by FSM or IBM Systems Director.
https://<FSM or ISD host>:8422/ibm/director/rest/VMControl/hosts
  1. Submit a GET request using the following URL. This retrieves the virtual network IDs on the host.
https://<FSM or ISD host>:8422
/ibm/director/rest/VMControl/hosts/{Host OID}/customization

Figure 7 shows an example of the virtual network IDs on the host.

Figure 7. Virtual network IDs on the host
Virtual network IDs on the host
  1. Update the virtual appliance OVF using the correct virtual network ID on the host as a value for the Network name and the Ethernet adapter Connection, as shown in the code below. The value should be the same for (1), (2), and the virtual network ID on the host found in the previous step.
<ovf:Info>Network Section</ovf:Info>
<ovf:Network ovf:name="Discovered-1-0">(1)
<ovf:Description>Captured from virtual server vm1877</ovf:Description>
<ovf:VirtualHardwareSection ovf:transport="iso">
<rasd:Caption>Ethernet Adapter Allocation</rasd:Caption>
<rasd:ElementName>Network adapter 1 on Discovered-1-0</rasd:ElementName>
  1. In order to update the OVF file, use steps 4 and 5 of the How to resize a base image disk capacity section.

Adding product sections manually in the OVF file

A virtual server capture process in FSM or Systems Director may result in a time consuming task, especially for large images. At some point, the capture operation in ICCT might fail despite the virtual appliance being created in the image repository. This might cause a misconfiguration in its OVF file. There could be performance issues with the storage system preventing the ICCT from getting the newly created virtual appliance OVF in a timely manner to add the required product section elements.

The capture might also fail due to Common Agent Services (CAS) communication problems between the management server and the managed virtual system.

Perform the following steps to add an OVF product section for each configuration operation defined in a software bundle only when an OVF is created without the activation definitions, or if the virtual server was captured directly in VMControl.

  1. Repeat steps 1 to 7 of the Get the virtual image OVF envelope file section.
  2. Use the bundle configuration operation name as the value for the ovf:class property within the ProductSection element.
  3. Use each configuration argument in your software bundle to define the product section properties, as depicted in
Table 2. Values for OVF product section properties
OVF product section propertyValue
ovf:key Configuration argument name
ovf:type Based on the valid argument value, for example:
unit32 - numericstring - strings
ovf:userConfigurable true - user is allowed to enter a value.
false - the parameter is disabled. User can not enter a value.
ovf:value Empty or default argument value
ovf:msgid Argument label. Name convention - <product section class>.<configuration argument name>.label

You can use Figure 8 as an example.

Figure 8. Product activation properties mapping
Product activation properties mapping

Virtual appliance upgrade

A virtual appliance cannot be updated by directly inserting new activation logic or upgraded software binaries in the raw image. Once the virtual appliance is deployed, and it is running on a virtual server, the software upgrade and maintenance is business as usual.

If a virtual appliance must be upgraded to be deployed multiple times, then it is recommended to build new software bundles. ICCT allows you to extend a bundle to create a new version, where you can update all required binaries. After the new bundles are updated with the latest software, you need to repeat the same steps of extend, synchronize, and capture in order to create a new virtual appliance.


Software bundles are the core reusable assets that are needed to build new virtual appliances. ICCT allows the export and import of software bundles easily, leading to a collaborative environment for virtual appliance development on different cloud provider architectures. Although a specific programming language for software bundle scripts is not mentioned here, shell scripting for AIX/Linux and PASE shell for IBM i are the easiest way to go. An Eclipse plug-in named Product Activation Development Kit is also available to develop software bundles using Python. The advantage of using the Product Activation Development Kit besides Python's portability, is its ability to run and debug bundle operations from the Eclipse integrated development environment (IDE).

A virtual appliance should be able to be configured by itself during the deployment. However, each application and middleware has its own challenges to achieve this. Furthermore, a user interactive customization in VMControl is not yet supported. However, ICCT aims to provide the means by which a user can interact with the virtual appliance configuration during deployment, by using the logic within your software bundle scripts.




  • IBM Systems Director forum: Post your IBM System Director questions and comments, and share your thoughts, ideas, and solutions with other users.


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into AIX and Unix on developerWorks

Zone=AIX and UNIX
ArticleTitle=Using IBM Image Construction and Composition Tool