IBM Systems Director VMControl is a multi-platform, multi-hypervisor virtualization management solution and one entree into the world of cloud computing. It is an advanced manager of IBM Systems Director, a free-to-own set of platform management tools.

Building off of the excellent systems management capabilities of IBM Systems Director, VMControl provides a number of capabilities to help manage the complexity of cloud computing administration. These capabilities include:

• Virtual machine life cycle management.
• Software image life cycle and image library management.
• System pool capability for dynamic collections of server resources.

The information in this article and the command line interface described in it are specific to the IBM Systems Director VMControl version 2.3.

Let's take a closer look at VMControl before I show you how to automate a management function with a script.

VMControl editions

VMControl is an IBM Systems Director advanced manager. It provides three levels of virtualization capabilities, expressed as editions:

• IBM Systems Director VMControl Express Edition supports system-level virtualization, including virtual server life cycle functions and virtual farm support. The Express Edition, like Systems Director, is free to download and use.
  
• Standard Edition includes everything in the Express Edition and adds image life cycle and image library management capabilities. VMControl Standard Edition is free to try for 60 days.
  
• Enterprise Edition includes everything in both the VMControl Express and Standard Editions and adds system pool life cycle support. System pools are dynamic collections of computing resources used to support multiple virtual images running concurrently. VMControl Enterprise Edition is free to try for 60 days.

Back to top

VMControl command-line interface

The VMControl command-line interface (CLI) provides a method for you to interact with VMControl without the overhead of a graphical user interface. VMControl CLI commands can be run interactively from a command prompt to perform simple tasks, but their real power is discovered when they are combined into a script.

Any of the capabilities specified in the section on editions can be achieved through the VMControl CLI; performing simple tasks is pretty straightforward but you will still find the VMControl CLI to be a rich and robust interface that can be used to perform the most advanced tasks.

I will guide you through both the simple VMControl CLI commands and some of the more advanced techniques and describe the different commands available in each of the VMControl editions. I'll show you the common practices and some examples of how to combine these commands in a useful way.

By the end of the article, you should feel more comfortable using the VMControl CLI and should be able to start writing scripts of your own.

The systems management command-line interface (smcli)

The VMControl CLI commands are run within the IBM Systems Director systems management command-line interface called smcli. The syntax for a VMControl CLI is similar to the syntax of most CLIs that you would see if you are trying to run a Windows® batch script or a Linux® shell script and has the following format:

smcli <commandName> [options]

Retrieving a list of all available CLI commands can be done by running smcli lsbundle. The output will contain a list of commands separated into groups called namespaces. The format of the output of the lsbundle command is:

<namespace>/<commandName>

Each command has a set of options that can be specified in order to manipulate the action of the command. To see a description of the command containing all of the possible options, use the -h or --help options: smcli <commandName> --help.

For more information on the smcli interface, see Resources.

Details of the VMControl CLI

The VMControl CLI is grouped into two namespaces. VMControl Express Edition CLI commands are grouped in the vsm namespace while the VMControl Standard Edition and Enterprise Edition CLI commands are grouped in the imagemgrcli namespace.

Information on CLI commands can be retrieved by running the commands using using the -h or the --help options. For example, smcli lsva -h returns the syntax for the lsva command while smcli lsva --help returns addition help information, including examples.

The next section lists all of the commands available in the VMControl CLI, including a short description for each. The commands described here are correct at time of publication, but visit the URLs for any late changes.

Express Edition commands
The Express Edition commands are as follows:

Standard Edition commands
The Standard and Enterprise commands are as follows (commands designated with a * fall under the Standard Edition license when the target is a host and under the Enterprise Edition license when the target is a system pool):

Enterprise Edition commands

Customization parameters

One of the more complicated parts of effectively using the VMControl CLI is learning how to properly use customization parameters. Customization parameters (also called capabilities) come in all shapes and sizes, from the simple Boolean to the more complicated table. Most of these will give you minimum and maximum boundaries for the values that you need to supply.

In VMControl, customization parameters are displayed using the lsvrtcap or lscustomization commands. These commands require you to specify the type of action that you are performing and the targets on which you are performing that action. For example, to collect customization parameters for creating a virtual server on a specific host, the following command needs to be specified:

smcli lsvrtcap -c mkvs -n 0x1234

0x1234 is the ID of the host that you want to use for creating a new virtual server.

These customization parameters need to be updated by you or your script and passed back to supported commands that use them to add system-specific customization to supported VMcontrol CLIs.

Customization parameters are returned to supported commands using the -A parameter. They should be separated by commas with the entirety surrounded by quotation marks. Here is an example of some common customization parameter types.

This first customization parameter is a text parameter. In this example, your system name has a maximum number of 31 characters.

name       Value:  null
           Min:    1
           Max:    31
           Description: The name of the virtual server to be created.

The second customization parameter is a long parameter. It has a minimum value of 1 with a maximum value of four and increments linearly in increments of 1.

cpushared  Value:  1
           Min:    1
           Max:    4
           Increment:      1
           IncrementType:  LINEAR
           Description:    The desired number of dedicated or virtual 
                           processors to be assigned to the virtual 
                           server.

The third customization parameter is a selection list parameter. Valid options for the gos parameter are IBM Power - AIXLINUX and IBM Power - i5/OS.

gos        Value:  IBM Power - AIXLINUX
           Options:        IBM Power - AIXLINUX,
                           IBM Power - i5/OS
           Description:    The type of operating system (aixlinux or 
                           IBM i) that can be installed on the virtual 
                           server.

The final customization parameter is a table parameter. In this case there is only one row, but because the minimum value is one, we must select it.

diskphysicalvolumes   Min: 1
           Max: 1
           Changeable Columns:
              Column Name:     CLI Attribute
              Physical Volumes physvolname
              Storage Server   physvolstgsvr

     Options:
           Key,         Physical Volumes*,   Size (MB), Location,   Storage Server*
           [hdisk1:sys1] hdisk1              4258       hdb-1254    icb-cpt1v1

Assuming that these four customization parameters are the only four required customization parameters for creating a virtual server, the mkvs command would look like this:

smcli mkvs -n 0x1234 -A "name=vs_1, cpushared=2, gos=IBM Power - AIXLINUX, diskphysicalvolumes=+hdisk:sys1"

Note the + before hdisk:sys1 in the diskphysicalvolumes parameter. This is a shortcut for selecting an entire row as is.

More information about table parameters can be found using the --help option with the lsvrtcap or lscustomization commands; or you can check out the lsvrtcap command infocenter in Resources.

Back to top

The life cycle of a virtual appliance

Now that you have the commands and a basic understanding of customization parameters, it's time to learn how to take advantage of the IBM Systems Director VMControl CLI. In the remaining sections, I will detail the most powerful component of VMControl — virtual appliance life cycle management. A virtual appliance:

• is a ready-to-deploy operating system and software package that is stored by IBM Systems Director VMControl.
• contains an image of a full operating system.
• can contain software applications and middleware.
• contains metadata describing the virtual server that the image requires.

Let's look even deeper into the life cycle management.

Back to top

The image repository

Virtual appliances are stored in an image repository which can be discovered through the IBM Systems Director console (see Resources for more on creating and discovering image repositories).

Once an image repository has been discovered, it can be viewed in the CLI using the lsrepos command. Running lsrepos with no parameters results in a list of all virtual appliances. Adding the -o option will include each repository's OID (object identifier):

# smcli lsrepos -o
myImageRepository, 3129

To retrieve more information about this repository, use the -l option:

# smcli lsrepos -l
myImageRepository
        ClassName:com.ibm.usmi.datamodel.software.ImageRepository
        UniqueId:76f1e7be-d6bf-4aba-b7d4-40b04c3d2577
        ImageRepositoryType:1
        ChangedDate:2010-08-04T00:17:27-05:00
        SourceTokens:{ }
        DisplayName: myImageRepository
        CreatedDate:2010-07-08T15:31:02-05:00
        ImagingTool:DISCOVERY_NIM_REPOSITORY
        OID:3129
        Guid:2F0ECE8196CA36D9A0314BFE6C7CD082
        ObjectType:ImageRepository

Note that the -o and -l command line options are common to all of the "list" style of CLI commands.

Back to top

Virtual appliance creation

Virtual appliances are stored by VMControl in a repository which is also managed by VMControl. They are created in two ways, either by import or capture.

Import

Import creates a virtual appliance from an existing virtual appliance package. VMControl can import virtual appliance packages that use the Distributed Management Task Force (DMTF) Open Virtualization Format (OVF), a platform-independent, open-packaging-and-distribution format for virtual appliances (Resources).

Once you have a valid image ready to import, use the importva CLI command to import it. The following command imports /tmp/myImage.ova into the repository with an OID of 3129 and sets its name and description:

smcli importva -v -F "/tmp/myImage.ova" -r 3129 -n "myImportImage" -D "My First Imported Image"

Capture

Capture creates a virtual appliance from one of the following sources:

• virtual server
• workload
• mksysb image
• mksysb resource
• lpp_source resource
• lpp_source directory

The lscapsrv command can be used to list capturable virtual servers and workloads. Use the -T option to filter out virtual servers or workloads:

# smcli lscapsrv -o
myCapturableVirtualServer, 2950

To capture the virtual server in the previous code block:

smcli captureva -v -s 2950 -r 3129 -n "myCaptureImage" -D "My First Captured Image"

For more information on capturing mksysb or lpp_source resources, see Resources.

If you are working in an environment with multiple types of image repositories, it may be necessary to use the lsrepos command prior to running importva or captureva to validate that your repository is valid for the image that you intend to create. To import:

smcli lscustomization -a import -F /tmp/myImage.ova -r 3129

To capture, run the following command:

smcli lscustomization -a capture -s 2950 -r 3129

In addition to validating the repository, this command returns customization options that can be passed in on import/capture using the -A parameter.

Back to top

Deploying a virtual appliance

Now that you have created a virtual appliance, it is time to deploy it. There are two methods of deploying a virtual appliance in VMControl:

• Deploy to an existing virtual server or
• Deploy to a new virtual server.

In this example, we will be using deploy to a new virtual server.

When choosing to deploy to a new server, a host or system pool is selected as the target. The deployment process involves the creation of a new virtual server followed by installing your virtual appliance image on the newly created virtual server. There are special rules for deploying to a system pool that I will discuss later.

When choosing to deploy to an existing virtual server, an empty virtual server is selected as the target. This virtual server has been allocated prior to running the deploy. In this case, the deployment process only involves installing the virtual appliance image on the existing virtual server.

The first thing that you need to do when deploying a virtual appliance is to choose the virtual appliance that you want to deploy. This can be done with the lsva command:

# smcli lsva -o
AIX 6 for Power version 6.1 TL 4, 16239
AIX 6 for Power version 6.1 TL 5, 16344

The next step is to find a target for this virtual appliance deployment using the lsdeploytargets command:

# smcli lsdeploytargets -a deploy_new -V 16344 -o
PowerHost1, 6760
PowerHost2, 5019
TestSystemPool1, 8042

Now it is time to review the customization options for deploying virtual appliance 16344 to host 6760 using the lscustomization command:

# smcli lscustomization -a deploy_new -V 16344 -s 6760

This command returns more customization parameters than should be copied here; review the customization parameters section. For more information on required parameters, see Resources.

Finally, once you have reviewed the customization parameters, it is time to deploy the virtual appliance.

# deployva -a deploy_new -V 16344 -s 6760 -A "cpushminu=0.1,cpushmaxu=1,cpushu=1,
cpushmode=UNCAP,cpushmin=1,cpushmax=1,cpushared=1,memmin=2048,memmax=2048,
memsize=2048,virtualnetworks[Network1]=hostVnet:ETHERNET0/2,
product.AIX1.com.ibm.ovf.vim.2.system.hostname=myFirstDeployedHost,
product.AIX1.com.ibm.ovf.vim.2.system.domainname=ibm.com,product.AIX1.com.ibm.ovf.vim.2.
 networkport.6.gateway=10.10.10.17,product.AIX1.com.ibm.ovf.vim.2.networkport.6.
 netmask=255.255.255.0,product.AIX1.com.ibm.ovf.vim.2.networkport.6.
 domainname=ibm.com,product.AIX1.com.ibm.ovf.vim.2.networkport.6.ip=
 10.10.10.1,product.AIX1.com.ibm.ovf.vim.2.networkport.6.dns1.ip=10.10.1.18"

Breaking up the -A parameter will give a better view of the supplied parameters:

• CPU parameters:

cpushminu=0.1, cpushmaxu=1, cpushu=1, cpushmode=UNCAP

cpushmin=1, cpushmax=1, cpushared=1

• Memory parameters:

memmin=2048, memmax=2048, memsize=2048

• Virtual server parameters:

product.AIX1.com.ibm.ovf.vim.2.system.hostname=myFirstDeployedVS

product.AIX1.com.ibm.ovf.vim.2.system.domainname=ibm.com

• Network parameters:

virtualnetworks[Network1]=hostVnet:ETHERNET0/2

product.AIX1.com.ibm.ovf.vim.2.networkport.6.gateway=10.10.10.17

product.AIX1.com.ibm.ovf.vim.2.networkport.6.netmask=255.255.255.0

product.AIX1.com.ibm.ovf.vim.2.networkport.6.domainname=ibm.com

product.AIX1.com.ibm.ovf.vim.2.networkport.6.ip=10.10.10.1

product.AIX1.com.ibm.ovf.vim.2.networkport.6.dns1.ip=10.10.1.18

The result of this command is the creation of a new workload and a new virtual server:

# smcli lsworkloads
AIX 6 for Power version 6.1 TL 5

# smcli lsvrtsys -n myFirstDeployedVS
myFirstDeployedVS

When deploying a virtual appliance to a system pool, the deploymentplanid customization parameter is required and must match what was returned from executing the lscustomization command.

Back to top

Deleting a virtual appliance

When your image library is getting too large, it's time to delete a virtual appliance. This can be done with the rmva command:

# smcli rmva -V 16344

Back to top

In conclusion

I hope this short introduction into the power of the VMControl command line interface has provided you with enough basics to be comfortable running VMControl CLI commands and to use that knowledge to combine commands into scripts to increase productivity and take advantage of the power of IBM Systems Director VMControl.

Resources

Learn

• This Infocenter Mini-library is all the source material for more detailed information that is listed in this article:
  • Find the VMControl free trial license and information.
  • Get more information about IBM Systems Director.
  • Get more information on the smcli interface.
  • More information about table parameters can be found in the lsvrtcap command infocenter.
  • Learn more about creating and discovering image repositories.
  • Read more about the requirements for import.
  • Get more information on capturing mksysb or lpp_source resources.
  • Learn more about deployva and required parameters.
  
  
• How to develop SMCLI commands for IBM Systems Director (developerWorks, Dec 2009) takes your knowledge a step further by showing you how to develop smcli commands.
  
  
• Half the benefit of virtual appliances comes from being able to automate some or all of their deployment: Take a look at how in Automating deployment and activation of virtual appliances (developerWorks, Apr 2009).
  
  
• The classic Simplify AIX image management in a PowerVM environment using IBM Systems Director VMControl V2.1 (developerWorks, Sep 2009) provides a detailed overview of life cycle management, provisioning, and configuration of virtual appliances.
  
  
• The IBM Smart Business Development and Test on the IBM Cloud site is your place to see how to start developing your applications for the cloud.
  
  
• See the growing list of of software images available on the IBM Cloud.
  
  
• In the developerWorks cloud developer resources, discover and share knowledge and experience of application and services developers building their projects for cloud deployment.
  
  
• Read all the great cloud blogs on My developerWorks.
  
  

Discuss

• Join a cloud computing group on My developerWorks.
  
  
• Join the My developerWorks community, a professional network and unified set of community tools for connecting, sharing, and collaborating.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• VMControl editions
• VMControl command-line interface
• The life cycle of a virtual appliance
• The image repository
• Virtual appliance creation
• Deploying a virtual appliance
• Deleting a virtual appliance
• In conclusion
• Resources
• About the author
• Comments

Next steps from IBM

Learn more, join the cloud community

---

• Community: Cloud computing conversations led by IBM community members
• Buy: Try IBM software on IBM SmartCloud Enterprise

Dig deeper into Cloud computing on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers