Creating virtual servers through VMControl REST APIs

Customize virtual disks and networks

Creating logical partitions on IBM Hardware Management Console (HMC) can often be a time consuming task and of course requires a certain level of technical skills on PowerVM technology. By using remote command execution on HMC and VMControl Representation State Transfer (REST) web services calls, you will be able to programmatically create logical partitions assigning virtual resources and enabling a simplified virtualization management.


Jose Moises, 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 five 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.

21 December 2011

Also available in Chinese Russian Japanese


IBM Systems Director provides a set of consumable interfaces which are accessible from any language that has a HTTP client library such as Java, Perl, CSharp and so on. These interfaces are web services based on Representational State Transfer (REST) client/server architecture and each web service is viewed as a resource within IBM Systems Director. Each resource will have a specific URI associated with. The resource URI, the HTTP method, possible query parameters and the HTTP request body sent to the IBM Systems Director server determine the service to be accessed (also known as REST API) and what action that service needs to take.

VMControl is an advanced manager which supports REST web services within IBM Systems Director. Latest version of VMControl is 2.3.1 at the moment of writing this article and unfortunately has some limitations for creation of disk storage during creation of virtual servers. Creating virtual disks or logical volumes programmatically using VMControl REST web services is not supported in version 2.3.1, but there is a solution for this inconvenient: Create the virtual disks by using the remote command execution on your Hardware Management Console (HMC) and add virtual disks and networks through VMControl REST web services.

Enabling remote command execution on HMC

Command Line Interface (CLI) offers a easy method to execute simple or complex tasks, you can use HMC commands on scripts to automate common system management tasks. In order to enable and configure remote command execution on HCM please use this HMC command line wiki.

Once the remote command line is configured you will be able to run HMC commands from your ssh client. Listing 1 shows how to run Virtual I/O Server (VIOS) commands. VIOS commands will be used later to create storage pools and logical volumes.

Listing 1. Listing 1. HCM remote command line usage
$ssh hscroot@<hmc_host> viosvrcmd -m <POWER_System> 
    -p <vios_name> -c '"<vios_command>"'

<hmc_host> is the HMC hostname or IP address
<Power_System> is the POWER System name, i.e. Server-9117-MMA-SN10ED68E
<vios_name> is the VIOS name running in your POWER system
<vios_command> is the command you want to run in the VIOS

It is important to write the ' character around the VIOS command if the command contains arguments, otherwise you will receive an error like this:
"An invalid parameter was entered. The parameters -virtual are not valid. Please check your entry and retry the command."

Create the storage pool

Logical volume storage pools are collections of one or more physical volumes. To create storage pools, be sure you meet the following requirements:

  • The Hardware Management Console must be at version 7 release 3.4.2 or later.
  • The Virtual I/O Server must be at version or later.
  • Ensure that there is a resource monitoring and control connection between the Hardware Management Console and the Virtual I/O Server.

To create a volume-group-based storage pool, first you need to know which physical volumes are unassigned in your system, to retrieve the list of unassigned physical volumes you can use the VMControl REST API shown in Listing 2.

Listing 2. Listing 2. VMControl REST API to get customization values

This API will show you all customization properties that are available when creating a new virtual server on a specific host. To find your host Object ID (OID) you can use the API shown in Listing 3.

Listing 3. Listing 3. VMControl REST API to get available hosts

When you submit a GET action on API shown in Listing 2, a list of available physical volumes is displayed inside diskphysicalvolumes property as shown in Figure 1.

Figure 1. Figure 1. Physical volumes available in the host system
Physical volumes available in the host system

The values you need for each physical volume are its id and size, the size is inside the property object. Once you decide which physical volume will be used, then you can execute a command on your HMC remotely from your REST client application, to create your storage pool. Listing 4 shows the VIOS command you can execute remotely.

Listing 4. Listing 4. Create a storage pool remotely
$ssh hscroot@<hmc_host> viosvrcmd -m <host_system> 
    -p <vios_name> -c '"mksp -f <storage_pool_name> 

Please be careful to include only the name and not the text ":vios" from your physical volume id.

Create the logical volume

The logical volume will appear as a virtual disk in VMControl, once the storage pool is available you can create any number of disks you need. You can use the command in Listing 5 to create your virtual disk remotely.

Listing 5. Listing 5. Create a virtual disk remotely
$ssh hscroot@<hmc_host> viosvrcmd -m <host_system> 
    -p <vios_name> -c '"mklv -lv <disk_name> 
    <storage_pool_name> <size>"'

Visible virtual resources for VMControl

In order to add the storage pool and virtual disks as a resources into IBM Systems Director, you can submit an inventory collection job with your POWER system host as the target. The API shown in Listing 9 is used to submit a POST request to create an inventory job:

Listing 6. Listing 6. Inventory collection job API


{ObjectType} = Server
{OID} = Server's object ID
{ProfileID} = Inventory profile ID, you can use the default All inventory, ID: default.All

The request payload to be used with API in Listing 6 is shown in Listing 7:

Listing 7. Listing 7. Inventory collection job payload
  "DisplayName": "My inventory collection job",

You can verify the inventory collection job progress and status by using the Java Messaging Service (JMS) provider available in IBM Systems Director, which is Apache ActiveMQ. IBM Systems Director uses this provider to communicate events and other important messages with interested client applications. JMS overview and examples are available in the IBM Systems Management SDK. Basically, you need to subscribe your client to the topic and validate the job progress and status.

A new JMS topic subscription can be created to listen events and know if the new resources such as storage pools and virtual disks are available within IBM Systems Director. The topic you need to use is Director.manageableelementservice.manageableelement and the message properties that are received when a new manageable element is added to IBM Systems Director are shown in Listing 8.

Listing 8. Listing 8. Manageable element event properties sample
properties = {EventType=CREATED_EVENT, OID=91256, 
ObjectType=StorageVolume, Version=1.0.0}

The value of ObjectType property represents the type of the new added resource. In the case of storage pools, ObjectType is set to StoragePool. Virtual disks created as logical volumes in the VIOS partition are shown with ObjectType set to StorageVolume.

Once the inventory collection job is complete with no errors and the manageable elements added, you can verify that new resources are visible for VMControl within IBM Systems Director, by using the same VMControl REST API in Listing 2. Figure 2 shows the set of virtual disk which are displayed inside the disks property.

Figure 2. Figure 2. Virtual disks available in the host system
Virtual disks available in the host system

Within each virtual disk property object you can find additional information such as: Size (MB), storage pool and storage server. The storage server in this case is a VIOS. The virtual disk id value is used to assign the disks to a new virtual server.

Create the new virtual server

Listing 9. Listing 9. VMControl REST API to create a virtual server

The POST request requires a JSON object payload where you specify the virtual server settings as explained in the IBM Systems Director VMControl SDK.

Listing 10 shows an example of a JSON payload which specifies the following settings:

  • Virtual server type, value set to IBM Power - AIXLINUX
  • Virtual server name, value set to vserver
  • Cpu mode, value set to SHARED
  • Number of CPUs, value set to 2
  • Memory size, value set to 2048
  • Memory unit size, value MB
  • Disks, value set to vmdisk1:rootvg_vm:vios;vmdisk2:rootvg_vm:vios. Which means both vmdisk1 and vmdisk2 will be assigned to the virtual server.
  • Networks, value set to 1. Which means the VLAN with identifier 1 will be assigned to a virtual Ethernet adapter.
  • Networks, value set to 80. Which means the VLAN with identifier 80 will be assigned to a virtual Ethernet adapter.
Listing 10. Listing 10. JSON sample request to create a virtual server
            "name":"gos", "value":"IBM Power - AIXLINUX"
            "name":"name", "value":"vserver"
            "name":"cpumode", "value":"SHARED"           
             "name":"cpushared", "value":2
            "name":"memsize", "value":2048
            "name":"memunitsize", "value":"MB"
            "name":"disks", "value":"vmdisk1:rootvg_vm:vios;vmdisk2:rootvg_vm:vios"
            "name":"networks", "value":"1"
            "name":"networks", "value":"80"


Figure 3 shows a submission request to API in Listing 9, this was executed on the Poster FireFox plug-in. Poster helps to interact directly with the REST APIs and inspect the response message body and status. You can submit any request action supported by the REST APIs without write a line of code, however you can submit the same type of request by using a programming language with a HTTP client library such as Java.

Figure 3. Figure 3. Create virtual server with VMControl REST API
Create virtual server with VMControl REST API

Notice that a job activation is created when you submit the request, which tells you about the status and progress of the task Create Virtual Server. If everything goes well you will be able to see the new virtual server in VMControl. To verify the task status, you can submit a GET request to the API shown in Listing 11.

Listing 11. Listing 11. Job activation status REST API

Replacing the values given by the response from a create virtual server request in this example, we have a jobID = 36 and activationID = 12. If the job activation status is set to Complete and Progress set to 100 then you will be able to see the message shown in Figure 4.

Figure 4. Figure 4. Job activation details
Job activation details

Figure 4 shows the message when progress level has reach the 50 % which is "DNZVMP509I Create Virtual Server request completed successfully for host, Server-9117-MMA-SN10ED68E. Systems Director might not display the new virtual server immediately. It might take a few minutes for the new virtual server to be displayed.", when the job activation is completed you will see a message like this: “Server-{host_name} client job status changed to "Complete".

Again, it is recommended to use JMS to consume messages generated by job updates or when a new manageable element is created, deleted, or changed. In this case the new virtual server being created is a manageable element.

Creating the virtual server programmatically

You can get the source code of several good examples on how to call IBM Systems Director REST APIs from the IBM Systems Management SDK site. Listing 12 shows a Java code sample on how to submit a POST request to create a virtual server.

Listing 12. Listing 12. Java sample code to call VMControl REST API
1)public String ceateVirtualServer(){
2)		String METHODNAME = "ceateVirtualServer";
3)		String requestPayload = "your JSON payload from Listing 10 goes here"; 

4)      String uri = sdc.getConnectionContextURI() + 
5)		RESTUtilities.log(Level.INFO, logger, CLASSNAME, METHODNAME, 
		"requestPayload: " + requestPayload);
6)	RESTUtilities.log(Level.INFO, logger, CLASSNAME, METHODNAME, 
        "(POST) URI to invoke: " + uri);        
7)        try{
8)        	HttpsURLConnection dataConnection = sdc.processRequest(uri, 
        	"POST", requestPayload);
9)            int rc = dataConnection.getResponseCode();
10)            if (rc != 201) {
11)             RESTUtilities.log(Level.SEVERE, logger, CLASSNAME, METHODNAME, 
                "FAIL: Unexpected return code: Expected 201 but got " + rc);
12)              return "-1";
13)         }
14)         String response = RESTUtilities.getResponseString(dataConnection);
15)     }catch(Exception e){
16)	    	e.printStackTrace();
17)     }		
18)	return "0";
19)	}

Line 14 of Listing 12 will give you the URL that you need to verify the status and progress of the created job activation just the same way we got this response in Figure 3.

Verify virtual server configuration

We can verify if the virtual server settings were saved correctly in IBM Systems Director by following the next steps:

  1. Go to System Configuration > VMControl > Virtual Servers and Hosts
  2. Select your new virtual server and from the context menu (right click) select System Configuration > Edit Virtual Server then select Virtual Disk, verify the assigned virtual disks are selected as shown in Figure 5.
  3. Select Network, verify the assigned networks are displayed, as shown in Figure 6.

Figure 5 shows the virtual disks assigned to the virtual server.

Figure 5. Figure 5. Virtual disks assigned to virtual server
Virtual disks assigned to virtual server

As you can see in Figure 5, the virtual disks created remotely on the VIOS partition through HMC were assigned correctly to the virtual server, all other unassigned virtual disks will be displayed here.

When the virtual server is created, VMControl automatically assign a virtual SCSI adapter in your VIOS partition, rebooting is not required.

Figure 6 shows the networks assigned to the virtual server. These networks were created previously in the VIOS partition which is managing the hardware resources for virtual servers.

Figure 6. Figure 6. Networks assigned to virtual server
Networks assigned to virtual server

Figure 6 shows two networks with a unique id, this id value represent the internal Virtual LAN (VLAN) identifier that is used to communicate virtual servers.

Calling HMC commands from your REST client

This document presents a quick guide to create a virtual server by using the VMControl REST APIs, you can call your scripts to run remotely HMC commands (see Create the storage pool and Create the logical volume) from your REST client application. For example, if you are using Java code and your client is running on Linux/Unix, then you can call the HMC scripts as shown in Listing 13.

Listing 13. Listing 13. Java sample code to call system commands
1) String s = null;
2) Process p = 
   Runtime.getRuntime().exec("ssh viosvrcmd" +
     		" -m Server-9117-MMA-SN10ED68E -p myvios" +
     		" -c '\"mklv -lv vmdisk2 rootvg_vm 10G\"'");
3)        BufferedReader stdInput = new BufferedReader(new

4)        BufferedReader stdError = new BufferedReader(new 
        // read the output from the command
5)        System.out.println("Here is the standard output of the command:\n");
6)        while((s = stdInput.readLine()) != null) {
7)             System.out.println(s);
8)        }            
        // read any errors from the attempted command
9)        System.out.println("Here is the standard error of the command (if any):\n");
10)        while ((s = stdError.readLine()) != null) {
11)            System.out.println(s);
12)        }            
13)           System.exit(0);
14)        }
15)  catch (IOException e) {
16)       System.out.println("exception happened - here's what I know: ");
17)       e.printStackTrace();
18)       System.exit(-1);
19) }


b) You can use the guide in this documents to create storage pools and virtual disks while creating your virtual server with VMControl 2.3.1. Something important is that you can only assign the complete disk size to a virtual server and you can follow the same process to assign physical disks, in this case you only need to get the physical disk id value from the response of the REST API in Listing 2.

New IBM Systems Director 6.3 and VMControl 2.4 were released on December 2011 and allow you to add existing disk and volumes using REST APIs, however creating a new disk and attaching it to an existing virtual server is not supported. You can create the virtual disk outside VMControl by following the steps in this guide and then be able edit the existing virtual server to add new disks using the API: hosts/{hostOID}/virtualServers/{vsOID}




  • 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 SOA and web services on developerWorks

Zone=SOA and web services
ArticleTitle=Creating virtual servers through VMControl REST APIs