vSphere APIs for Guest Operating System Management: What’s Special and When to Use It?

This is a wrap-up post of recent series on vSphere guest operating system management APIs. If you missed them, here are a few links to related posts: [Note: these are not related to the vSphere Guest API.]

After reading these posts, you may wonder (at least, I did): Why should we use these guest operating system related APIs? Can’t we simply use well-known alternatives like HTTP to download/upload files, SSH/WMI to run programs, etc.? To some extents, you are right but not exactly.

Lost VMs or Containers? Too Many Consoles? Too Slow GUI? Time to learn how to "Google" and manage your VMware and clouds in a fast and secure HTML5 App.

For one thing, all these remote manageability to a guest operating system requires network connection to the guest OS. With vSphere APIs, it doesn’t. All you must have is networking connection to the ESXi on which the guest operating system is running. I think this is the biggest uniqueness of this APIs.

This does not mean you don’t need remote manageability. In fact, you do. The question is really when you should use which.

To answer the question, you have to first consider the accessibility of the management network to the ESXi. In general, this is a separate network dedicated for management, nothing else as a best practice. This limitation actually excludes lots of use cases already. It basically suggests that you use vSphere API only in management applications which can access management network.

The second consideration is the performance. In general, I felt, without apple to apple comparison, that the vSphere API is slow especially when moving files from and to a guest operating system. I think it’s in part due to the fact that ESXi is a middleman in between.

To sum up, the guest management APIs via vSphere is not meant to be used as a general approach for communicating with a guest operating system. Only these management applications with ESXi access should use these APIs. For other general purpose communications like download files, use whatever existing protocols/APIs out there as would you work with an operating system running directly on a physical machine.

This entry was posted in Software Development, vSphere API and tagged , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.


  1. Posted March 21, 2012 at 12:32 am | Permalink

    Hi Steve, thanks for the great work on the APIs!
    It seems the APIs allow a great deal of new modify access to the guest OS from vCenter – how does VMware intend to address this?

    For instance I can now craft a powershell script to remotely access all VMs as root (subverting our policy) /etc/ssh/sshd_config PermitRoot No

    I’d suggest ideally there would be a decentralized (secure) sudoers list of allowed guest operations to mitigate a vcenter compromise.


  2. Posted March 21, 2012 at 7:49 am | Permalink

    Hi Fletcher,
    I now see your comment! Thanks for reminding me on Twitter and trying it again!
    To gain access to an OS, you will need credential as would you log in the OS directly. I think you raised a good point to use sodo for better auditing.

  3. Svetozar
    Posted August 31, 2012 at 1:34 pm | Permalink

    Hi Steve,

    I like the VI Java API.
    I would like to use this “vSphere APIs for Guest Operating System managment” too.

    Do you have plans to share its source code ?


  4. lihlcnkr
    Posted October 7, 2012 at 8:33 pm | Permalink

    Hi Steve,
    It’s great job.

    but it have a issue.
    some vm, GuestOperationsManager works well, but after hot adding nic device to vm,
    it always throw GuestPermissionDenied exception.

    It’s like vmware issue, and because this issue, we can not use it: (
    Vcenter version is 5.0
    virtual machine guest OS is windows 2008 server R2

    are u have any idea?



  5. Posted October 8, 2012 at 6:57 pm | Permalink

    Hi lihlcnkr, interesting issue. what if you re-login? just wonder if you can work this around.


  6. lihlcnkr
    Posted October 8, 2012 at 9:14 pm | Permalink

    Hi Steve.
    thanks your reply.

    I tested re-login, restart VM guest OS, reset VM。
    after hot adding nic device, guest OS API is not working again.
    always throw GuestPermissionDenied exception.

    and after hot adding nic device, I try to use vSphere upgrade GuestOS VM tool , but it fail.

    So, it looks when hot adding nic device, GuestOS VM tool is not working well.

    I Tested it win 2003 and win 2008 server R2, It’s same result.

  7. Posted October 8, 2012 at 11:23 pm | Permalink

    Let’s try to understand what you found out. After hot adding NIC to a VM running Windows 2003 and Windows 2008 SR2, the guest OS API stops working correctly with GuestPermissionDenied exception even after you re-logining, restarting guest OS, reset VM. Am I right?
    Also, how about after removing the hot added NIC? I know it’s probably not acceptable in your case, but I am curious what would happen. What version of VMware Tools did you use? Had you upgrade the VMware Toosl before you hot adding NIC?

  8. lihlcnkr
    Posted October 9, 2012 at 1:13 am | Permalink

    Hi, Steve,

    Yes, It’s just you say.
    My VMware Tool version is 8.6.5, Build 652272

    and after removing the hot added NIC, it also happen.

  9. lihlcnkr
    Posted October 9, 2012 at 1:20 am | Permalink

    my environment is like this:

    VMware Tools: Version 8.6.5, Build 652272
    Vcenter Server: Version 5.0.0 Build 455964
    ESXi: Version 5.0.0 Build 623860

    before hot adding NIC device, I upgraded the VMware Toosl.
    and after removing the hot added NIC, it also happen.

    sorry for my poor english.


  10. Posted October 9, 2012 at 12:41 pm | Permalink

    Thanks Lihlcnkr, as you pointed out earlier, it’s mostly an issue with VMware Tools which carries real executions. You may want to contact VMware support on this issue. I believe part of VMware Tools is open sourced somewhere (search it), you also take a look there. But I wouldn’t recommend that unless you are really familiar with low level programming. Even so it’s still a lot of work.
    Thanks! Steve

  11. lihlcnkr
    Posted October 10, 2012 at 1:24 am | Permalink

    Hi, Steve.

    I contacted VMware support team, but they said for technical support, it need technical support license, it very expensive@@. and without support team, it can’t report bug directly.

    Anyway, Thanks very much.

  12. Posted October 10, 2012 at 10:49 am | Permalink

    Tech support license needed to file a bug with VMware? It doesn’t make senese to me. Maybe for a solution but not for filing a bug. Can you ask around on Twitter and cc me there? Thanks!


  13. lihlcnkr
    Posted October 11, 2012 at 9:42 pm | Permalink

    Hi, Steve

    I posted on twitter and vmware community.

    And I tested it again using vSphere powerCLI, and result is same.

    and I Installed open source vmware tool(open-vm-tools) on linux, and tested it.
    but looks open-vm-tools not working well with guest OS API.

    if I can’t resolve this issue, looks like I only use VIX or wmi&ssh for handle guest OS: (

    anyway, thanks your advise^^


Post a Comment

Your email is never published nor shared. Required fields are marked *


You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>


    My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__ doublecloud.org.

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.