Reduce cloud management complexity with command-line scripting

Using the easy-to-access IBM Systems Director's VMControl command-line interface


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.

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:


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 Related topics.

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:

chvrtauthAuthorize one or more platform managers or host systems by setting or revoking authorization credentials.
chvrthostChange the attributes of one or more virtual-server host.
chfarmAdd a host to or remove a host from a virtual farm or change a virtual farm's attributes.
chvsChange the attributes of one or more virtual servers.
lsvrtcapList virtualization capabilities of a virtual server or host system.
lsvrtsysList the name and ID for virtual systems.
mkfarmCreate a virtual farm.
mkrelocatetaskCreate a task to relocate (or migrate) virtual servers.
mkvsCreate a virtual server.
rmvsDelete a virtual server.

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):

capturevaCapture a virtual appliance.
chworkloadChange the attributes of a workload.
deployva*Deploy a virtual appliance.
importvaImport a virtual appliance into VMControl Standard Edition.
lscapsrvList servers that you can capture as virtual appliances.
lscustomization*List attributes that you can customize for a virtual appliance when you run the captureva, deployva, or importva commands.
lsdeploytargetsList the target servers or hosts on which you can deploy a virtual appliance workload.
lsreposList repositories.
lsvaList virtual appliances.
lsvaforreplaceList virtual appliances that can replace the version on the specified virtual server.
lsvsforreplaceList all virtual servers that are candidates for being updated to the specified virtual appliance.
lsworkloadsDisplay workloads.
mkworkloadCreate a workload.
replaceversionDeploy a different version of a virtual appliance on one or more virtual servers.
rmvaPermanently delete a virtual appliance.
rmworkloadDelete a workload.
startworkloadStart a workload.
stopworkloadStop a workload.

Enterprise Edition commands

addhosttopoolAdd a host to a system pool.
chsyspoolUpdate a system pool.
entermaintenancemodeEnter the maintenance mode for a host.
exitmaintenancemodeExit the maintenance mode for a host.
lscandidatehostList hosts that are candidates for addition to a server system pool.
lscandidatestorageList candidate storage for a system pool.
lssyspoolList server system pools.
mksyspoolCreate a new server system pool.
rmhostfrompoolRemove a host from a server system pool.
rmsyspoolDelete a system pool.
vmcrelocateGenerate, display, and optionally execute a Placement Services plan.

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 

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 

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

           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 Related topics.

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.

The image repository

Virtual appliances are stored in an image repository which can be discovered through the IBM Systems Director console (see Related topics 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
        SourceTokens:{ }
        DisplayName: myImageRepository

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

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 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 (Related topics).

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 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 Related topics.

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.

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 Related topics.

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,

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:
  • Network parameters:

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

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.

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

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.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=Cloud computing
ArticleTitle=Reduce cloud management complexity with command-line scripting