Posts Tagged ‘vSphere API’

Tech Talk: Accessing the Vsphere API from C/C++

May 26th, 2011 No comments

This talk is by Steven Wong who is an architect working at EMC on various backup and virtualization projects. If you are using C or C++ with gSOAP to manage vSphere, this talk is for you.

Check it out below:

vCenter Server Linked Mode: An API Perspective

May 4th, 2011 1 comment

A new feature called vCenter Linked Mode has been introduced in vSphere 4. It allows several vCenter servers to form a linked mode group. When you connect to any of the vCenter server via vSphere Client, you see all of them behind a single pane of glass.

I got questions from time to time, “what does it mean for vSphere API?” More specifically, if you connect to one vCenter in a linked mode group, will you “see” all of them? If not, how can vSphere Client achieve that?

Vertical vs Horizontal APIs

April 25th, 2011 No comments

Many APIs have emerged since the inception of computer software. Its root can be traced back to the layered software architecture in which high layer calls to low layer. The low layer is not necessarily called APIs, but the other way is mostly true.

Initial APIs were inside a single or multiple vertical call stacks that share same memory space. As a result, you have good performance and ease of use. After that, inter-process communication (IPC) emerged and allowed API services to run in a different process for better

Introducing vSphere Guest API

April 11th, 2011 1 comment

If you want to read information about a virtual machine from the guest OS running on it, the vSphere Guest API is for you. It’s a C library coming with VMware Tools. Unlike the vSphere API which can be used anywhere, the vSphere Guest API is only available in the guest OS.

High Level Characteristics

  • It’s read only. You can use it to retrieve state and performance of a virtual machine running on ESX, but you can NOT
Categories: vSphere API Tags: , , ,

Features Not Exposed in vSphere Client but vSphere APIs

April 6th, 2011 10 comments

If you think vSphere Client exposes everything, you are wrong. The vSphere APIs actually expose more features than the vSphere Client, which is a great product. This is one reason why system administrators should learn vSphere APIs.

While writing my book, for example, I noticed that vSphere APIs actually allow you to change guest OS screen size with a simple call setScreenResolution(int width, int height).

Given the time pressure, I didn’t summarize these API only features at that time. To be honest,

Finding out Guest OS Running on a Virtual Machine

March 18th, 2011 5 comments



VMware ESX and ESXi (a.k.a. vSphere Hypervisor) support the most guest operating systems among all the hypervisors. From the vSphere API, you can determine what operating system is installed on a virtual machine.

The related managed object is the VirtualMachine and there are multiple ways to

Released: VMware vSphere API and SDK FAQ

March 6th, 2011 25 comments

After working on this for weeks, I am pleased to announce the first release of VMware vSphere API and SDK Frequently Asked Questions. It includes 70+ questions and trustable answers in 6 different categories: General, Getting Started, Language Bindings, VI Java API, API Usage, Troubleshooting.

From now on, before posting any question to any forum please read this FAQ page. For the best readability, I decided not to allow comments on that page. But your feedbacks and suggestions are always important. Please feel free to use this post for comments and discussions. Based on your inputs, I will continue to enhance the FAQs.

Categories: vSphere API Tags: , , ,

Introducing VMware vShield REST API

February 22nd, 2011 6 comments

One of my colleagues asked me about vShield API and pointed me to the vShield API Programming Guide. I have of course heard about the vShield many times, but haven’t tried it out, let alone its API. But that doesn’t mean I cannot read it on demand. In fact, such questions motivate me to learn more beyond vSphere API. So keep your questions coming if you have one.

Here is what I found out after reading the programming guide. I have to admit I haven’t written any code connecting to a vShield test-bed, so I just share some basics of the API. Overall I found it’s similar to the vCloud API that I had worked with before in format and protocol.

Somehow the API does not, but I think should,

Getting ESX and ESXi Memory Info

February 2nd, 2011 9 comments

With a vSphere Client, you can easily check the memory information of a host, either ESX or ESXi. To get that, you click on a host from the inventory tree, and then configuration tab. From the left side Hardware section of the configuration page, you click Memory and see a pane displaying the memory info as follows:

Note that if you have chosen a ESXi host, you won’t see the Service Console part because there is no console OS any more in ESXi. BTW, VMware wants you to migrate from ESX to ESXi and here is a link with helps.

This seemingly easy information is actually not easy to get. At first glance, it should be in the config property of HostSystem (managed object representing an ESX or ESXi). The config property has a sub property called systemResources, typed as HostSystemResourceInfo. But you will get null for the systemResources property most, if not all, of the time, as reported in VI Java API forum.

Interestingly enough, HostSystem has a systemResources property in peer to the config property as well. Luckily, it’s not null so you can dig down for something. Still, with 3 sub properties of complex types included, how to get the memory from the data object?

Here are the steps to collect and calculate the numbers:

Categories: vSphere API Tags: , , ,

How to Change VMX Programmatically?

January 31st, 2011 7 comments

As most of you may have known, the vmx file is the most important file at the back of a virtual machine. It defines the configurations of a virtual machine for example virtual hardware version, devices, disk files, etc. That is why it owns the virtual machine icon when you look at all the files behind a virtual machine with either datastore browser in vSphere Client or VMware Workstation/Fusion.

Given the importance of the vmx file, we don’t recommend anyone to manually modify it given that messing it up may corrupt a virtual machine. You can change the content indirectly from GUI and APIs. If you can change the virtual devices of a virtual machine, its vmx file is changed accordingly.

Beyond basic configuration entries, the vmx file can be extended to hold key/value pairs. A vmx file is really a text file with many lines of key/value pairs. By extending it, you can add extra lines of key/value pairs at the end of the file. Keep in mind that you should NOT add any key that is duplicated with predefined keys like “virtualHW.version.” As you already noticed, the key has the “.” delimiter as namespace pattern. You can start with your own namespace to avoid possible name clash.

How to Differentiate Folders in vSphere

January 28th, 2011 4 comments

As we know Folder is a container object in vSphere. It’s used to hold other managed objects in a similar way as directory holding files in an OS. There is an interesting question asking in VI Java API forum on how to tell whether a folder is vmFolder or hostFolder. BTW, you don’t see these two folders displayed in vSphere Client.

The questioner guessed correctly that you can find out by a folder’s childType property. Here is the documentation in API reference on the possible values of the childType property:

How to Delete Virtual Machine With vSphere API?

January 18th, 2011 3 comments

This question was asked at VI Java API forum recently and has been answered by the community.

There should be a “Destroy_Task()”-Method for each Managed Object, so also Virtual Machines…. Cheers, Joerg

As  Jörg Lew has correctly pointed out the solution, I would like to elaborate a bit more here.

If you are using VI Java API, the method name is destroy_Task(). The code is as simple as:

Difference of Two Common Privileges in vSphere API

January 17th, 2011 No comments

If you have used vSphere API and read its API Reference, you may have noticed two most commonly used privileges: System.View and System.Read. They are required in many methods. As their names suggest they are different, but what is the difference? It can be confusing for some people including me initially because it’s nowhere documented.

Here are some explanations after my talking to my colleague Jianping Yang who is the vCenter DB and Security guru.

Categories: vSphere API Tags:

vSphere Performance Counters for Monitoring ESX and vCenter

December 3rd, 2010 12 comments

VMware vSphere provides comprehensive performance metrics for your needs on performance monitoring and diagnosis. These stats are available through not only vSphere Client but also vSphere APIs. To understand the overall performance management concepts, you want to read this article: Fundamentals of vSphere Performance Management.
Once having the basics, you may wonder what types of stats are exposed. The following table summaries all the 315 performance counters available in vSphere 4.1. As you might have guessed, the information is generated using open source Sphere Java API and then imported into WordPress using WP-Table Reloaded. You can easily sort and search the table.

Update: Carter Shanklin and Luc Dekens have articles on performance counters as well:

Really Simple Guidelines to Write Great Code Samples

November 24th, 2010 2 comments

When a developer learns a new programming language or API, the first thing is probably to try out a HelloWorld sample. As said, real programmers don’t read documents. Although I don’t fully agree on that, it has some truth in it.

In my own experiences, I normally continue with other samples after HelloWorld one. When something is not quite clear, I check out the API reference or read some tutorials. Anyway, I am not telling you how to learn a new language or API, but trying to make a point here on the importance of code samples for the developers. In my opinion, samples are the most effective way to empower your users.

I think you would agree with me, there are too many bad samples. Here are some typical symptoms:

  1. Too much boilerplate code to a point that the code illustrating the API usage got buried. Typical boilerplate code includes extensive exception handling, GUI, logging, etc. Some samples even have a common library that could confuse your users totally.
  2. Too many API calls in one sample. You may need several APIs for a use case, but don’t aim one sample for multiple use cases.
  3. Too much object oriented. Object oriented programming is a best practice for application development. But it could confuse your developers sometimes.
  4. Dependencies on other APIs. To run the sample, your users need to install other libraries which may or may not need extra configuration or tuning. To understand the sample, users need to understand additional APIs. Extra burden, really!
  5. Of course, typical bad smells of programming which are not unique for samples. For example, bad naming, unnecessary global variables, using object attributes for passing values between methods, etc.

Now, how you can develop great samples? Besides the best practices writing great applications, you want to follow the following guidelines:

Wire Compatibility of Web Services

November 23rd, 2010 No comments

As a software professional, you may have heard about the source compatibility and binary compatibility. With the Web Services, a new type of compatibility came up. This is what I call wire compatibility. It’s not related to the programming but the XML messages passed on the wire. Since we don’t use XML directly but programming APIs, the wire compatibility surfaces and affects the source and binary compatibility.

Too abstract? You bet. Let’s pick up an example here. Because VMware vSphere API is defined in WSDL, I will use it in the following discussion.

In vSphere 4.1, the method PowerOnMultiVM_Task() gets an additional parameter called option typed as OptionValue array. The following are related parts in the WSDL:

<operation name="PowerOnMultiVM_Task">
  <input message="vim25:PowerOnMultiVM_TaskRequestMsg" />
  <output message="vim25:PowerOnMultiVM_TaskResponseMsg" />
  <fault name="RuntimeFault" message="vim25:RuntimeFaultFaultMsg"/>
<complexType name="PowerOnMultiVMRequestType">
    <element name="_this" type="vim25:ManagedObjectReference" />
    <element name="vm" type="vim25:ManagedObjectReference" maxOccurs="unbounded" />
    <element name="option" type="vim25:OptionValue" minOccurs="0" maxOccurs="unbounded" />

As you can see, the minOccurs of the option element is zero, meaning it’s optional. If you have an application built with 4.0 (no option parameter by then), the SOAP request still works. So it’s compatible on the wire.

Undocumented VI and vSphere API Methods: A Little History

October 25th, 2010 No comments

Most developers may have noticed the asynchronous methods in vSphere API like PowerOnVM_Task method, but not so many know their synchronous peers like PowerOnVM before 4.1. VMware vSphere API Reference doesn’t mention them at all. But you can find them in WSDL(check out the WSDL snippets at the end of this article).

There is an exception however. In VI Perl, these synchronous methods are exposed. There, you can choose which one to use. In vSphere Java API 2.0, these methods are exposed only in the stub layer but not the object layer. You don’t want to use stub methods directly when you can use objects, therefore I don’t talk much about it even in my book. Somehow I came across a question in the forum asking about this. So I think it may be good to share a little history and insight here.

The differences of these twin methods are minimal. They have exactly same parameters but different returns. The methods whose names include _Task suffix have Task returned. When you have the Task return, the operation may not yet be done at the server side. But with the Task object, you can track the progress, and even get the result data objects.

Really Simple Tricks to Speed up Your CLIs 10 Times Using vSphere Java API

October 15th, 2010 4 comments

I recently had a short discussion with my colleague on implementing CLIs with vSphere Java API. One problem is that if you have multiple commands to run, each of them connects to the server and authenticate over and over. You’d better remember to logout the connection each time after you are done, or leave many un-used connections on the server that could significantly slow down your ESX or vCenter server (read this blog for details).

You can have two solutions to this problem. The first one is to have your own “interpreter” command. After you type the command, it shows you prompt for more sub-commands. It’s very much like the “ftp” command in that sense. You can have subcommands like “login” or “open” or “connect” for connecting to a server, and other commands. The “interpreter” command can then hold the ServiceInstance object until it’s closed in the end.

You can save about 0.3 to 0.5 second on creating new HTTPS connection and login for each command after the first one. It’s not a big deal given that vSphere Java API has hugely reduced that time from 3 to 4 seconds with Apache AXIS. So if you switch to vSphere Java API, you get instant 10 time performance gain. Still, if you have many commands to run, it could be a decent saving.

With this solution, you can also implement batch mode in which you can save all your commands into a file and then execute them all with one command. You can find many examples like PowerShell which support interactive mode and batch mode.

Another solution is just having normal commands. The problem becomes how to avoid the authentication for each command after the first. Luckily we have something for you in the API.

Categories: vSphere API Tags: , ,

vSphere Java API Exceeds 10,000 Downloads

October 7th, 2010 No comments

October 6, 2010, is a historical moment for VI Java API project – the total downloads exceeded 10,000. It’s two days earlier than I had expected. After yesterday’s blog on the NetApp and Brocade’s testimonials, the daily downloads suddenly doubled. When I found the stats approaching 10,000, I tweeted “vSphere Java API 9,999 downloads now. Who want to be No. 10,000?” I wish I could have been able to track who made the No. 10,000. :-)

Strictly speaking, the total had exceeded 10,000 a while back. Besides typical downloads, you can also directly sync up with the subversion. As I checked the number there, it had passed 1,000 reads early this year.

Thanks to you all, the vSphere Java API community!

10,000 downloads is not a big deal for an application especially when it’s for end users. It’s a big deal for an API, and even bigger for an enterprise API which requires vSphere environment which not every developer has access to.

Besides the download number, I would like to brag these numbers:

NetApp and Brocade Opt for Open Source vSphere Java API

October 6th, 2010 No comments

I am very pleased to welcome NetApp and Brocade to the vSphere(VI) Java API poweredby page. Many thanks to Patric Chang and Katie Colbert from Brocade, and George Costea and Eric Forgette from NetApp for making this happen.

NetApp and Brocade have been using open source vSphere(VI) Java API for quite some time and each has several products shipped with this open source API. As you may recall from my previous blog on VMworld 2010, I did not talk about NetApp and Brocade because I hadn’t got written permission even though they had great shows out there. Please feel free to check them out at VMworld in Copenhagen next week.

I think the key takeaway from this is that vSphere Java API has been stable enough to be used by companies like NetApp and Brocade that demand highest quality of products. For one thing, you can prabably afford not connecting to networks for a little while, but for sure cannot afford messing up your data storage. NetApp and Brocade’s confidence in this API is the best testimonial on the quality and readiness of the API. There are many other even bigger companies are using the API as well. I will talk more about them later.