VADeployer - a Java SWT REST client application

Configure and deploy virtual appliances through VMControl

A Standard Widget Toolkit (SWT) Java™ desktop application was developed taking advantage of the flexibility and ease of use of the IBM® Systems Director Representational State Transfer (REST) application programming interfaces (APIs). You can use this application to configure, at deployment time, each product section within a virtual appliance Open Virtualization Format (OVF) descriptor as well as memory and processor allocation settings for a new virtual server.


Jose M. Romo Corona (, Technical Consultant, IBM

Jose 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

01 November 2012

Also available in Chinese


The application developed as part of this article is called VADeployer, which implements Hypertext Transfer Protocol Secure (HTTPS) requests to IBM Systems Director VMControl™ REST APIs to mimic the IBM Systems Director web interface deployment process for virtual appliances. VADeployer also allows you to modify additional settings, such as memory and processor allocation before deployment.

VADeployer is built upon Java 1.6 and the graphical user interface (GUI) was developed using Eclipse Juno and WindowBuilder Pro SWT, which is under Eclipse Public License v 1.0. The REST API version used by VADeployer for IBM Systems Director and VMControl is 6.3.0 and 2.4.0 respectively.

In the next sections, you will find an introduction about the relationship between VMControl and the virtual appliance model to give you an idea on how VADeployer interacts with VMControl to configure and deploy a virtual appliance.

Virtual appliances and VMControl

IBM along with other vendors in the virtualization market space have adopted the Distributed Management Task Force (DMTF) OVF specification as a standard way of building and deploying software virtual appliances, and simplifying the integration of complex software solutions in a self contained binary Open Virtualization Appliance (OVA) package. VMControl enables you to import virtual appliances (taking an OVA package or OVF file as an input) and store it into an image repository. You can also capture a virtual server where your software solution is configured and running to create a new virtual appliance into an image repository.

Within an image repository, which can be Network Installation Management (NIM) or Storage Copy Services (SCS) based, you can have multiple virtual appliances containing a different software solution. Based on your business needs, you can choose a virtual appliance from your catalog and rapidly deploy it, making it aware of its deployment context. VMControl enables you to specify the configuration values for every product section defined in the virtual appliance OVF file. A product section can refer to networking, OS tuning, OS security, or any software product configuration that should be done at deployment time. Virtual appliance creation is a different topic, not covered in this article, which is addressed by the Virtual Solutions Activation Engine (VSAE) solution, a scripting engine that starts on the first boot before the application services are activated. Basically, VSAE parse the OVF envelope file (default name is ovf-env.xml) and based on a well-defined activation logic, the activation engine passes all configuration parameters to the correct activation script, which performs the required configuration.

Customization properties

Each configurable property within a product section in the OVF file is translated into a customization property in VMControl. You can retrieve all customization properties that allow you to configure your virtual appliance at deployment time by using VMControl REST APIs. For instance, you can submit a GET action to the REST API that is shown in Listing 1 to retrieve the customization properties available at deployment time for a virtual appliance that will be deployed on a specific target host, which means that you can find the properties that are available, based on the host resources and the OVF file describing your virtual appliance.

Listing 1. REST API to retrieve deployment-time customization properties

IBM Systems Director supports different virtualization environments, including VMWare ESX/ESXi, IBM PowerVM®, kernel-based virtual machine (KVM), and IBM z/VM®. VADeployer was only tested on PowerVM though. Within the OVF file, the Virtual Hardware Section describes the virtual or logical hardware required by the virtual appliance such as disks, network adapters, memory and processor allocation, and so on. This section also includes the virtual system type (a direct child element of System), which specifies the virtualization environment where the virtual appliance can be deployed. For example, a virtual system type identifier can be set to vmx-4 for VMware fourth-generation virtual hardware or IBM:POWER:[OS] for IBM POWER® processor-based hardware, where [OS] can be either AIX, Linux® or IBM i[X] (X is the IBM i version). Depending on the Virtual Hardware Section description, VMControl allows you to select the correct target host, where your virtual appliance can be deployed.

You can retrieve all valid target hosts where you can deploy your virtual appliance by sending a GET action to the REST API that is shown in Listing 2.

Listing 2. VMControl REST API with target host filter

Although VMControl enables you to select an existing virtual server or a system pool as a deployment target, VADeployer only supports the host type.

Typically, every customization property has the following attributes:

  • name
  • description
  • type
  • value
  • rules

Basically, the type and rules attributes determine what a valid value should be. In the case of OVF product sections, the type is set to ovf and there are no rules. A customization property example for an OVF product section is shown in Listing 3.

Listing 3. OVF customization property example
 "value": "",
 "class": "",
 "type": "ovf",
 "name": "",
 "description": "Static IP address for the network adapter \"Network adapter 1 on
 "category": "Internet Protocol Version 4"

The corresponding product section within an OVF envelope file that contains this OVF customization property is shown in Listing 4.

Listing 4. OVF product section example
<ovf:ProductSection ovf:class="" (1)
<ovf:Info>Network adapter configuration for Network adapter 1 on Discovered-1-0
 <ovf:Category>Internet Protocol Version 4</ovf:Category>
 <ovf:Property ovf:key="ipv4addresses" ovf:type="string" 
 ovf:userConfigurable="true"> (2)
 <ovf:Label>Static IP address for the network adapter &quot;Network adapter 1 on
 <ovf:Description>Static IP address for the network adapter &quot;
 Network adapter 1 on Discovered-1-0&quot;.</ovf:Description>
 <ovf:Property ovf:key="ipv4netmasks" ovf:type="string"
 ovf:userConfigurable="true"> (3)
 <ovf:Label>Static network mask for network adapter &quot;Network adapter 1 on
 <ovf:Description>Static network mask for network adapter &quot;Network adapter 1 on
 <ovf:Category>Deployment use</ovf:Category>
 <ovf:Property ovf:key="order" ovf:type="uint32"
 ovf:userConfigurable="false" ovf:value="0"> (4)
 <ovf:Label>The adapter order for network adapter &quot;Network adapter 1 on
 <ovf:Description>The adapter order for network adapter &quot;Network adapter 1 on

As you can see in Listing 4, at (1) the Product Section class matches the value found in the customization property in Listing 3. Typically, each product section corresponds to a particular software product to be installed and each property element specifies application-level customization parameters. You need to take into account that those properties with the userConfigurable attribute value equal to false (4) will not be part of the customization properties included in the REST API response, and therefore, you will find only two customization properties defined for the product section (shown in Listing 4), one for each of the following properties:

  • ipv4addresses (2)
  • ipv4netmasks (3)

The OVF customization property name consists of:

product.[virtual system id].[product section class].[property key].
[product section instance]

Where the virtual system ID is specified within the OVF file in the Virtual System element and the class and instance combination is unique among all product sections.

There are optional elements that can be used in a product section to provide additional information about the software product such as product name, vendor, version, full version, product URL and vendor URL. When you retrieve the deployment customization properties using the REST API in Listing 1, these optional elements are ignored along with those properties with the userConfigurable attribute value equal to false. For instance, if a product section contains two properties, one for the OS username and other for the user password, you will find that username is set to userConfigurable="false" for the root user, and password is set to userConfigurable="true" as you expect to be able to enter your own root password at the time of deployment. In this case, the username customization property is ignored and you would need to look at the password customization property's description to figure out which user will take the value you enter.

VADeployer retrieves all OVF customization properties from the OVF XML file and not from the customization REST API so that all information about the software product, along with non configurable properties, are shown to the user, in the same way this is shown in the VMControl deployment wizard. Although every nonconfigurable property is shown, these are disabled in the VADeployer GUI.

The OVF file of a virtual appliance can be obtained by sending a GET action, using the REST API in Listing 5.

Listing 5. VMControl REST API to retrieve a virtual appliance OVF file

Defining a workload request payload

In order to deploy a virtual appliance, you need to create a workload which is a logical entity within IBM Systems Director that allows you to manage and monitor the newly created virtual server where your virtual appliance becomes alive. To define a workload, you need to specify:

  • A virtual appliance object identifier (OID)
  • A target OID. In the case of VADeployer, this is the target host OID
  • Customization properties

The customization properties are passed into an array of JSON objects with name/value pairs, collected from the response of the REST API in Listing 1 and in regards to VADeployer, using the OVF envelope file that describes the virtual appliance. The REST API used to create the workload is /VMControl/workloads. Customization properties become customization parameters after the request is received by IBM Systems Director.

Listing 6 shows an example of a request payload to create a workload.

Listing 6. JSON payload example for a workload request
 {	"name":"",
 {	"name":"",
 {	"name":"",
 {	"name":"product.vs0.My_Application_Config.password",
 {	"name":"storagemapping", (1)
 {	"name":"virtualnetworks", (2)

You must specify a value for storagemapping (1) for all virtual appliances, and this customization parameter allows you to map one or more virtual appliance's virtual disks. When you retrieve the customization properties for your virtual appliance and host combination, under storagemapping, you will find all the virtual disks that should be mapped to the available storage (storage pool or volume). Each virtual disk is identified with an ID, the corresponding ID for the virtual disk that is shown in Listing 6 at (1) is [1], so you are assigning the virtual disk ID [1] to a storage pool's OID, 4540. The storage pool OID is obtained from the poolstorages customization property.

Similarly, the virtualnetworks parameter (2) must be specified for all virtual appliances containing IBM AIX® or IBM PowerLinux® images and Linux or Microsoft® Windows® images for KVM. For network mapping, you need to provide a virtual network ID and the virtual network on host ID, which are [Discovered-1-0] and hostVnet:Discovered-1-0 respectively.

Application overview

VADeployer can run by targeting an IBM Systems Director server managing an IBM PowerVM virtualization environment. Although this application is not designed to work with KVM, the code can be modified to work with KVM hosts customization properties. Furthermore, VADeployer can run targeting an IBM Flex System Manager (FSM) managing an IBM PureFlex™ System.

VADeployer is intended to provide a rich set of examples on how to implement the VMControl REST APIs in combination with Java SWT to deploy virtual appliances from a GUI and hopefully you will be able to reuse some code from this application. VADeployer supports the following features:

  • Virtual appliance deployment to a new virtual server on a single target host. Deployment to an existing virtual server and deployment on several hosts or system pool are not supported
  • Virtual disk mapping is available for storage pools only
  • Virtual network mapping
  • Configuration of all product sections available for a given virtual appliance
  • Configuration of memory and processor allocation
  • Display workload logs and status

The code was compiled using the SWT 32-bit binary package for Windows. If you need to compile and run this application on a different OS, then you can download SWT binaries from the Eclipse downloads website and then recompile.

The code is written in a model view controller (MVC) style as follows:

  • Model: All classes contained in the package represent the virtual hardware to be configured for a virtual appliance at deployment time.
  • View: The class is the main class and contains all the GUI objects.
  • Controller: The class implements the REST API calls and processes the response data.

There is no special implementation around SWT. Developers with basic knowledge can follow up on how the data bindings are defined and how the GUI objects interact with each other.

GUI elements

The VADeployer GUI, as shown in Figure 1, consists of the following key elements:

  • Locate: Allows you to search virtual appliances and locate available target hosts.
  • Configure: Used for virtual appliance configuration, including virtual disks and virtual networks mapping, and OVF customization properties.
  • Advanced: Used to modify memory and processor allocation settings for the new virtual server.
  • Monitor: Shows the newly created workload status and log entries.
Figure 1. VADeployer GUI
VADeployer GUI

Setting up the environment

VADeployer was designed to run against a system configured with IBM Systems Director 6.3 and VMControl 2.4, managing an IBM PowerVM virtualization environment, although the code can be modified to work with KVM customization properties. VADeployer can also work by consuming REST web services from the FSM, managing an IBM PureFlex System.

Before building the VADeployer application

  1. In order to test VADeployer, your IBM Systems Director server must be set to manage virtual appliances and workloads. For specific details, visit the IBM Systems Director Information center website.
  2. Install the latest version of Eclipse IDE for Java EE Developers Windows 32 bit.

Building the VADeployer code

All the required libraries for VADeployer are included in the file. After importing the project into Eclipse and pointing to your local Java Runtime Environment (JRE) System Library in the build path, it should be built without any errors.

  1. Launch your Eclipse integrated development environment (IDE). Click Help -> Install New Software.
  2. Click the available software websites link.
  3. Enable the website with the URL You can enter this URL in the filter form for a quick search. Select the check box that is next to the website name to enable it. If this site is not available, then add a new website by using the same URL (provided in this step) for the location.
  4. Select the items: Swing Designer, SWT Designer, and WindowsBuilder Engine and then click Next.
  5. Click Next on the details page and complete the installation.
  6. Restart Eclipse.
  7. Download the file.
  8. Import the project in to the Eclipse workspace. Click File -> Import -> Existing Projects into Workspace.
  9. Select the archive file option and search for the file.
  10. Click Finish.

How to run VADeployer using Eclipse

Perform the following steps to run the VADeployer from Eclipse.

  1. Open the env.dat file located in your VADeployer-win32 Eclipse project directory. Enter your IBM Systems Director or FSM information as follows:
    	VAD_SYSTEM_PORT=8422 (This is the default port)
    	VAD_SYSTEM_PASSWORD=XXXXX (This is your SMAdministrator user's password)
    	VAD_SYSTEM_USERID=smadminuser (This is your SMAdministrator user)
    	VAD_KEYSTORE_PASSWORD=ibmpassw0rd (This is the default password
            for IBM Systems Director keystore in a new install, otherwise,
            consult your system administrator).

    Note: A log file, named vadeployer-log.txt, will be created in the same directory where the VADeployer project is located.

  2. Within your Eclipse workspace, select the main class and click Run As -> Run Configurations. Then click Java Application -> New launch configuration.
  3. On the Main tab, verify the the selected project is VADeployer-win32 and the main class is set to
  4. Click the Arguments tab and enter the program arguments as follows:

    "<VADeployer Eclipse project path>\env.dat" SUNX509

  5. Click Apply.
  6. Click Run.

You can create an executable JAR file by exporting the project as a runnable JAR file. If you want to run this application using IBM JVM, then you need to specify the IBMX509 certificate in the arguments as follows:

java -jar <my jar dir>\VADeployer-win32.jar <my env.dat dir>\env.dat IBMX509

Basic deployment scenario

You can perform the following steps to deploy a virtual appliance in VADeployer:

  1. Under Locate, click Go to retrieve all virtual appliances or enter a name to filter your results.
  2. Select a virtual appliance. Target hosts are displayed.
  3. Select a target host. This action retrieves the deployment customization properties available when deploying the selected virtual appliance into the selected target host.
  4. Click the Configure tab. Here, you must assign all the virtual disks to the required storage pool, map virtual networks to virtual networks on host, and enter all required product activation parameters.
  5. If necessary, click the Advanced tab to modify memory and processor allocation settings.
  6. Click Deploy and confirm to continue deploying.
  7. Track the workload's status on the Monitor tab.


VADeployer explores only a small piece of the IBM Systems Director REST APIs capabilities to manage and automate virtual appliance deployments. The integration can go beyond to fully customize the logical resources required by a virtual appliance. For instance, you can customize a virtual server based on your business needs for storage, memory, processing, and networking and use it as a target to deploy your virtual appliance, while at the same time, specify the deployment parameters for your software products.

You can always use the IBM Systems Director Admin console, select VMControl under System Configuration, and start deploying the virtual appliances. However, the integration between IBM Systems Director and VMControl and your solution is what matters. More importantly, every new REST API release is including new features that you can take advantage of, and IBM Systems Director technology aligns with the latest and powerful IBM PureFlex System management technology, which leverages on FSM for physical and logical resource management. Under this perspective, you might find VADeployer code useful and take it as a start point or extend current features.

Finally, independent software vendors (ISVs) can always get closer to IBM to know the terms and conditions that must be met to integrate their products with the IBM Systems Director REST APIs.




  • IBM Systems Director forum: Post your questions and comments about IBM System Director, 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=VADeployer - a Java SWT REST client application